Document revision date: 19 July 1999

Keywords are reserved words in DECTPU that have special meaning to the compiler.

To see a list of all DECTPU keywords, use the SHOW (KEYWORDS) built-in.

You use keywords in the following ways:

• As parameters for DECTPU built-in procedures. For example, the first parameter of the SET built-in procedure is always a keyword (for instance, PAD, SCROLLING, STATUS_LINE).
• As values returned by DECTPU built-in procedures, such as CURRENT_DIRECTION, KEY_NAME, LAST_KEY, READ_KEY, and GET_INFO. For example, the call GET_INFO (window, "status_video") has the following keywords as possible return values:
  • BLINK
  • BOLD
  • NONE
  • REVERSE
  • SPECIAL_GRAPHICS
  • UNDERLINE
• As pattern directives. The following keywords fall into this category:
  • ANCHOR
  • BUFFER_BEGIN
  • BUFFER_END
  • LINE_BEGIN
  • LINE_END
  • PAGE_BREAK
  • REMAIN
  • UNANCHOR
  
  These keywords, which behave like built-in procedures, are described in the DEC Text Processing Utility Reference Manual.
• To specify the DECTPU data types (BUFFER, MARKER, LEARN, and so on).
• To report warning or error status conditions (TPU$_BADMARGINS, TPU$_CREATEFAIL, TPU$_NOEOBSTR, and so on).
• To pass the names of keys to DECTPU procedures.

Table 3-1 shows the correspondence between keywords used as DECTPU key names and the keys on the VT400, VT300, VT200, and VT100 series of keyboards. You do not have to define a key or control sequence just because there is a DECTPU keyword for the key or sequence.

Table 3-1 Keywords Used for Key Names

DECTPU Key Name	VT400, VT300, VT200 Series Key	VT100 Key
PF1	PF1	PF1
PF2	PF2	PF2
PF3	PF3	PF3
PF4	PF4	PF4
KP0, KP1, ..., KP9	0, 1,..., 9	0, 1,..., 9
Period	.	.
Comma	,	,
Minus	--	--
Enter	Enter	Enter
Up	Up arrow	Up arrow
Down	Down arrow	Down arrow
Left	Left arrow	Left arrow
Right	Right arrow	Right arrow
E1	Find / E1
E2	Insert Here / E2
E3	Remove / E3
E4	Select / E4
E5	Prev Screen / E5
E6	Next Screen / E6
Help	Help / F15
Do	Do / F16
F6, F7,..., F20	F6, F7,..., F20
NULL_KEY	Ctrl/space	Ctrl/space
TAB_KEY	Tab	Tab
RET_KEY	Return	Return
DEL_KEY	< X|	Delete
LF_KEY	Ctrl/J	Line feed
BS_KEY	Ctrl/H	Backspace
Ctrl_A_KEY	Ctrl/A 1	Ctrl/A 1
Ctrl_B_KEY	Ctrl/B	Ctrl/B
.	.	.
.	.	.
.	.	.
Ctrl_Z_KEY	Ctrl/Z	Ctrl/Z

The OpenVMS terminal driver handles the following keys as special cases. DIGITAL recommends that you avoid defining the following control characters and function key:

• Ctrl/C
• Ctrl/O
• Ctrl/Q
• Ctrl/S
• Ctrl/T
• Ctrl/X
• Ctrl/Y
• F6

A learn sequence is a collection of DECTPU keystrokes for use later. The LEARN_BEGIN built-in procedure starts collecting keystrokes; the LEARN_END built-in procedure stops the collection of keystrokes and returns a value of the learn data type as a result. The following example assigns a learn data type to the variable x:

LEARN_BEGIN (EXACT); . . . x := LEARN_END;

All keystrokes that you enter between the LEARN_BEGIN and LEARN_END built-in procedures are stored in the variable x. The EXACT keyword specifies that, when the learn sequence is replayed, the input (if any) for the built-in procedures READ_CHAR, READ_KEY, and READ_LINE (if used in the learn sequence) will be the same as the input entered when the learn sequence was created. If you specify NO_EXACT, a replay of a learn sequence containing keys that invoke the built-in procedures READ_LINE, READ_KEY, or READ_CHAR looks for new input.

For more information on replaying a learn sequence, see LEARN_BEGIN and LEARN_END in the DEC Text Processing Utility Reference Manual.

You can use the LEARN_ABORT built-in procedure to interrupt the execution of a learn sequence. For information on using LEARN_ABORT, see LEARN_ABORT in the DEC Text Processing Utility Reference Manual.

To enable your user-written DECTPU procedures to work successfully with learn sequences, you must observe the following coding rules when you write procedures that you or someone else can bind to a key:

• The procedure should return true or false, as needed, to indicate whether execution of the procedure completed successfully.
• The procedure should invoke the LEARN_ABORT built-in in case of error.

These practices help prevent a learn sequence from finishing if the learn sequence calls the user-written procedure and the procedure is not executed successfully.

A procedure that does not explicitly return a value returns 0 by default, thus aborting a learn sequence.

A marker is a reference point in a buffer. You can think of a marker as a "place holder." To create a marker, use the MARK built-in procedure.

The following example assigns a value of the marker data type to the variable x:

x := MARK (NONE);

After this statement is executed, the variable x contains the character position where the editing point was located when the statement was executed. The editing point is the point in a buffer at which most editing operations are carried out.

You can cause a marker to be displayed with varying video attributes (BLINK, BOLD, REVERSE, UNDERLINE). The NONE keyword in the preceding example specifies that the marker does not have any video attributes.

When you use the MARK built-in, DECTPU puts the marker on the buffer's editing point. The editing point is not necessarily the same as the window's cursor position.

A marker can be either free or bound. Free markers are useful for establishing place marks in locations that do not contain characters, such as locations before the beginning of a line, after the end of a line, in the white space created by a tab, or below the end of a buffer. By placing a free marker in such a location, you make it possible to establish the editing point at that location without inserting padding space characters that could complicate later operations such as FILL.

A marker is bound if there is a character in the position marked by the editing point at the time you create the marker. A bound marker is tied to the character on which it is created. If you move the character to which a marker is bound, the marker moves with the character. If you delete the character to which a marker is bound, DECTPU binds the marker to the nearest character or to the end of the line if that is closer than any character.

To force the creation of a bound marker, use the MARK built-in with any of its parameters except FREE_CURSOR. This operation creates a bound marker even if the editing point is beyond the end of a line, before the beginning of a line, in the middle of a tab, or beyond the end of a buffer. To create a bound marker in a location where there is no character, DECTPU fills the space between the marker and the nearest character with padding space characters.

A marker is usually free if all of the following conditions are true:

• You used MARK (FREE_CURSOR) to create the marker.
• There was no character in the position marked by the editing point at the time you created the marker.
• Nothing has happened to cause the marker to become bound.

The following paragraphs explain each of these conditions in more detail.

If you use the MARK (FREE_CURSOR) built-in procedure and there is a character in the position marked by the editing point, the marker is bound even though you specify otherwise. Once a marker becomes bound, it remains bound throughout its existence. To determine whether a marker is bound, use the following GET_INFO call:

GET_INFO (marker_variable, "bound");

DECTPU keeps track of the location of a free marker by measuring the distance between the marker and the character nearest to the marker. If you move the character from which DECTPU measures distance to a free marker, the marker moves too. DECTPU preserves a uniform distance between the character and the marker. If you collapse white space that contains one or more free markers (for example, if you delete a tab or use the APPEND_LINE built-in procedure), DECTPU preserves the markers and binds them to the nearest character.

If you use the POSITION built-in procedure to establish the editing point at a free marker, the marker remains free and the editing point is also said to be free; that is, the editing point is not bound to a character. Some operations cause DECTPU to fill the space between a free marker and the nearest character with padding space characters, thereby converting the free marker to a bound marker. For example, if you type text into the buffer when the editing point is detached, DECTPU inserts padding space characters between the nearest character and the editing point. Using any of the following built-in procedures when the editing point is detached also causes DECTPU to perform padding:

• APPEND_LINE
• COPY_TEXT
• CURRENT_CHARACTER
• CURRENT_LINE
• CURRENT_OFFSET
• ERASE_CHARACTER
• ERASE_LINE
• MOVE_HORIZONTAL
• MOVE_TEXT
• MOVE_VERTICAL
• SELECT
• SELECT_RANGE
• SPLIT_LINE

Example 3-1 shows how to suppress padding while using these built-ins. The example assumes that the editing point is free. The code in this example assigns the string representation of the current line to the variable bat without adding padding blanks to the buffer.

Example 3-1 Suppressing the Addition of Padding Blanks

x := MARK (FREE_CURSOR); ! Places a marker at the ! detached editing point POSITION (SEARCH_QUIETLY ("",FORWARD)); ! Moves the active editing ! point to the nearest ! text character bat := CURRENT_LINE; ! Assigns the string ! representation of the ! current line to bat without ! adding padding blanks POSITION (x); ! Returns the active editing ! point to the free marker

To remove a marker, use the DELETE built-in procedure with the marker as a parameter. For example, the following statement deletes the marker mark1:

DELETE (mark1);

You can also set all variables referring to the marker to refer to something else, for example, tpu$k_unspecified or 0. The following statement sets the variable mark1 to 0:

mark1 := 0;

If mark1 were the only variable referring to a marker, that marker would be deleted upon execution of the previous statement.

The marker data type is returned by the MARK, SELECT, BEGINNING_OF, END_OF, and GET_INFO built-in procedures.

3.7 Pattern Data Type

A pattern is a structure that DECTPU uses when it searches for text in a buffer. You can think of a pattern as a template that DECTPU compares to the searched text, looking for a match between the pattern and the searched text. You can use a variable whose data type is the pattern data type when you specify the first parameter to the SEARCH and SEARCH_QUIETLY built-in procedures.

To create a pattern, use DECTPU pattern operators (+, &, |, @) to connect any of the following:

• String constants
• String variables
• Pattern variables
• Calls to pattern built-in procedures
• The following keywords:
  • ANCHOR
  • BUFFER_BEGIN
  • BUFFER_END
  • LINE_BEGIN
  • LINE_END
  • PAGE_BREAK
  • REMAIN
  • UNANCHOR
• Parentheses (to enclose expressions)

Patterns can be simple or complex. A simple pattern can be composed of sets of strings connected by one of the pattern operators. The following example indicates that pat1 matches either the string "abc" or the string "def":

pat1 := "abc" | "def";

If you connect two strings with the + operator, the result is a string rather than a pattern. For example, the following statement gives pat1 the string data type:

pat1 := "abc" + "def";

The SEARCH and SEARCH_QUIETLY built-in procedures accept such a string as a parameter.

A more complex pattern uses pattern built-in procedures and existing patterns to form a new pattern. The following example indicates that pat2 matches the string "abc" followed by the longest string that contains any characters from the string "12345":

pat2 := "abc" + SPAN ("12345");

Pat2 matches the string "abc123" in the text string "xyzabc123def".

Following are additional examples of statements that create complex patterns:

pat1 := any( "abc" ); pat2 := line_begin + remain; pat3 := "abc" | "xes"; pat4 := pat1 + "12"; pat5 := "xes" @ var1; pat6 := "abc" & "123";

You can assign a pattern to a variable and then use the variable as a parameter for the SEARCH or SEARCH_QUIETLY built-in procedure. SEARCH or SEARCH_QUIETLY looks for the character sequences specified by the pattern that you use as a parameter. If SEARCH or SEARCH_QUIETLY finds a match for the pattern, the built-in returns a range that contains the text that matches the pattern. You can assign the range to a variable.

The following example uses strings and pattern operators to create a pattern that is stored in the variable my_pat. The variable is then used with the SEARCH or SEARCH_QUIETLY built-in procedure in a forward direction. If SEARCH or SEARCH_QUIETLY finds a match for my_pat, the range of matching text is stored in the variable match_range. The POSITION built-in procedure causes the editing point to move to the beginning of match_range.

my_pat := ("abc" | "def") + "::"; match_range := SEARCH (my_pat, FORWARD); POSITION (match_range);

3.7.1 Using Pattern Built-In Procedures and Keywords

The following built-in procedures return values of the pattern data type:

• ANY
• ARB
• MATCH
• NOTANY
• SCAN
• SCANL
• SPAN
• SPANL

See the DEC Text Processing Utility Reference Manual for a complete description of these pattern built-in procedures.

3.7.2 Using Keywords to Build Patterns

You can use the following keywords as the first argument to the SEARCH or SEARCH_QUIETLY built-in procedures. You can also use them to form patterns in expressions that use the pattern operators. See the DEC Text Processing Utility Reference Manual for a complete description of these keywords.

• ANCHOR
• BUFFER_BEGIN
• BUFFER_END
• LINE_BEGIN
• LINE_END
• PAGE_BREAK
• REMAIN
• UNANCHOR

The following are the DECTPU pattern operators:

• Concatenation operator (+)
• Link operator (&)
• Alternation operator (|)
• Partial pattern assignment operator (@)

The pattern operators are equal in DECTPU's precedence of operators. For more information on the precedence of DECTPU operators, see Chapter 4. Pattern operators associate from left to right. Thus, the following two DECTPU statements are identical:

pat1 := a + b & c | d @ e; pat1 := (((a + b) & c) | d) @ e;

In addition to the pattern operators, you can use two relational operators, equal (=) and not equal (<>), to compare patterns.

The following sections discuss the pattern operators.

3.7.3.1 + (Pattern Concatenation Operator)

The concatenation operator (+) tells SEARCH or SEARCH_QUIETLY that text matching the right pattern element must immediately follow the text matching the left pattern element in order for the complete pattern to match. In other words, the concatenation operator specifies a search in which the right pattern element is anchored to the left. For example, the following pattern matches only if there is a line in the searched text that ends with the string abc.

pat1 := "abc" + line_end;

If SEARCH or SEARCH_QUIETLY finds such a line, the built-in returns a range that contains the text abc and the end of the line.

DIGITAL recommends that you use the concatenation operator rather than the link operator unless you specifically require the link operator.

	privacy and legal statement
6018PRO_004.HTML