* language *
NEdit Macro

$
$ - NEdit built-in globals
Macro language:
        $1 ... $9, $args, $n_args - function arguments
        $empty_array, $sub_sep
Document text positions:
        $cursor, $column, $line
        $top_line
        $selection_left, $selection_right
        $selection_start, $selection_end
        $text_length
File information:
        $file_path, $file_name
        $file_format
        $read_only, $modified, $locked
Window information:
        $language_mode
        $highlight_syntax
        $n_panes, $active_pane, $display_width, $n_display_lines
        $font_name, $font_name_bold, $font_name_bold_italic, $font_name_italic
        $max_font_width, $min_font_width
        $backlight_string
Other settings:
        $auto_indent
        $overtype_mode
        $use_tabs, $em_tab_dist, $tab_dist
        $incremental_backup, $make_backup_copy
        $incremental_search_line, $statistics_line
        $show_matching, $match_syntax_based
        $show_line_numbers
        $wrap_text, $wrap_margin
Miscellaneous:
        $calltip_ID
        $server_name
Return values:
        $search_end
        $string_dialog_button
        $list_dialog_button
        $read_status
        $shell_cmd_status

* alias *
$1 ... $9, $args, $n_args - function arguments
$1
$2
$3
$4
$5
$6
$7
$8
$9
$args
$n_args

$1 ... $9, $args, $n_args - function arguments
$1 ... $9, $args, $n_args - function arguments
Function arguments are accessible either as the shorthand
symbols $1 to $9, useful when the number of arguments is
limited, or as the special array $args. The number of
arguments passed can be determined using $n_args or $args[].

$active_pane
$active_pane
Index of the current pane.

$auto_indent
$auto_indent
Contains the current preference for auto indent. Can be  "off", "on" or "auto".

$calltip_ID
$calltip_ID
Equals the ID of the currently displayed calltip, or 0 if no calltip is being
displayed.

$cursor
$cursor
Position of the cursor in the current window.

$column
$column
Column number of the cursor position in the current window.

$display_width
$display_width
Width of the current pane in pixels.

$em_tab_dist
$em_tab_dist
If tab emulation is turned on in the Tabs... dialog of the Preferences menu,
value is the distance between emulated tab stops. If tab emulation is turned
off, value is -1.

$empty_array
$empty_array
An array with no elements. This can be used to initialize an array to an empty
state.

$file_format
$file_format
Current newline format that the file will be saved with. Can be "unix", "dos"
or "macintosh".

$file_name
$file_name
Name of the file being edited in the current window, stripped of directory
component.

$file_path
$file_path
Directory component of file being edited in the current window.

$font_name
$font_name
Contains the current plain text font name.

$font_name_bold
$font_name_bold
Contains the current bold text font name.

$font_name_bold_italic
$font_name_bold_italic
Contains the current bold-italic text font name.

$font_name_italic
$font_name_italic
Contains the current italic text font name.

$highlight_syntax
$highlight_syntax
Whether syntax highlighting is turned on.

$incremental_backup
$incremental_backup
Contains 1 if incremental auto saving is on, otherwise 0.

$incremental_search_line
$incremental_search_line
Has a value of 1 if the preference is selected to always show the incremental
search line, otherwise 0.

$language_mode
$language_mode
Name of language mode set in the current window.

$line
$line
Line number of the cursor position in the current window.

$locked
$locked
True if the file has been locked by the user.

$make_backup_copy
$make_backup_copy
Has a value of 1 if original file is kept in a backup file on save, otherwise
0.

$max_font_width
$max_font_width
The maximum font width of all the active styles. Syntax highlighting styles are
only considered if syntax highlighting is turned on.

$min_font_width
$min_font_width
The minimum font width of all the active styles. Syntax highlighting styles are
only considered if syntax highlighting is turned on.

$modified
$modified
True if the file in the current window has been modified and the modifications
have not yet been saved.

$n_display_lines
$n_display_lines
The number of lines visible in the currently active pane.

$n_panes
$n_panes
The number of panes in the current window.

$overtype_mode
$overtype_mode
True if in Overtype mode.

$read_only
$read_only
True if the file is read only.

$selection
$selection_start, $selection_end
$selection_left, $selection_right

* alias *
$selection_start, $selection_end
$selection_start
$selection_end

$selection_start, $selection_end
$selection_start, $selection_end
Beginning and ending positions of the primary selection in the current window,
or -1 if there is no text selected in the current window.

* alias *
$selection_left, $selection_right
$selection_left
$selection_right

$selection_left, $selection_right
$selection_left, $selection_right
Left and right character offsets of the rectangular (primary) selection in the
current window, or -1 if there is no selection or it is not rectangular.

$server_name
$server_name
Name of the current NEdit server.

$show_line_numbers
$show_line_numbers
Whether line numbers are shown next to the text.

$show_matching
$show_matching
Contains the current preference for showing matching pairs, such as "[]" and
"{}" pairs. Can be "off", "delimiter", or "range".

$match_syntax_based
$match_syntax_based
Whether pair matching should use syntax information, if available.

$statistics_line
$statistics_line
Has a value of 1 if the statistics line is shown, otherwise 0.

$sub_sep
$sub_sep
Contains the value of the array sub-script separation string.

$tab_dist
$tab_dist
The distance between tab stops for a hardware tab character, as set in the
Tabs... dialog of the Preferences menu.

$text_length
$text_length
The length of the text in the current window.

$top_line
$top_line
The line number of the top line of the currently active pane.

$use_tabs
$use_tabs
Whether the user is allowing the NEdit to insert tab characters to maintain
spacing in tab emulation and rectangular dragging operations. (The setting of
the "Use tab characters in padding and emulated tabs" button in the Tabs...
dialog of the Preferences menu.)

$wrap_margin
$wrap_margin
The right margin in the current window for text wrapping and filling.

$wrap_text
$wrap_text
The current wrap text mode. Values are "none", "auto" or "continuous".

$backlight_string
$backlight_string
The current value of the window's backlighting specification. This is empty if
backlighting is turned off. It can be changed through calls to the built-in
macro function set_backlight_string().

append_file
append_file(string, filename)
Appends a string to a named file. Returns 1 on successful write, or 0 if
unsuccessful.

beep
beep()
Ring the bell.

calltip
calltip(text_or_key [, pos [, mode [, position_modifier ...]]])
Pops up a calltip. 
<pos> is an optional position in the buffer where the tip will be displayed. 
    Passing -1 for <pos> is equivalent to not specifying a position, and it
    guarantees that the tip will appear on-screen somewhere even if the cursor
    is not.  The upper-left corner of the calltip will appear below where the
    cursor would appear if it were at this position.
<mode> is one of:
    "tipText" (default): displays the text as-is
    "tagKey": uses it as the key to look up a tag, then converts the tag to a
              calltip
    "tipKey": uses the text as the key to look up a calltip, then falls back
              to "tagKey" behavior if that fails
    You'll usually use "tipKey" or "tipText".
<position_modifier> modifies the placement of the calltip relative to the
    cursor position (or <pos>) - you may have more than one of:
    "center" or "right": aligns the center or right edge of the calltip with
              the position ("center" and "right" may not both be used.)
    "above" places the calltip above the position
    "strict" does not allow the calltip to move from its position in order to
              avoid going off-screen or obscuring the cursor.
Returns the ID of the calltip if it was found and/or displayed correctly, 0
otherwise.

clipboard_to_string
clipboard_to_string()
Returns the contents of the clipboard as a macro string. Returns empty string
on error.

dialog
dialog(message, btn_1_label, btn_2_label, ...)
Pop up a dialog for querying and presenting information to the user. First
argument is a string to show in the message area of the dialog. Additional
optional arguments represent labels for buttons to appear along the bottom of
the dialog. Returns the number of the button pressed (the first button is number
1), or 0 if the user closed the dialog via the window close box.

focus_window
focus_window(window_name)
Sets the window on which subsequent macro commands operate. window_name can be
either a fully qualified file name, or one of "last" for the last window
created, or "next" for the next window in the chain from the currently focused
window (the first window being the one returned from calling
focus_window("last"). Returns the name of the newly-focused window, or an empty
string if the requested window was not found.

get_character
get_character(position)
Returns the single character at the position indicated by the first argument to
the routine from the current window.

get_range
get_range(start, end)
Returns the text between a starting and ending position from the current
window.

get_selection
get_selection()
Returns a string containing the text currently selected by the primary
selection either from the current window (no keyword), or from anywhere on the
screen (keyword "any").

getenv
getenv(name)
Gets the value of an environment variable.

kill_calltip
kill_calltip([calltip_ID])
Kills any calltip that is being displayed in the window in which the macro is
running.  If there is no displayed calltip this does nothing.  If a calltip ID
is supplied then the calltip is killed only if its ID is calltip_ID.

length
length(string)
Returns the length of a string

* alias *
list_dialog
$list_dialog_button
list_multisel_dialog

list_dialog
list_dialog(message, text, btn_1_label, btn_2_label, ...)
list_multisel_dialog(message, text, btn_1_label, btn_2_label, ...)
Pop up a dialog for prompting the user to choose a single line or multiple lines
from the given text string. The first argument is a message string to be used as
a title for the fixed text describing the list. The second string provides the
list data: this is a text string in which list entries are separated by newline
characters. Additional optional arguments represent labels for buttons to appear
along the bottom of the dialog.
  - list_dialog() returns a string containing the single line of text selected
    by the user (without any newline separator) or the empty string if none was
    selected.
  - list_multisel_dialog() returns a string containing all lines of text
    selected by the user separated (but not terminated) by newline characters.
Both functions return the number of the button pressed (the first button is
number 1), in $list_dialog_button. If the user closes the dialog via the window
close box or by the escape key, the function returns the empty string, and
$list_dialog_button returns 0.

max
max(n1, n2, ...)
Returns the maximum value of all of its arguments

min
min(n1, n2, ...)
Returns the minimum value of all of its arguments

* alias *
read_file
$read_status

read_file
read_file(filename)
Reads the contents of a text file into a string. On success, returns 1 in
$read_status, and the contents of the file as a string in the subroutine return
value. On failure, returns the empty string "" and an 0 $read_status.

replace_in_string
replace_in_string(string, search_for, replace_with [, type, "copy"])
Replaces all occurrences of a search string in a string with a replacement
string. Arguments are 1: string to search in, 2: string to search for, 3:
replacement string.  There are two optional arguments.  One is a search type,
either "literal", "case", "word", "caseWord", "regex", or "regexNoCase".  The
default search type is "literal".  If the optional "copy" argument is
specified, a copy of the input string is returned when no replacements were
performed.  By default an empty string ("") will be returned in this case.
Returns a new string with all of the replacements done.

replace_range
replace_range(start, end, string)
Replaces all of the text in the current window between two positions. If the
cursor position is between start and end it will be set to start.

replace_selection
replace_selection(string)
Replaces the primary-selection selected text in the current window.

replace_substring
replace_substring(string, start, end, replace_with)
Replacing a substring between two positions in a string within another string.

$search_end
Position of the end of the last search pattern match found by
search() or search_string().

search
search(search_for, start [, search_type, wrap, direction])
Searches silently in a window without dialogs, beeps, or changes to the
selection. Arguments are: 1: string to search for, 2: starting position.
Optional arguments may include the strings: "wrap" to make the search wrap
around the beginning or end of the string, "backward" or "forward" to change
the search direction ("forward" is the default), "literal", "case", "word",
"caseWord", "regex", or "regexNoCase" to change the search  type  (default is
"literal"). Returns the starting position of the  match, or -1 if nothing
matched. Also returns the ending position  of the match in $search_end.

search_string
search_string(string, search_for, start [, search_type, direction])
Built-in macro subroutine for searching a string. Arguments are 1: string to
search in, 2: string to search for, 3: starting position. Optional arguments
may include the strings: "wrap" to make the search wrap around the beginning or
end of the string, "backward" or "forward" to change the search direction
("forward" is the default), "literal", "case", "word", "caseWord", "regex", or
"regexNoCase" to change the search type (default is "literal"). Returns the
starting position of the match, or -1 if nothing matched. Also returns the
ending position of the match in $search_end.

select
select(start, end)
Selects (with the primary selection) text in the current buffer between a
starting and ending position.

select_rectangle
select_rectangle(start, end, left, right)
Selects a rectangular area of text between a starting and ending position, and
confined horizontally to characters displayed between positions "left", and
"right".

set_backlight_string
set_backlight_string([string])
Applies the given string, which should be in the format of the
nedit*backlightCharTypes X resource, to the current text window, turning on
backlighting.  If the value of the string passed is "default", or if no
parameter is passed, the nedit.backlightCharTypes X resource's own value will
be used.  If the empty string, "", is passed, backlighting will be turned off.

set_cursor_pos
set_cursor_pos(position)
Set the cursor position for the current window.

* alias *
shell_command
$shell_cmd_status

shell_command
shell_command(command, input_string)
Executes a shell command, feeding it input from input_string. On completion,
output from the command is returned as the function value, and the command's
exit status is returned in the global variable $shell_cmd_status.

split
split(string, separation_string [, search_type])
Splits a string using the separator specified. Optionally the search_type
argument can specify how the separation_string is interpreted. The default is
"literal". The returned value is an array with keys beginning at 0.

* alias *
string_dialog
$string_dialog_button

string_dialog
string_dialog(message, btn_1_label, btn_2_label, ...)
Pops up a dialog prompting the user to enter information. The first argument is
a string to show in the message area of the dialog. Additional optional
arguments represent labels for buttons to appear along the bottom of the dialog.
Returns the string entered by the user as the function value, and number of the
button pressed (the first button is number 1), in $string_dialog_button. If the
user closes the dialog via the window close box, the function returns the empty
string, and $string_dialog_button returns 0.

string_compare
string_compare(string1, string2 [, consider-case])
Compare two  strings and return 0 if they are equal, -1 if string1 is less
than  string2 or 1 if string1 is greater than string2. The values for the
optional consider-case argument is either "case" or "nocase". The default is to
do a case sensitive comparison.

string_to_clipboard
string_to_clipboard(string)
Copy the contents of a macro string to the clipboard.

substring
substring(string, start [, end])
Returns the portion of a string between a start and end position (with the
position of the beginning of the string being 0).  If end is missing, the
position of the end of the string is used. If either of the positions are
negative, they are treated as relative to the end of the string.  A position
specified either before the start of the string or after the end of the string
is repositioned to the nearest valid string position.  If the start position is
beyond the end position, the empty string is returned.

t_print
t_print(string1, string2, ...)
Writes strings to the terminal (stdout) from which NEdit was started.

tolower
tolower(string)
Return an all lower-case version of string.
rangeset_add
toupper
toupper(string)
Return an all upper-case version of string.

write_file
write_file(string, filename)
Writes a string (parameter 1) to a file named in parameter 2. Returns 1 on
successful write, or 0 if unsuccessful.

* include *
neditmacroRS.ct
neditmacroHI.ct
neditmacroAR.ct