Document revision date: 19 July 1999

Format

pattern := SCAN ( {buffer |range |string} [[, {FORWARD |REVERSE} ]])

Parameters

buffer

An expression that evaluates to a buffer. SCAN does not match any of the characters that appear in the buffer.

range

An expression that evaluates to a range. SCAN does not match any of the characters that appear in the range.

string

An expression that evaluates to a string. SCAN does not match any of the characters that appear in the string.

FORWARD

A keyword that directs DECTPU to match characters in the forward direction. This is the default.

REVERSE

A keyword that directs DECTPU to match characters as follows: first, match characters in the forward direction until DECTPU finds a character that is a member of the set of characters. Next, return to the first character matched and start matching characters in the reverse direction until DECTPU finds a character that is in the set.

You can specify REVERSE only if you are using SCAN in the first element of a pattern being used in a reverse search. In all other contexts, specifying REVERSE has no effect.

The behavior enabled by REVERSE allows an alternate form of reverse search. By default, a reverse search stops as soon as a successful match occurs, even if there might have been a longer successful match in the reverse direction. By specifying REVERSE, you direct DECTPU not to stop matching in either direction until it has matched as many characters as possible.

Return Value

Description

The SCAN procedure returns a pattern that matches only characters that do not appear in the string, buffer, or range used as its parameter. SCAN matches as many characters as possible, stopping only if it finds a character that is present in its parameter or if it reaches the end of a line. If SCAN is part of a larger pattern, SCAN does not match a character if doing so prevents the rest of the pattern from matching.

SCAN does not cross line boundaries. To match a string of characters that may cross one or more line boundaries, use SCANL.

Signaled Errors

Examples

The following example stores a pattern that matches the longest string of characters that does not contain a, b, or c in pat1:

pat1 := SCAN ("abc") 
      

The following example identifies parenthesized text within a single line. It moves the editing point to the beginning of the parenthesized text, if it is found.

PROCEDURE user_find_parens 
 
   paren_text    := ANY("(') + SCAN (')"); 
   found_range   := SEARCH (paren_text, FORWARD, NO_EXACT); 
 
   IF found_range = 0   ! No parentheses. 
   THEN 
       MESSAGE  ("No parentheses found."); 
   ELSE 
       POSITION (found_range); 
   ENDIF; 
ENDPROCEDURE; 
 

 
 
      

The following example goes through the current file, deleting all characters that are not numbers, letters, or spaces:

PROCEDURE user_remove_odd_characters 
   LOCAL pat1, 
         odd_text; 
 
   pat1 := SCAN ("abcdefghijklmnopqrstuvwxyz 0123456789"); 
   POSITION (BEGINNING_OF (CURRENT_BUFFER)); 
   LOOP 
      odd_text := SEARCH_QUIETLY (pat1, FORWARD); 
      EXITIF odd_text = 0; 
      ERASE (odd_text); 
      POSITION (odd_text); 
   ENDLOOP; 
   POSITION (END_OF (CURRENT_BUFFER)); 
ENDPROCEDURE; 
 
      

Format

pattern := SCANL ( {buffer |range |string} [[, {FORWARD |REVERSE} ]])

Parameters

buffer

An expression that evaluates to a buffer. SCANL does not match any of the characters that appear in the buffer.

range

An expression that evaluates to a range. SCANL does not match any of the characters that appear in the range.

string

An expression that evaluates to a string. SCANL does not match any of the characters that appear in the string.

FORWARD

A keyword that directs DECTPU to match characters in the forward direction. This is the default.

REVERSE

A keyword that directs DECTPU to match characters as follows: first, match characters in the forward direction until DECTPU finds a character that is a member of the set of characters. Next, return to the first character matched and start matching characters in the reverse direction until DECTPU finds a character that is in the set.

You can specify REVERSE only if you are using SCANL in the first element of a pattern being used in a reverse search. In all other contexts, specifying REVERSE has no effect.

The behavior enabled by REVERSE allows an alternate form of reverse search. By default, a reverse search stops as soon as a successful match occurs, even if there might have been a longer successful match in the reverse direction. By specifying REVERSE, you direct DECTPU not to stop matching in either direction until it has matched as many characters as possible.

Return Value

Description

The SCANL procedure returns a pattern that matches a string of characters, including line breaks, none of which appear in the buffer, range, or string used as its parameter. The returned pattern contains as many characters and line breaks as possible.

SCANL is similar to SCAN in that it matches one or more characters that do not appear in the string, buffer, or range used as its parameter. Unlike SCAN, however, SCANL does not stop matching when it reaches the end of a line. Rather, it successfully matches the line end and continues trying to match characters on the next line.

If SCANL is part of a larger pattern, it does not match a character or line boundary if doing so prevents the rest of the pattern from matching.

SCANL must match at least one character.

Signaled Errors

Examples

The following example creates a pattern that matches a sentence. It assumes that a sentence ends in one of the following characters: a period (.), an exclamation point (!), or a question mark (?). The matched text does not include the punctuation mark ending the sentence.

sentence_pattern := any ("ABCDEFGHIJKLMNOPQRSTUVWXYZ") + scanl (".!?); 
 
      

The following example goes through the current buffer, erasing anything that is not a number. The only line breaks it leaves in the file are those between a line ending with a number and one beginning with a number.

PROCEDURE user_remove_non_numbers 
   LOCAL pat1, 
         non_number_region; 
 
   pat1 := SCANL ("0123456789"); 
 
   POSITION (BEGINNING_OF (CURRENT_BUFFER)); 

 
   LOOP 
      non_number_region := SEARCH_QUIETLY (pat1, FORWARD); 
      EXITIF non_number_region = 0; 
  
      ERASE (non_number_region); 
      POSITION (non_number_region); 
   ENDLOOP; 
 
   POSITION (BEGINNING_OF (CURRENT_BUFFER)); 
ENDPROCEDURE; 
 
      

Format

[[integer2 := ]]SCROLL (window [[,integer1]] )

Parameters

window

The window associated with the buffer whose text you want to scroll.

integer1

The signed integer value that indicates how many lines you want the text to scroll. If you supply a negative value for the second parameter, the lines of text scroll off the top of the screen, leaving the cursor closer to the beginning of the buffer. If you supply a positive value for the second parameter, the lines of text scroll off the bottom of the screen, leaving the cursor closer to the end of the buffer. If you specify 0 as the integer value, no scrolling occurs.

This parameter is optional. If you omit the second parameter, the text scrolls continuously until it reaches a buffer boundary or until you press a key. If the current direction of the buffer is forward, the text scrolls to the end of the buffer. If the current direction of the buffer is reverse, the text scrolls to the beginning of the buffer. If you press a key that has commands bound to it, the scrolling stops and DECTPU executes the commands bound to the key.

Return Value

Description

The SCROLL procedure moves the lines of text in the buffer up or down on the screen by the number of lines you specify. You can scroll text only in a visible window. If the window is not currently visible on the screen, DECTPU issues an error message.

During scrolling, the cursor does not move but stays positioned at the same relative screen location. The current editing point is different from the editing point that was current before you issued the SCROLL built-in procedure.

SCROLL optionally returns an integer that indicates the number and direction of lines actually scrolled. If you supply a negative value for the second parameter, the lines of text scroll off the bottom of the screen, leaving the cursor closer to the beginning of the buffer. If you supply a positive value for the second parameter, the lines of text scroll off the top of the screen, leaving the cursor closer to the end of the buffer. The value of integer2 may differ from what was specified in integer1.

SCROLL causes the screen to scroll immediately. Unlike screen updates, SCROLL does not wait to take effect until after the completion of a procedure.

If the buffer has been modified or the window display has altered since the last update, the window is updated before the scrolling operation begins.

SCROLL does not work in the following cases:

• If you have turned off the screen update flag with SET (SCREEN_UPDATE, OFF)
• If you used the /NODISPLAY qualifier when invoking DECTPU on an unsupported device
• If the window that you specify is not visible on the screen

When the scrolling is complete, the editing point (record and offset) is set to match the cursor position (screen line and column position).

After the scrolling stops, the cursor may be located to the right of the last character in the new current record, to the left of the left margin, or in the middle of a tab. In this instance, any DECTPU built-in procedure that requires a record offset (for example, CURRENT_OFFSET, MOVE_HORIZONTAL, MOVE_VERTICAL, MARK, and so on) causes the record to be padded with blanks to the cursor location.

If the screen you are using does not have hardware scrolling regions, the window being scrolled is repainted for each scroll that would have occurred. For instance, the statement SCROLL (my_window,3) repaints the window three times.

If you use SCROLL while positioned after the end of the buffer, SCROLL completes successfully and returns 0 as the amount scrolled.

Signaled Errors

Examples

The following example causes the text of the buffer that is mapped to the main window to scroll forward 10 lines:

SCROLL (main_window,+10) 
 

 
 
      

The following example scrolls the buffer MAIN until you press a key. The procedure returns the number of lines scrolled.

PROCEDURE user_scroll_buffer 
      
   LOCAL scrolled_lines; 
   
   MESSAGE ("Press any key to stop scrolling..."); 
   scrolled_lines := SCROLL (main_window); 
   dummy_key := READ_KEY; 
   RETURN scrolled_lines; 
ENDPROCEDURE; 
      

Format

[[range2 := ]]SEARCH ( {ANCHOR |BUFFER_BEGIN |BUFFER_END |LINE_BEGIN |LINE_END |PAGE_BREAK |pattern |REMAIN |string |UNANCHOR}

, {FORWARD |REVERSE} [[, {EXACT |NO_EXACT |integer} [[, { buffer |range1} ]] ]])

Parameters

ANCHOR

A keyword that directs SEARCH to start a search at the current character position. Use this keyword as part of a complex pattern.

BUFFER_BEGIN

A keyword used to match the beginning of a buffer.

BUFFER_END

A keyword used to match the end of a buffer.

LINE_BEGIN

A keyword used to match the beginning of a line.

LINE_END

A keyword used to match the end of a line.

PAGE_BREAK

A keyword used to match a form-feed character.

pattern

The pattern that you want to match.

REMAIN

A keyword that specifies a match starting at the current character and continuing to the end of the current line.

string

The string that you want to match.

UNANCHOR

A keyword that specifies that the next pattern element can match anywhere after the previous pattern element. Use this keyword as part of a complex pattern.

For more information on these keywords, refer to the individual descriptions of them in this chapter.

FORWARD

Indicates a search in the forward direction.

REVERSE

Indicates a search in the reverse direction.

EXACT

Indicates that the characters SEARCH is trying to match must be the same case and have the same diacritical markings as those in the string or pattern used as the first parameter to SEARCH.

NO_EXACT

Indicates that the characters SEARCH is trying to match need not be the same case nor have the same diacritical markings as those in the string or pattern used as the first parameter to SEARCH. NO_EXACT is the default value for the optional third parameter.

integer

Specifies how SEARCH should handle case and diacritical information if you want to match one attribute and ignore the other. DIGITAL recommends that you use the defined constants available for specifying this integer. The defined constants are as follows:

• TPU$K_SEARCH_CASE---Equivalent to the integer 1. This specifies that the search should match the case of the first parameter but be insensitive to the diacritical markings of the first parameter.
• TPU$K_SEARCH_DIACRITICAL---Equivalent to the integer 2. This specifies that the search should match the diacritical markings of the first parameter but be insensitive to the case of the first parameter.

buffer

The buffer in which to search. SEARCH starts at the beginning of the buffer when doing a forward search and at the end of the buffer when doing a reverse search.

range1

The range in which to search. SEARCH starts at the beginning of the range when doing a forward search and at the end of the range when doing a reverse search.

To search a range for all occurrences of a pattern, you must define the range dynamically after each successful match; otherwise, SEARCH positions to the beginning of the range and finds the same occurrence over and over. See the example section for a procedure that searches for all occurrences of a pattern in a range.

Return Value

Description

The SEARCH procedure looks for a particular arrangement of characters in a buffer or range and returns a range that contains those characters. SEARCH looks for text that matches the string, pattern, or keyword specified as its first parameter. If it finds such text, it creates a range that contains this text and returns it. If SEARCH does not find a match, SEARCH returns 0 and signals the error TPU$_STRNOTFOUND. To perform a search that does not signal an error when there is no match, use the SEARCH_QUIETLY built-in procedure.

The starting position for the search depends on the optional fourth parameter and the search direction. If you do not specify the fourth parameter, the search starts at the editing point.

If you specify a range for the fourth parameter, the search starts at the beginning of the range for a forward search or the end of the range for a reverse search. When searching a range, SEARCH matches only text inside the range. It does not look at text outside the range.

If you specify a buffer for the fourth parameter, the search starts at the beginning of the buffer for a forward search or the end of the buffer for a reverse search.

To determine whether the searched text contains a match, SEARCH examines the character at the starting position and attempts to match the character against the pattern, text, or keyword specified. By default, the search is unanchored. This allows SEARCH to move one character in the direction of the search if the character at the start position does not match. SEARCH continues in this manner until it finds a match or reaches the bounds of the buffer or range.

To prevent SEARCH from moving the starting position in the direction of the search, use the ANCHOR keyword when you define the pattern to be matched.

SEARCH does not change the current buffer or the editing point in that buffer.

For more information about searching, see the Guide to the DEC Text Processing Utility.

Signaled Errors

Examples

In the following example, if you search a buffer in which the string "Reflections of Monet" appears, this assignment statement stores the characters "Reflections of Monet" in the range user_range. The search finds a successful match even though the characters in the word "Monet" do not match in case because you specified NO_EXACT.

user_range := SEARCH ("Reflections of MONET", FORWARD, NO_EXACT) 
      

The following example searches the range the_range for all occurrences of the pattern "blue skies". If SEARCH finds the pattern, the procedure redefines the_range to begin after the end of the pattern just found. If the procedure did not redefine the range, SEARCH would keep finding the first occurrence over and over. The procedure reports the number of occurrences of the pattern.

PROCEDURE user_search_range 
 
   LOCAL found_count; 
 
   ON_ERROR 
       [TPU$_STRNOTFOUND, TPU$_CONTROLC]: 
       MESSAGE ( FAO ("Found !SL occurrences.", found_count)); 
       RETURN; 
      [OTHERWISE]:ABORT; 
   ENDON_ERROR; 
 
   found_count := 0; 
   the_pattern := "blue skies"; 
   the_range := CREATE_RANGE (BEGINNING_OF (CURRENT_BUFFER), 
                              END_OF (CURRENT_BUFFER), 
                              NONE); 
   found_range := CREATE_RANGE (BEGINNING_OF (CURRENT_BUFFER), 
                                BEGINNING_OF (CURRENT_BUFFER), 
                                NONE); 
    LOOP 
       the_range := CREATE_RANGE (END_OF (found_range), 
                                  END_OF (the_range), NONE); 
       found_range := SEARCH (the_pattern, FORWARD, NO_EXACT, 
                              the_range); 
    
       found_count := found_count + 1; 
    ENDLOOP; 
ENDPROCEDURE; 
      

Format

[[ range2 := ]] SEARCH_QUIETLY ( {ANCHOR |BUFFER_BEGIN |BUFFER_END |LINE_BEGIN |LINE_END |PAGE_BREAK |pattern |REMAIN |string |UNANCHOR }

, {FORWARD |REVERSE} [[, {EXACT |NO_EXACT |integer} [[, {buffer |range1} ]] ]])

Parameters

ANCHOR

A keyword that directs SEARCH_QUIETLY to start a search at the current character position.

BUFFER_BEGIN

A keyword used to match the beginning of a buffer.

BUFFER_END

A keyword used to match the end of a buffer.

LINE_BEGIN

A keyword used to match the beginning of a line.

LINE_END

A keyword used to match the end of a line.

PAGE_BREAK

A keyword used to match a form-feed character.

pattern

The pattern that you want to match.

REMAIN

A keyword that specifies a match starting at the current character and continuing to the end of the current line.

string

The string that you want to match.

UNANCHOR

A keyword that specifies that the next pattern element can match anywhere after the previous pattern element. Use this keyword as part of a complex pattern.

For more information on these keywords, refer to the individual descriptions of them in this chapter.

FORWARD

Indicates a search in the forward direction.

REVERSE

Indicates a search in the reverse direction.

EXACT

Indicates that the characters SEARCH_QUIETLY is trying to match must be the same case and have the same diacritical markings as those in the string or pattern used as the first parameter to SEARCH_QUIETLY.

NO_EXACT

Indicates that the characters SEARCH_QUIETLY is trying to match need not be the same case nor have the same diacritical markings as those in the string or pattern used as the first parameter to SEARCH_QUIETLY. NO_EXACT is the default value for the optional third parameter.

integer

Specifies how SEARCH_QUIETLY should handle case and diacritical information if you want to match one attribute and ignore the other. DIGITAL recommends that you use the defined constants available for specifying this integer. The defined constants are as follows:

• TPU$K_SEARCH_CASE---Equivalent to the integer 1. This specifies that the search should match the case of the first parameter but be insensitive to the diacritical markings of the first parameter.
• TPU$K_SEARCH_DIACRITICAL---Equivalent to the integer 2. This specifies that the search should match the diacritical markings of the first parameter but be insensitive to the case of the first parameter.

buffer

The buffer in which to search. SEARCH_QUIETLY starts at the beginning of the buffer when doing a forward search and at the end of the buffer when doing a reverse search.

range1

The range in which to search. SEARCH_QUIETLY starts at the beginning of the range when doing a forward search and at the end of the range when doing a reverse search.

---

Previous

Next

Contents

Index

	privacy and legal statement
6020PRO_023.HTML