The size of the internal kill buffer array
Int_Type KILL_ARRAY_SIZE
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.
This variable is a read-only varaible and may not available on 16 bit systems.
insert_from_kill_array, copy_region_to_kill_array, append_region_to_kill_array
append_region_to_file
Integer append_region_to_file (String file);
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.
append_region_to_kill_array
Void append_region_to_kill_array (Integer n);
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.
insert_from_kill_array, copy_region_to_kill_array
KILL_ARRAY_SIZE
bufsubstr
String bufsubstr ();
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.
insbuf, push_mark
check_region
Void check_region (Integer ps);
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;
}
markp, push_mark
copy_region
Void copy_region (String buf);
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.
insbuf, bufsubstr, push_mark, pop_mark, bufferp
copy_region_to_kill_array
Void copy_region_to_kill_array (Integer n);
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.
insert_from_kill_array, append_region_kill_array
KILL_ARRAY_SIZE
count_narrows
Integer count_narrows ();
This function returns the narrow depth of the current buffer.
narrow, widen, widen_buffer, push_narrow
narrow
Void narrow ();
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.
widen, narrow_to_region
narrow_to_region
Void narrow_to_region (void);
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.
widen_region, narrow.
pipe_region
Integer pipe_region (String cmd);
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.
run_shell_cmd, push_mark
pop_narrow
Void pop_narrow ();
The purpose of this function is to restore the last narrow
context that was saved via push_narrow
.
push_narrow, widen, widen_buffer
push_narrow
Void push_narrow ();
This function saves the current narrow context. This is useful when one wants to restore this context after widening the buffer.
pop_narrow, narrow, widen, widen_buffer
translate_region
Void translate_region ();
This function uses the global character array TRANSLATE_ARRAY
to
modify the characters in a region based on the mapping defined by the
array. The only restriction is that the newline character cannot be
mapped. This example
define swap_a_and_b ()
{
variable i;
_for (0; 255, 1)
{
i = ();
TRANSLATE_ARRAY[i] = i;
}
TRANSLATE_ARRAY['a'] = 'b';
TRANSLATE_ARRAY['b'] = 'a';
bob (); push_mark (); eob ();
translate_region ();
}
uses translate_region
to swap the 'a'
and 'b'
characters in the
current buffer.
insert, delete, what_char
TRANSLATE_ARRAY
widen
Void widen ();
This function undoes the effect of narrow
. Consult the documentation
for narrow
for more information.
widen_region, narrow
widen_buffer
Void widen_buffer ();
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
.
narrow, widen, push_narrow, pop_narrow
widen_region
Void widen_region ();
This function undoes the effect of narrow_to_region
. Consult the
documentation for narrow_to_region
for more information.
widen, narrow_to_region
write_region_to_file
Integer write_region_to_file (String filename);
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.
write_buffer, append_region_to_file, push_mark
xform_region
Void xform_region (Integer how);
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.
translate_region, define_case