Rangesets are a tool of the macro language to tag parts, or ranges, of the text, which shall be viewed as a group. A range is merely a contiguous range of characters between a start and an end position in the document, and a set of ranges belonging together is called a rangeset. So, a rangeset is nothing but an in general non-contiguous part of the text.
Rangesets can be assigned a background color to make them visible: characters within all ranges of a rangeset will have the background color of the rangeset. (If more than one rangeset includes a given character, its background color will be that of the most recently created rangeset which has a color defined.)
Applications of rangesets are for example:
Rangesets are manipulated only through macro routines. Rangesets must be created first using the rangeset_create() function, which will return an identifier for the newly-created (empty) rangeset. This identifier is then passed to the other rangeset functions to manipulate the rangeset. For example, ranges are added to a rangeset with the rangeset_add() function.
Notice that the ranges inside a rangeset do not have a particular identity. Only, they are given a (dynamically changing) numeric index, counting from 1, in the order of appearance in the text buffer. The ranges are adjusted when modifications are made to the text buffer: they shift around when characters are added or deleted staying with the original strings of characters. However, ranges within a set will coalesce if the characters between them are removed, or a new range is added to the set which bridges or overlaps others. For more on this, see "How rangesets change with modifications".
There is a limit to the number of rangesets which can exist at any time - currently up to 63 in each document. Care should be taken to destroy any rangesets which are no longer needed, by using the rangeset_destroy() function, if this limit is attained.
Rangesets can be named: this is useful for macros which need a fixed identification for rangesets which are used for the same purpose in different documents. Although a new rangeset's number is arbitrary, its name can be fixed. This is done using the rangeset_set_name() function. Note that rangeset names within a particular document may not be unique. For this reason, the rangeset_get_by_name() function returns an array of identifiers, which will be empty if the name has not been associated with a rangeset.
When changes are made to the document text, ranges within each set are altered with it, according to their behavioral mode. If changes are made outside of the ranges in a rangeset, each range simply maintains its size and adjusts its position to match the changes. When text within a range is deleted, the range's length is reduced by the same amount. When changes involving new text are made within a range of the set, or to one of the extremities of a range, different behaviours may be desirable. The rangeset_set_mode() function allows these modes to be chosen.
Note that the precise behaviour of these modes may change in future versions of XNEdit.
The available modes are:
maintain or ins_del - Both these modes have the same behaviour. New text added at the front of a range in a set is not added to the range; new text added within the range or at the end extends the range. Replacement overlapping an extremity of the set acts as if the new text were added first, then the old text deleted. This causes curtailment at the front of the range, extension at the end. Replacement of the full text of the range removes the range from the set. The default behaviour for a newly created rangeset is maintain.
del_ins - New text added at the front or end of a range in a set is not added to the range; new text added within the range extends the range. Replacement overlapping an extremity of the set acts as if the old text were deleted first, then the new text added. This causes curtailment at either end. Replacement of the full text of the range removes the range from the set.
include - New text added at the front or end of a range in a set extends the range, as does new text added within the range. Replacement overlapping an extremity of the set acts as if the new text were added first, then the old text deleted. This causes curtailment at the front of the range, extension at the end. Replacement of the full text of the range adds the new text to the range if the start position of the replacement is at the range's start point.
exclude - New text added at the front or end of a range in a set does not extend the range; new text added within the range extends the range. Replacement overlapping an extremity causes curtailment of the range. Replacement of the full text of the range removes the range from the set.
break - New text added at the front or end of a range in a set does not extend the range; new text added within the range will split the range. Replacement overlapping an extremity causes curtailment of the range. Replacement of the full text of the range removes the range from the set.
A rangeset is manipulated only through macro routines. Rangesets can easily become very large, and may exceed the capacity of the running process. Coloring relies on proper color names or specifications (such as the "#rrggbb" hexadecimal digit strings), and appropriate hardware support. If an invalid color name is given, the default background color is used instead. Behaviours set using rangeset_set_mode() are subject to change in future versions.
$rangeset_listarray of active rangeset identifiers, with integer keys starting at 0, in the order the rangesets were defined.
rangeset_create() rangeset_create( n )Creates one or more new rangesets. The first form creates a single range set and returns its identifier; if there are no rangesets available it returns 0. The second form creates n new rangesets, and returns an array of the rangeset identifiers with keys beginning at 0. If the requested number of rangesets is not available it returns an empty array.
rangeset_destroy( r ) rangeset_destroy( array )Deletes all information about a rangeset or a number of rangesets. The first form destroys the rangeset identified by r. The second form should be passed an array of rangeset identifiers with keys beginning at 0 (i.e. the same form of array returned by rangeset_create(n); it destroys all the rangesets appearing in the array. If any of the rangesets do not exist, the function continues without errors. Does not return a value.
rangeset_add( r ) rangeset_add( r, start, end ) rangeset_add( r, r0 )Adds to the rangeset r. The first form adds the range identified by the current primary selection to the rangeset, unless the selection is rectangular. The second form adds the range defined by the start and end positions given. The third form adds all ranges in the rangeset r0 to the rangeset r, and returns 0.
Returns the index of the newly-added range within the rangeset.
rangeset_subtract( r, [start, end] ) rangeset_subtract( r, r0 )Removes from the rangeset r. The first form removes the range identified by the current primary selection from the rangeset, unless start and end are defined, in which case the range they define is removed. The second form removes all ranges in the rangeset r0 from the rangeset r. Does not return a value.
rangeset_invert( r )Changes the rangeset r so that it contains all ranges not in r. Does not return a value.
rangeset_get_by_name( name )Returns an array of active rangeset identifiers, with integer keys starting at 0, whose name matches name.
rangeset_info( r )Returns an array containing information about the rangeset r. The array has the following keys: defined (whether a rangeset with identifier r is defined), count (the number of ranges in the rangeset), color (the current background color of the rangeset, an empty string if the rangeset has no color), name (the user supplied name of the rangeset, an empty string if the rangeset has no name), and mode (the name of the modify-response mode of the rangeset).
rangeset_range( r, [index] )Returns details of a specific range in the rangeset r. The range is specified by index, which should be between 1 and n (inclusive), where n is the number of ranges in the rangeset. The return value is an array containing the keys start (the start position of the range) and end (the end position of the range). If index is not supplied, the region returned is the span of the entire rangeset (the region starting at the start of the first range and ending at the end of the last). If index is outside the correct range of values, the function returns an empty array.
rangeset_includes( r, pos )Returns the index of the range in rangeset r which includes pos; returns 0 if pos is not contained in any of the ranges of r. This can also be used as a simple true/false function which returns true if pos is contained in the rangeset.
rangeset_set_color( r, color )Attempts to apply the color as a background color to the ranges of r. If color is at empty string, removes the coloring of r. No check is made regarding the validity of color: if the color is invalid (a bad name, or not supported by the hardware) this has unpredictable effects.
rangeset_set_name( r, name )Apply the name to the rangeset r.
rangeset_set_mode( r, type )Changes the behaviour of the rangeset r when modifications to the text buffer occur. type can be one of the following: "maintain" (the default), "break", "include", "exclude", "ins_del" or "del_ins". (These modes are described above.)