1.164.3 Get methods

text_buffer <-sub: from=[int], to=[int] -> string

text_buffer <-contents: from=[int], size=[int] -> string

New string holding the text in the specified interval. text_buffer<-contents and text_buffer<-sub only differ in the interface. text_buffer<-sub is compatible to char_array<-sub and the preferred interface.

text_buffer <-convert: editor -> text_buffer

Translate an editor in its corresponding text_buffer. Notably useful when dealing with regular expressions (class regex) and class fragment which both define various methods that accept a text_buffer argument.

text_buffer <-find: from=int, for=string, times=[int], return=[{start,end}], exact_case=[bool], word=[bool] -> index=int

Search for a plain string. The arguments are in the table below. Values between parenthesis are the defaults.

from:	Start the search from this index
for:	Search for this string
times (1):	Return the nth occurrence
return (start):	start: first character, end: last character
exactcase (@on):	@off: case does not matter
wordmode (@off):	@on: find whole words only

Fails silently if the requested string cannot be found. See also class regex.

text_buffer <-find_all_fragments: test=[code] -> matching=chain

Return a new chain holding all associated fragments for which code could be executed successfully. @arg1 refers to the current fragment. See also chain<-find_all.

This method is commonly used to find fragments with a certain attribute overlapping the caret position:

...
get(TextBuffer, find_all_fragments,
    and(message(@arg1, overlap, Caret),
                @arg1?style == active),
        Fragments),
...

See also text_buffer->for_all_fragments, text_buffer<-find_fragment.

See also

class fragment

text_buffer <-find_fragment: test=code -> fragment

Find first fragment object in the text_buffer object that accepts code. See also text_buffer<-find_all_fragments, text_buffer->for_all_fragments.

text_buffer <-length: -> int

Number of characters in the text_buffer. A character is defined as a Unicode code point. Reads the value of text_buffer-size.

text_buffer <-matching_bracket: from=int, bracket=[char] -> index=int

Find index of a matching bracket. From is the index on which to start the scan. Assume from holds a text_buffer<-character bracket. If no bracket is specified, the text_buffer<-character at from is used. Specifying the bracket is useful to find the start of the bracketed environment point is in.

start_of_compound_statement(TB, Here, Start) :-
        get(TB, matching_bracket, Here, '}', Start).

If this method traps -while scanning-, a bracket mismatch (e.g. (hello}) it will generate a mismatched_bracket error. See class error and the predicate pce_catch_error/2.

See class syntax_table for defining brackets.

This method deals with string and comment. See text_buffer->in_string, text_buffer->in_comment and text_buffer<-scan.

text_buffer <-matching_quote: from=int, direction={forward,backward} -> index=int

Find quote matching the quote at from, scanning in the indicated direction. Class syntax_table defines quotes and escape sequences for quotes.

text_buffer <-scan: from=int, unit={character,word,line,sentence,paragraph,term}, times=[int], return=[{start,end}] -> index=int

Scan over a number of textual units. This function is used by class editor to determine the range of operations like editor->forward_word, editor->transpose_terms, etc. Arguments:

from	Index to start scanning
unit	Unit to scan for
times	Number of units to skip (<0: backwards)
return	start: start of unit, end: end of unit

For example,

get(TextBuffer, scan, 200, word, 2, start, Index)

will scan two words from index 200 and return the start of the 2nd word.

The definitions of the units is determined by the associated text_buffer<-syntax.

See also text_buffer<-matching_bracket.

text_buffer <-scan_syntax: from=[int], to=[int] -> tuple

Find syntactical state of position using the defined string and comment syntax from the associated text_buffer<-syntax object. Scanning starts at from, which is assumed to be outside comment and strings. The return-value is a tuple object, whose first part is a name indicating the syntactical category at to and whose second part denotes the start-position of this syntactical object.

Returned syntactical categories:

code

To is outside strings or comment

comment

To is inside a comment

string

To is inside a quoted string.

See also class syntax_table, text_buffer<-skip_comment, text_buffer<-skip_layout, text_buffer<-matching_bracket.

text_buffer <-size: -> int

Inherits description from: text_buffer-size

text_buffer <-skip_comment: from=int, to=[int], skip_layout=[bool] -> index=int

Assume from points to a layout character or the start of a comment. Return the first location not in a comment and not whitespace. If skip_layout is @off, just comment will be skipped.

See also text_buffer->in_comment and text_buffer<-skip_layout and class syntax_table.

text_buffer <-skip_layout: from=int, direction=[{forward,backward}], skip_newline=[bool] -> index=int

Scan the contents of the text_buffer object in the indicating direction, returning the first non-blank character. If skip_newline is @off, newlines will not be skipped.

See also text_buffer<-skip_comment, text_buffer<-scan, text_buffer<-find, regex->search.