Built in Variables

These variables are read-only and cannot be changed by direct assignment.

• $1, $2, $3, $4, $5, $6, $7, $8, $9 $args[<expr>]
  Argument information. The first 9 arguments (if there are that many) can be referenced as read-only values using the shorthand form. All arguments can be accessed as values in the $args array, using a numeric index starting at 1. The total number of arguments received by a function is given by $n_args or $args[].
• $active_pane
  Index of the current pane.
• $auto_indent
  Contains the current preference for auto indent. Can be "off", "on", or "smart".
• $calltip_ID
  Equals the ID of the currently displayed calltip, or 0 if no calltip is being displayed.
• $cursor
  Position of the cursor in the current window.
• $column
  Column number of the cursor position in the current window.
• $display_width
  Width of the current pane in pixels.
• $em_tab_dist
  If tab stop emulation is turned on in the Preferences → Tab Stops... dialog, the value is the distance between emulated tab stops. If tab emulation is turned off, the value is 0.
• $empty_array
  An array with no elements. This can be used to initialize an array to an empty state.
• $file_format
  Current newline format that the file will be saved with. Can be "unix", "dos" or "macintosh".
• $file_name
  Name of the file being edited in the current window, stripped of directory component.
• $file_path
  Directory component of file being edited in the current window.
• $font_name
  Contains the current plain text font name.
• $highlight_syntax
  Whether syntax highlighting is turned on.
• $incremental_backup
  Contains 1 if incremental auto saving is on, otherwise 0.
• $incremental_search_line
  Has a value of 1 if the preference is selected to always show the incremental search line, otherwise 0.
• $language_mode
  Name of language mode set in the current window.
• $line
  Line number of the cursor position in the current window.
• $locked
  True if the file has been locked by the user.
• $make_backup_copy
  Has a value of 1 if original file is kept in a backup file on save, otherwise 0.
• $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
  The minimum font width of all the active styles. Syntax highlighting styles are only considered if syntax highlighting is turned on.
• $modified
  True if the file in the current window has been modified and the modifications have not yet been saved.
• $VERSION
  Returns NEdit-ng's version number, in the format "YYYYRRR" ("2019004" for NEdit-ng 2019.4).
• $n_display_lines
  The number of lines visible in the currently active pane.
• $n_panes
  The number of panes in the current window.
• $overtype_mode
  True if in Overtype mode.
• $read_only
  True if the file is read only.
• $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.
• $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
  Name of the current NEdit-ng server.
• $show_line_numbers
  Whether line numbers are shown next to the text.
• $show_matching
  Contains the current preference for showing matching pairs, such as "[]" and "{}" pairs. Can be "off", "delimiter", or "range".
• $match_syntax_based
  Whether pair matching should use syntax information, if available.
• $statistics_line
  Has a value of 1 if the statistics line is shown, otherwise 0.
• $sub_sep
  Contains the value of the array sub-script separation string.
• $tab_dist
  The distance between tab stops for a hardware tab character, as set in the Preferences → Tab Stops... dialog.
• $text_length
  The length of the text in the current document.
• $top_line
  The line number of the top line of the currently active pane.
• $use_tabs
  Whether the user is allowing the NEdit-ng 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 Preferences → Tab Stops... dialog.)
• $wrap_margin
  The right margin in the current window for text wrapping and filling.
• $wrap_text
  The current wrap text mode. Values are "none", "auto" or "continuous".

Built-in Subroutines

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

• beep()
  Ring the bell.

• calltip( "text_or_key" [, pos [, mode or 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), "tipKey", or "tagKey". "tipText" displays the text as-is, "tagKey" uses it as the key to look up a tag, then converts the tag to a calltip, and "tipKey" uses it as the key to look up a calltip, then falls back to "tagKey" behavior if that fails. You'll usually use "tipKey" or "tipText".

  Finally, you can modify the placement of the calltip relative to the cursor position (or <pos>) with one or more of these optional position modifiers: "center" aligns the center of the calltip with the position. "right" aligns the 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()
  Returns the contents of the clipboard as a macro string. Returns empty string on error.

• 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.

• filename_dialog( [title[, mode[, defaultPath[, filter[, defaultName]]]]] )
  Presents a file selection dialog with the given title to the user that prompts for a new or existing file.

  Options are: <title> will be the title of the dialog, defaults to "Choose file". If <mode> is set to "exist" (default), the dialog will only allow the user to select files which already exist. If it is set to "new", then, the user may specify any valid filename regardless of a file existing with that name or not. <defaultPath> is the default path to use. Default (or "") will use the active document's directory. <filter> is the file glob which determines which files to display. Is set to "*" if filter is "" and by default. <defaultName> is the default filename that is filled in automatically.

  Returns "" if the user cancelled the dialog, otherwise returns the fully-qualified path, including the filename.

• focus_window( window_name )
  Sets the window on which subsequent macro commands operate. <window_name> can be either a fully qualified file name, or a relative filename (which will be completed from NEdit-ng's working directory) 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( position )
  Returns the single character at the position indicated by the first argument to the routine from the current window.

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

• 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( name )
  Gets the value of an environment variable.

• 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( string )
  Returns the length of a string

• list_dialog( message, text, btn_1_label, btn_2_label, ... )
  Pop up a dialog for prompting the user to choose a line 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. Returns the line of text selected by the user as the function value (without any newline separator) or the empty string if none was selected, and 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, the function returns the empty string, and $list_dialog_button returns 0.

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

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

• 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 a 0 $read_status.

• 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( start, end, string )
  Replaces all the text between two positions in the current window. If the cursor position is between start and end it will be set to start.

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

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

• revert_to_saved()
  Reloads the file, discarding all changes done to the document by the user since the last save.

• 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( 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( start, end )
  Selects (with the primary selection) text in the current buffer between a starting and ending position.

• 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_cursor_pos( position )
  Set the cursor position for the current window.

• 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(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.

• 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(string1, string2 [, consider-case])
  Compare two strings and return 0 if they are equal, -1 if string1 is lexicographically less than string2 or 1 if string1 is lexicographically 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 )
  Copy the contents of a macro string to the clipboard.

• 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( string1, string2, ... )
  Writes strings to the terminal (stdout) from which NEdit-ng was started.

• tolower( string )
  Return an all lower-case version of string.

• toupper( string )
  Return an all upper-case version of string.

• valid_number( string )
  Returns 1 if the string can be converted to a number without error following the same rules that the implicit conversion would. Otherwise 0.

• 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.

Deprecated Functions

Some functions are included only for supporting legacy macros. You should not use any of these functions in any new macro you write.

• match()
  DEPRECATED Use select_to_matching() instead.

Deprecated Built in Variables

Some global variables no longer have a practical meaning in NEdit-ng. You should not use any of these variables in any new macro you write.

• $font_name_bold
  Contains the current bold text font name.
  DEPRECATED NEdit has dropped support for simultanious different fonts, use $font_name

• $font_name_bold_italic
  Contains the current bold-italic text font name.
  DEPRECATED NEdit has dropped support for simultanious different fonts, use $font_name

• $font_name_italic
  Contains the current italic text font name.
  DEPRECATED NEdit has dropped support for simultanious different fonts, use $font_name