Macro Subroutines

  BUILT IN VARIABLES

• $cursor :
  Position of the cursor in the current window.
  
• $column :
  Column number of the cursor position in the current window.
  
• $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.
• $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.
• $language_mode :
  Name of language mode set in the current window.
• $line :
  Line number of the cursor position in the current window.
• $modified :
  True if the file in the current window has been modified and the modifications have not yet been saved.
• $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.
• $tab_dist :
  The distance between tab stops for a hardware tab character, as set in the Tabs... dialog of the Preferences menu.
• $text_length :
  The length of the text in the current window.
• $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 :
  The right margin in the current window for text wrapping and filling.

  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
• 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.
  
  1. First argument is a string to show in the message area of the dialog.
  2. Up to nine 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(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(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.
• 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.
  
  1. The first argument is a message string to be used as a title for the fixed text describing the list.
  2. The second string provides the list data: this is a text string in which list entries are separated by newline characters.
  3. Up to seven 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 an 0 $read_status.
• replace_in_string(string, search_for, replace_with, [type]) : 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.
  4. Argument 4 is an optional search type, one of "literal", "case" or "regex". The default search type is "literal".
     
     
  Returns a new string with all of the replacements done, or an empty string (.) if no occurrences were found.
• replace_range(start, end, string) :
  Replaces all of the text in the current window between two positions
• 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.
• 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.
  3. 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" or "regex" 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. 2: string to search for
  3. 3: starting position.
  4. 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" or "regex" 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(pos) :
  Set the cursor position for the current window.
• set_language_mode(mode) :
  Change language mode 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.
• string_dialog(message, btn_1_label, btn_2_label, ...) :
  Pop up a dialog for prompting the user to enter information. The first argument is a string to show in the message area of the dialog. Up to nine 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_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 starting and ending position.
• t_print(string1, string2, ...) :
  Writes strings to the terminal (stdout) from which NEdit was started.
• tolower(string) :
  Return an all lower-case version of string.
• toupper(string) :
  Return an all upper-case version of string.
• 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.