DEC Text Processing Utility Reference Manual

Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

Contents

Index

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.

#2

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;

#2
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:

#3
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;

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;

SCANL

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

A pattern that may contain line breaks and that matches only characters that do not appear in the buffer, range, or string used as the parameter.

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

TPU$_NEEDTOASSIGN	ERROR	SCANL must appear on the right-hand side of an assignment statement.
TPU$_TOOFEW	ERROR	SCANL requires at least one argument.
TPU$_TOOMANY	ERROR	SCANL requires no more than one argument.
TPU$_ARGMISMATCH	ERROR	Argument to SCANL has the wrong type.
TPU$_CONTROLC	ERROR	You pressed Ctrl/C during the execution of SCANL.

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.

#1
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.

#2
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;

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;

SCROLL

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

An integer that indicates the number and direction of lines actually scrolled as a result of using SCROLL.

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

TPU$_CONTROLC	ERROR	You pressed Ctrl/C to stop scrolling.
TPU$_WINDNOTMAPPED	WARNING	You are trying to scroll an unmapped window.
TPU$_TOOFEW	ERROR	SCROLL requires at least one parameter.
TPU$_TOOMANY	ERROR	You specified more than two parameters.
TPU$_INVPARAM	ERROR	One or more of the specified parameters have the wrong type.

Examples

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

#1
SCROLL (main_window,+10)

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

#2
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;

SEARCH

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

The range that contains characters that match the pattern or string specified as a parameter.

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

TPU$_STRNOTFOUND	WARNING	Search for a string or pattern was unsuccessful.
TPU$_TOOFEW	ERROR	SEARCH requires at least two arguments.
TPU$_TOOMANY	ERROR	SEARCH accepts no more than four arguments.
TPU$_ARGMISMATCH	ERROR	One of the parameters to SEARCH is of the wrong type.
TPU$_INVPARAM	ERROR	One of the parameters to SEARCH is of the wrong type.
TPU$_BADKEY	WARNING	You specified an incorrect keyword to SEARCH.
TPU$_MINVALUE	WARNING	The integer parameter to SEARCH must be greater than or equal to --1.
TPU$_MAXVALUE	WARNING	The integer parameter to SEARCH must be less than or equal to 3.
TPU$_NOCURRENTBUF	ERROR	If you do not specify a buffer or range to search, you must position to a buffer before searching.
TPU$_CONTROLC	ERROR	You pressed Ctrl/C while SEARCH was executing.
TPU$_ILLPATAS	ERROR	The pattern to SEARCH contained a partial pattern assignment to a variable not defined in the current context.

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.

#1
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.

#2
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;

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;

SEARCH_QUIETLY

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.
To search a range for all occurrences of a pattern, you must define the range dynamically after each successful match; otherwise, SEARCH_QUIETLY 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

The range that contains characters that match the pattern or string specified as a parameter.

Description

The SEARCH_QUIETLY procedure looks for a particular arrangement of characters in a buffer or range and returns a range that contains those characters. Unlike the SEARCH built-in procedure, SEARCH_QUIETLY does not signal TPU$_STRNOTFOUND when it fails to find a string.
SEARCH_QUIETLY 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_QUIETLY does not find a match, the built-in returns 0 without signaling TPU$_STRNOTFOUND.
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_QUIETLY 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_QUIETLY 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_QUIETLY to move one character in the direction of the search if the character at the start position does not match. SEARCH_QUIETLY continues in this manner until it finds a match or reaches the bounds of the buffer or range.

Previous Next Contents Index

Copyright © Compaq Computer Corporation 1998. All rights reserved.
Legal

6020PRO_023.HTML

DEC Text Processing Utility Reference Manual

SCANL

Format

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

Parameters

buffer

range

string

FORWARD

REVERSE

Return Value

Description

Signaled Errors

Examples

SCROLL

Format

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

Parameters

window

integer1

Return Value

Description

Signaled Errors

Examples

SEARCH

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

BUFFER_BEGIN

BUFFER_END

LINE_BEGIN

LINE_END

PAGE_BREAK

pattern

REMAIN

string

UNANCHOR

FORWARD

REVERSE

EXACT

NO_EXACT

integer

buffer

range1

Return Value

Description

Signaled Errors

Examples

SEARCH_QUIETLY

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

BUFFER_BEGIN

BUFFER_END

LINE_BEGIN

LINE_END

PAGE_BREAK

pattern

REMAIN

string

UNANCHOR

FORWARD

REVERSE

EXACT

NO_EXACT

integer

buffer

range1

Return Value

Description

pattern := SCANL (

buffer
range
string
[[,

FORWARD
REVERSE
]])

[[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
]] ]])

[[ 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
]] ]])