variable KILL_ARRAY_SIZE

Synopsis

The size of the internal kill buffer array

Usage

Int_Type KILL_ARRAY_SIZE

Description

This variable contains the value of the size of the internal kill array of character strings. Any number from zero up to but not including the value of KILL_ARRAY_SIZE may be used as an argument in the functions that manipulate this array.

Notes

This variable is a read-only varaible and may not available on 16 bit systems.

See also

insert_from_kill_array , copy_region_to_kill_array , append_region_to_kill_array

function append_region_to_file

Synopsis

append_region_to_file

Usage

Integer append_region_to_file (String file);

Description

Appends a marked region to file returning number of lines written or \-1 on error. This does NOT modify a buffer visiting the file; however, it does flag the buffer as being changed on disk.

function append_region_to_kill_array

Synopsis

append_region_to_kill_array

Usage

Void append_region_to_kill_array (Integer n);

Description

This function appends the currently defined region to the contents of nth element, specified by n , of an internal array of character strings. Note: This function is not available on 16 bit systems.

See also

insert_from_kill_array , copy_region_to_kill_array

See also

KILL_ARRAY_SIZE

function bufsubstr

Synopsis

bufsubstr

Usage

String bufsubstr ();

Description

This function returns a string that contains the characters in the region specified by a mark and the current editing point. If the region crosses lines, the string will contain newline characters.

See also

insbuf , push_mark

function check_region

Synopsis

check_region

Usage

Void check_region (Integer ps);

Description

This function checks to see if a region is defined and may exchange the current editing point and the mark to define a canonical region. If the mark is not set, it signals an S-Lang error. A canonical region is one with the mark set earlier in the buffer than than the editing point. Always call this if using a region which requires such a situation. If the argument ps is non-zero, push_spot will be called, otherwise, ps is zero and it will not be called. As an example, the following function counts the number of lines in a region:
        define count_lines_region ()
        {
           variable n;
           check_region (1);   % spot pushed
           narrow ();
           n = what_line ();
           widen ();
           pop_spot ();
           return n;
         }

See also

markp , push_mark

function copy_region

Synopsis

copy_region

Usage

Void copy_region (String buf);

Description

This function may be used to copy a region defined by a mark and the current position to the buffered specified by the name buf . It does not delete the characters in region but it does pop the mark that determines the region.

See also

insbuf , bufsubstr , push_mark , pop_mark , bufferp

function copy_region_to_kill_array

Synopsis

copy_region_to_kill_array

Usage

Void copy_region_to_kill_array (Integer n);

Description

This function copies the currently defined region to the nth element, specified by n , of an internal array of character strings replacing what is currently there. Note: This function is not available on 16 bit systems.

See also

insert_from_kill_array , append_region_kill_array

See also

KILL_ARRAY_SIZE

function count_narrows

Synopsis

count_narrows

Usage

Integer count_narrows ();

Description

This function returns the narrow depth of the current buffer.

See also

narrow , widen , widen_buffer , push_narrow

function narrow

Synopsis

narrow

Usage

Void narrow ();

Description

This function may be used to restict editing to the region of lines between the mark and the editing point. The region includes the line containing the mark as well as the line at the current point. All other lines outside this region are completely inacessable without first lifting the restriction using the widen function. As a simple example, suppose that there is a function called print_buffer that operates on the entire buffer. Then the following function will work on a region of lines:
        define print_region ()
        {
           narrow ();
           print_buffer ();
           widen ();
        }
The narrow function will signal an error if the mark is not set. Note also that the narrow function may be used recursively in the sense that a narrowed region may be further restricted using the narrow function. For each narrow, the widen function must be called to lift each restriction.

See also

widen , narrow_to_region

function narrow_to_region

Synopsis

narrow_to_region

Usage

Void narrow_to_region (void);

Description

The narrow_to_region function behaves like the narrow function that narrow operates on lines and narrow_to_region restricts editing to only characters within the region.

See also

widen_region , narrow.

function pipe_region

Synopsis

pipe_region

Usage

Integer pipe_region (String cmd);

Description

The pipe_region function executes cmd in a separate process and sends the region of characters defined by the mark and the current point to the standard input of the process. It successful, it returns the exit status of the process. Upon failure it signals an error. Note: This function is only available for Unix and OS/2 systems.

See also

run_shell_cmd , push_mark

function pop_narrow

Synopsis

pop_narrow

Usage

Void pop_narrow ();

Description

The purpose of this function is to restore the last narrow context that was saved via push_narrow .

See also

push_narrow , widen , widen_buffer

function push_narrow

Synopsis

push_narrow

Usage

Void push_narrow ();

Description

This function saves the current narrow context. This is useful when one wants to restore this context after widening the buffer.

See also

pop_narrow , narrow , widen , widen_buffer

function translate_region

Synopsis

translate_region

Usage

Void translate_region (String_Type[256] a);

Description

This function uses the 256 element array of strings to translate the characters in a region based on the mapping defined by the array. If an array element is NULL , then the corresponding character will not be replaced. The translate_region function leaves the editing point at the end of the region.

Example

    variable a = String_Type[256];
    a['&'] = "&";
    a['<'] = "&lt;";
    a['>'] = "&gt;";
    a['$'] = "&dollar;";
    bob (); push_mark (); eob ();
    translate_region (a);
uses translate_region to replace the characters '&' , '<' , '>' , and '$' by the strings "&amp;" , "&lt;" , "&gt;" , and "&dollar;" , respectively.

See also

insert , delete, what_char , replace

function widen

Synopsis

widen

Usage

Void widen ();

Description

This function undoes the effect of narrow . Consult the documentation for narrow for more information.

See also

widen_region , narrow

function widen_buffer

Synopsis

widen_buffer

Usage

Void widen_buffer ();

Description

This function widens the whole buffer. If one intends to restore the narrow context after calling this function, the narrow context should be saved via push_narrow .

See also

narrow , widen , push_narrow , pop_narrow

function widen_region

Synopsis

widen_region

Usage

Void widen_region ();

Description

This function undoes the effect of narrow_to_region . Consult the documentation for narrow_to_region for more information.

See also

widen , narrow_to_region

function write_region_to_file

Synopsis

write_region_to_file

Usage

Integer write_region_to_file (String filename);

Description

This function may be used to write a region of the current buffer to the file specified by filename . It returns the number of lines written to the file or signals an error upon failure.

See also

write_buffer , append_region_to_file , push_mark

function xform_region

Synopsis

xform_region

Usage

Void xform_region (Integer how);

Description

This function changes the characters in the region in a way specified by the parameter how . This is an integer that can be any of of the following:
        'u'       Upcase_region
        'd'       Downcase_region
        'c'       Capitalize region
Anything else will change case of region.

See also

translate_region , define_case