Macro Language

Macros can be called from Macro menu commands, window background menu commands, within the smart-indent framework, and from the .neditmacro file. Macro menu and window background menu commands are defined under Preferences -> Default Settings -> Customize Menus. See the section below titled, "Preferences" for more information on creating items in these menus. The .neditmacro file is a file of macro commands and definitions which you can create in your home directory, and which NEdit will automatically load when it is first started.

NEdit's macro language is a simple interpreter with integer arithmetic, dynamic strings, and C-style looping constructs (very similar to the procedural portion of the Unix awk program). From the macro language, you can call the same action routines which are bound to keyboard keys and menu items, as well additional subroutines for accessing and manipulating editor data, which are specific to the macro language (these are listed in the sections titled Macro Subroutines, and Actions).

  Syntax

An NEdit macro language program consists of a list of statements, each terminated by a newline. Groups of statements which are executed together conditionally, such as the body of a loop, are surrounded by curly braces "{}".

Blank lines and comments are also allowed. Comments begin with a "#" and end with a newline, and can appear either on a line by themselves, or at the end of a statement.

Statements which are too long to fit on a single line may be split across several lines, by placing a backslash "\" character at the end of each line to be continued.

  Data Types

The NEdit macro language recognizes only two data types, dynamic character strings, and integer values. In general strings and integers can be used interchangeably. If a string represents an integer value, it can be used as an integer. Integers can be compared and concatenated with strings.

Integer Constants:

Integers are non-fractional numbers in the range of -2147483647 to 2147483647. Integer constants must be in decimal. For example:

a = -1
b = 1000

Character String Constants:

Character string constants are enclosed in double quotes. For example:

a = "a string"
dialog("Hi there!", "Dismiss")

Strings may also include C-language style escape sequences:

• \\ Backslash
• \t Tab
• \f Form feed
• \" Double quote
• \b Backspace
• \a Alert
• \n Newline
• \r Carriage return
• \v Vertical tab

For example, to send output to the terminal from which nedit was started, a newline character is neccessary because, like printf, t_print requires explicit newlines, and also buffers its output on a per-line basis:

t_print("a = " a "\n")

 Variables

Variable names must begin either with a letter (local variables), or a $ (global variables). Beyond the first character, variables may also contain numbers and underscores `_'. Variables are called in to existence just by setting them (no explicit declarations are necessary).

Local variables are limited in scope to the subroutine (or menu item definition) in which they appear. Global variables are accessible from all routines, and their values persist beyond the call which created them, until reset.

Built-in Variables:

NEdit has a number of permanently defined variables, which are used to access global editor information and information about the the window in which the macro is executing. These are listed along with the built in functions in the section titled Macro Subroutines.

  Functions and Subroutines

The syntax of a function or subroutine call is:

function_name(arg1, arg2, ...)

where arg1, arg2, etc. represent up to 9 argument values which are passed to the routine being called. A function or subroutine call can be on a line by itself, as above, or if it returns a value, can be invoked within a character or numeric expression:

a = fn1(b, c) + fn2(d)
dialog("fn3 says: " fn3())

Arguments are passed by value. This means that you can not return values via the argument list, only through the function value or indirectly through agreed-upon global variables.

Built-in Functions

NEdit has a wide range of built in functions which can be called from the macro language. These routines are divided into two classes, macro-language functions, and editor action routines. Editor action routines are more flexible, in that they may be called either from the macro language, or bound directly to keys via translation tables. They are also limited, however, in that they can not return values. Macro language routines can return values, but can not be bound to keys in translation tables.

Nearly all of the built-in subroutines operate on an implied window, which is initially the window from which the macro was started. To manipulate the contents of other windows, use the focus_window subroutine to change the focus to the ones you wish to modify. focus_window can also be used to iterate over all of the currently open windows, using the special keyword names, "last" and "next".

For backwards compatibility, hyphenated action routine names are allowed, and most of the existing action routines names which contain underscores have an equivalent version containing hyphens ('-') instead of underscores. Use of these names is discouraged. The macro parser resolves the ambiguity between '-' as the subtraction/negation operator, and - as part of an action routine name by assuming subtraction unless the symbol specifically matches an action routine name.

User Defined Functions

Users can define their own macro subroutines, using the define keyword:

define subroutine_name {
< body of subroutine >
}

Macro definitions can not appear within other definitions, or within macro menu item definitions (usually they are found in the .neditmacro file). The arguments with which a user-defined subroutine or function was invoked, are presented as $1, $2, ... , $9. The number of arguments can be read from $n_args.

 Operators and Expressions

Operators have the same meaning and precedence that they do in C, except for ^, which raises a number to a power (y^x means y to the x power), rather than bitwise exclusive OR. The table below lists operators in decreasing order of precedence.

Operators Associativity

• ()
• ^ right to left
• - ! ++ -- (unary)
• * / % left to right
• + - left to right
• > >= < <= == != left to right
• & left to right
• | left to right
• && left to right
• || left to right
• (concatenation) left to right
• = += -= *= /= %=, &= |= right to left

The order in which operands are evaluated in an expression is undefined, except for && and ||, which like C, evaluate operands left to right, but stop when further evaluation would no longer change the result.

Numerical Operators

The numeric operators supported by the NEdit macro language are listed below:

• + addition
• - subtraction or negation
• * multiplication
• / division
• % modulo
• ^ power
• & bitwise and
• | bitwise or

Increment (++) and decrement (--) operators can also be appended or prepended to variables within an expression. Prepended increment/decrement operators act before the variable is evaulated. Appended increment/decrement operators act after the variable is evaluated.

Logical and Comparison Operators

Logical operations produce a result of 0 (for false) or 1 (for true). In a logical operation, any non-zero value is recognized to mean true. The logical and comparison operators allowed in the NEdit macro language are listed below:

• && logical and
• || logical or
• ! not
• > greater
• < less
• >= greater or equal
• <= less or equal
• == equal (integers and/or strings)
• != not equal (integers and/or strings)

Character String Operators

The "operator" for concatenating two strings is the absence of an operator. Adjoining character strings with no operator in between means concatenation:

d = a b "string" c
t_print("the value of a is: " a)

Comparison between character strings is done with the == and != operators, (as with integers). There are a number of useful built-in routines for working with character strings, which are listed in the section called Macro Subroutines.

 Looping and Conditionals

NEdit supports looping constructs: for and while, and conditional statements:if and else, with essentially the same syntax as C:

for (<init>, ...; <condition>; <increment>, ...) <body>

while (<condition>) <body>

if (<condition>) <body>

if (<condition>) <body> else <body>

<body>, as in C, can be a single statement, or a list of statements enclosed in curly braces ({}). <condition> is an expression which must evaluate to true for the statements in <body> to be executed. for loops may also contain initialization statements, <init>, executed once at the beginning of the loop, and increment/decrement statements (or any arbitrary statement), which are executed at the end of the loop, before the condition is evaluated again.

Examples

for (i=0; i<100; i++)
j = i * 2

for (i=0, j=20; i<20; i++, j--) {
k = i * j
t_print(i, j, k)
}

while (k > 0)
{
k = k - 1
t_print(k)
}

for (;;) {
if (i-- < 1)
break
}

Loops may contain break and continue statements. A break statement causes an exit from the innermost loop, a continue statement transfers control to the end of the loop.