Go to the first, previous, next, last section, table of contents.
PENG supports extensive tool scripting capabilites. You can define your own tools, and use them via menus or hotkeys, and you can define environment variables that can be changed in the menus. This is described in the following sections.
Variables can be defined under `Options/Variables' (see section The Menu Entry `Options/Variables'). You can create new variables, delete existing ones (with DEL), and edit existing ones.
`Name' is the name under which the variable appears in the menu, and `Environment name' is the name of the environment variable created. Furthermore, you can define a hotkey and some options that affects inputting the variable.
Please note: Some of the key combinations offered are already used for other purposes on some keyboards, e.g., ALTGR+2/3/7/8/9/0/Q/C/E/M on German keyboards, so you can't use them as hotkeys.
If `Read from environment' is selected and the environment variable is already set before starting PENG, the PENG variable is initialized from the environment variable's contents (except for enumeration variables). However, variable values stored in the config file (usually entered in previous PENG sessions) take precedence.
The values for enumeration variables are specified as a `,' separated list of identifiers which will appear in the menu, each one optionally followed by a `:' and a value to which the environment variable will be set (otherwise, the identifier is used for this purpose, too). `\' can be used to quote special characters (`,', `:' and itself).
Variables of string types (including filenames etc.) can be defined to be lists. Their value is a (possibly empty) list of such strings. The list can be edited as usual in a menu, with DEL to remove items (see section Keys Used In Menus). In the environment variable, the items are stored quoted appropriately for the usual shells and separated with spaces.
The menu name is of the general form `[/mainmenu/][submenu/[subsubmenu/...]]menu-entry'.
It describes the menus and submenus for the variable. The only valid values for mainmenu are currently `Run', `Compile', `Tools', `Help' and `Options'. If omitted (including the leading `/'), it defaults to `Tools'.
The number and names of the submenus are not limited. (Yes, you can even use duplicate names within one menu, if that makes sense to you... ;-).
The letter to be used as a shortcut in each menu can be prefixed with a `~'. Otherwise, PENG will choose shortcuts by itself, as long as letters are available. A `~' at the end of the menu name means that no shortcut will be used at all.
If the menu name is empty, the variable does not appear in any menu, but the environment variable will be set, anyway (see section Internally used tool variables).
`Info node' can specify an info node (see section The Format Of An Info Node Description) to be used as a context-sensitive help for this tool -- see `Help/Help' (see section The Menu Entry `Help/Help'). This makes it possible to distribute tools with documentation in separate info files without any changes to PENG. The built-in PENG tools use the same mechanism to refer to sections in this documentation.
Tool variables can be used internally. E.g., the PENG built-in tools use an internal variable to compose the options to GPC from the various menu selections.
These variables are not normally listed in a menu because they only need to be changed when the tools themselves are modified to introduce new configuration options in the menu or things like that. However, you will see them under `Options/Variables' (see section The Menu Entry `Options/Variables').
Tools can be defined under `Options/Tools' (see section The Menu Entry `Options/Tools').
`Name', `Hotkey' and `Info node' are the same as the menu name, hotkey and info node for variables (see section Defining Variables). By convention, entries under `Options' should generally be used for variables only, but PENG does not enforce this.
As an additional feature, tools with the name `/Begin' or `/End' (note the leading `/') will not appear in any menu. `/Begin' tools are automatically executed when PENG is started -- or, more precisely, when the config file containing them is loaded (when PENG is started or it is loaded explicitly with `Options/Load config file' (see section The Menu Entry `Options/Load config file'). `/End' tools are automatically executed when PENG is terminated. This can be used, e.g., to create a temporary file or directory to be used by other tools at the beginning (see section `TEMP' (0)), and automatically remove it at the end.
If you define several `/Begin' or `/End' tools, the order in which they are executed is not defined.
`/End' tools are executed after all windows have been closed. Therefore, tool functions that refer to open windows such as `SAVE' (see section `SAVE' (any)), `CLOSE' (see section `CLOSE' (any)), `SEARCH' (see section `SEARCH' (1 or 2)), `GOTO' (see section `GOTO' (1 or 2)), `INSERT' (see section `INSERT' (*)) and `#i' output redirections (see section Redirecting The Output Of Shell Tools) do nothing or cause an error, respectively. Furthermore, functions that open a window such as `OPEN' (see section `OPEN' (any)), `VIEW' (see section `VIEW' (any)), `INFO' (see section `INFO' (any)), `TRYINFO' (see section `TRYINFO' (1)) and `#w', `#m', `#M', `#b' and `#B' output redirections (see section Redirecting The Output Of Shell Tools) are disabled.
`/End' tools are executed even if PENG is terminated by a `TERM' or `HUP' signal -- see `Options/Editor2/Use lock files' (see section The Menu Entry `Options/Editor2/Use lock files'). In this case, interactive tool functions, e.g., `SELECT' (see section `SELECT' (2 or more)), `PROMPT' (see section `PROMPT' (1 .. 3)) or `YNQUESTION' (see section `YNQUESTION' (*)), are disabled, but the `SHELL' (see section `SHELL' (*)) and `STATUS' functions (see section `STATUS' (*)) are executed. Therefore, be careful about using them in `/End' tools -- if the processes spawned don't terminate quickly enough, this might, e.g., prevent PENG from cleaning up properly before a system shutdown.
`Command' is the action for the tool (see section How Tools Are Evaluated).
`Mask', if given, can select which tool to apply, depending on the file name of the current editor window (e.g., to use different compilers for different languages with different file name extensions).
The `Condition', if not empty, is evaluated like a tool action when the tool is considered to be used, and should evaluate to `True' or `False' (case-insensitively). The tool is used if and only if the condition evaluates to `True' -- otherwise other tools are considered to be used if their name, mask and condition are satisfied. This makes it possible to define tools dependent on, e.g., variables. Since conditions can be evaluated quite often, they should usually contain only passive functions like `EQ' (see section `EQ' (1 or 2)) or `NE' (see section `NE' (1 or 2)).
When tools have a mask and/or a condition, it does make sense to have several tools of the same menu name. They will be listed in the menu only once.
It is also possible to have different tools (reasonably with different masks and/or conditions) with the same hotkey, with the same or different menu names.
Under `Options/Try a tool' (see section The Menu Entry `Options/Try a tool'), you can enter a tool command and apply it immediately without defining it as a tool.
The term current editor window, in the text above as well as in the description of the tool functions (see section Tool Functions), refers to the currently active window, if any, unless that is the message window, in which case it refers to the window below it, if any.
When a tool is invoked, PENG sets the following environment variables (besides those defined as variables, see section Defining Variables).
Some of them depend on the current editor window. Whenever a tool action influences the current editor window, the variables are updated automatically.
(1) empty if no window open or current window is not an editor
(2) empty if no current message
After setting the automatic variables (see section Variables Set Automatically) and the defined environment variables (see section Defining Variables), PENG evaluates the command line string from left to right, evaluating variable references and function and procedure calls.
Variable references are of the form `$ENVVAR' are replaced by the value of the environment variable. Both the automatic and user-defined variables and environment variables set before starting PENG can be used this way. If the variable is not set (as opposed to just being empty), this causes an error.
The variable name can also be enclosed in `{', `}'. In this case, special characters in the variable name don't have to be quoted with `\', and the name can be followed by a `-' or `:' and a value (e.g., `${foo-bar}'). That value is substituted if the variable is not set (`-'), or if it is not set or empty (`:'). Empty variables are even supported under Dos, which can't handle empty environment variables.
Function calls are of the form `$(FUNCTION arguments)'. Arguments are separated by one of several spaces. See section Tool Functions, for a list of available functions.
Parts of strings can be quoted with pairs of single or double quotes. Double quotes (`"') quote all characters except themselves and `$' (but including single quotes), single quotes (`'') quote all characters except themselves. Empty arguments can be formed by pairs of single or double quotes with nothing between them. The values of variables and results of functions, when used as arguments to other functions, are separated into multiple arguments, unless the variable evaluation or function call itself is inside double quotes, but `$' signs and quotations within them are never touched. This is mostly like the usual shells behave. `$' can quote itself (`$$', like in makefiles) as well as single and double quotes. The latter is needed if you want to pass quote characters to the `SHELL' (see section `SHELL' (*)) and `STATUS' (see section `STATUS' (*)) functions without causing them to quote text from the PENG tool evaluation.
Characters that need quoting (in some or all situations) are currently: `"', `'', ` ', `(', `)', `#', `$'. Pairs of unquoted parentheses are allowed in an argument.
The resulting string, after all replacements, if not empty, is executed, i.e., treated like the arguments to the `SHELL' function (see section `SHELL' (*)). This does not apply to tool conditions, where the resulting string is immediately taken as the value of the condition.
Please note: Tools like `echo foo $(WARNING bar)' will first give the warning `bar', and then write `foo' on the screen, because `$(WARNING bar)' is an argument to the main command. If you want the warning to be shown after the command is executed, you can do `$(SHELL echo foo #K) $(WARNING bar)' (See section Redirecting The Output Of Shell Tools, about the meaning of `#K').
PENG tools understand conditional statements of the form
`#if cond #then expr [#elif cond #then expr ... [#else expr]] #fi'
The `#elif' and `#else' parts are optional. There can be any number of `#elif' parts and one `#else' part for each `#if'. Conditional statements can be nested to a maximum depth of (currently) 16. The conditions cond must evaluate to either `False' or `True' (case-insensitively and ignoring any leading or trailing spaces).
The whole conditional statement is replaced by exactly one of the exprs, depending on the conditions, or by nothing if no `#else' part is given and all conditions are false. In particular, `#if' can be used both for conditional statements (the usual `if' in programming languages) and for conditional values (the `?:' in C). Spaces immediately following the `#if', `#then', `#elif', `#else' and `#fi' directives are removed, however spaces before those directives are not.
Only the expr which is actually used is evaluated, i.e., functions in the other exprs are not called. This is, of course, what you would expect of an if statement.
The following functions and procedures can be used in PENG tools.
The number of arguments is given in parentheses. `*' means the arguments are not separated, but treated as a single argument, including all the spaces except the first space after the function name.
Procedures are called like functions and take arguments like them and perform some action, but do not return anything.
Converts the argument to upper case.
Converts the argument to lower case.
Removes leading and trailing spaces from the argument.
Removes leading spaces from the argument.
Removes trailing spaces from the argument.
Returns a substring of the first argument, starting from the position given in the second argument (which must be a number) with the length given in the third argument (also a number), or extending up to the end of the first argument if only two arguments are given.
Finds the first match of the second argument, treated as a basic regular expression (see section The Menu Entry `Search/Regular expression'), in the first argument, and returns the index of the beginning of the match. If no match is found, it returns 0. The optional third argument, if not empty, can contain an index where to start matching (default 1), and the optional fourth argument an index where to stop matching (the default is the length of the first argument). The optional fifth argument can contain a combination of the following flags:
Returns `True' if the two arguments are equal as strings (or, if only one argument is given, if it's empty), and `False' otherwise.
Returns `True' if the two arguments are not equal as strings (or, if only one argument is given, if it's not empty), and `False' otherwise.
Returns `True' if all the arguments are `True', and `False' otherwise. All the arguments must be either `True' or `False' (case-insensitively and ignoring any leading or trailing spaces).
Please note: `AND' does not perform shortcut evalutaion, i.e., even if the first argument is `False', the remaining arguments are still evaluated. If you need shortcut evaluation, you can achieve this using `#if' statements (see section Conditional Statements in Tools). E.g., the following statement will have the effect of a shortcut `AND' with two arguments (though, in some cases, there exist shorter alternatives, e.g., if the `AND' is the whole condition of an `#if' statement without an `#else' branch):
#if cond1 #then cond2 #else False #fi
Returns `True' if at least one of the arguments is `True', and `False' otherwise. All the arguments must be either `True' or `False' (case-insensitively and ignoring any leading or trailing spaces).
Please note: `OR' does not perform shortcut evalutaion, i.e., even if the first argument is `True', the remaining arguments are still evaluated. If you need shortcut evaluation, you can achieve this using `#if' statements (see section Conditional Statements in Tools). E.g., the following statement will have the effect of a shortcut `OR' with two arguments (though, in some cases, there exist shorter alternatives, e.g., if the `OR' is the whole condition of an `#if' statement without an `#else' branch):
#if cond1 #then True #else cond2 #fi
Returns `True' if the argument is `True', and `False' otherwise. The argument must be either `True' or `False' (case-insensitively and ignoring any leading or trailing spaces).
Returns `True' if the file name given in the first argument (including directory if present!) matches any of the masks given in the remaining arguments, and `False' otherwise.
Returns all file names that match one of the patterns given.
Returns the directory of the argument(s). The result will always end with a directory separator -- if a file name contains no directory, the symbol that stands for the current directory (`.' on most systems), followed by a directory separator, is returned.
Returns the base name without extension of the argument(s).
Returns the file name extension of the argument(s).
If called with one argument, it returns the base name with extension. If called with two arguments, and the second argument is a suffix of the result, it also removes this suffix, just like `basename(1)' does (see section ``basename' Strip directory and suffix from a file name' in the GNU shell utilities manual).
Returns the argument(s) with all relative paths and occurrences of the symbols that stand for the current and parent directories (`.' and `..' on most systems) and symbolic links resolved in the directory, i.e., the path without the file name. Under Dos, it converts the result to lower case and removes a trailing `.', like Dos does. Arguments whose directory is invalid are ignored.
Removes the extension from the first argument and appends the second one.
Returns a unique temporary filename. It is guaranteed to not exist and to be distinct each time the function is called. The function does not create a file or directory, it just returns the name.
Displays a prompt to the user, with the first argument as its title, and the second argument, if given, as the initial content -- otherwise, the word under the cursor in the current editor window, if any, is used as the initial content, unless the `w' flag (see below) is given. Returns what the user enters. If the user aborts the prompt with ESC, the whole tool operation is aborted. The optional third argument can contain a combination of the following flags:
At most one of `f', `d', `m' or `p' is allowed.
Displays the given text to the user and waits for a `y'/`n' answer. If the answer is `y', it returns `True'. If the answer is `n', it returns `False'. If the question is aborted with ESC, the tool operation is aborted.
Displays a menu with the first argument as the title, and the further arguments as the items, and lets the user choose one item. Returns the item chosen. If the menu input is aborted, the whole tool operation is aborted.
Takes the first argument and replaces all matches of the second argument, treated as a basic regular expression (see section The Menu Entry `Search/Regular expression'), by the third one with backreferences and C-like escape sequences (esp. `\n', but not `\007') allowed (see section The Menu Entry `Search/Replace'), or by nothing if only two arguments are given. `\\' yields a single `\'. The optional fourth argument can contain a combination of the following flags:
Searches the first argument, treated as a basic regular expression (see section The Menu Entry `Search/Regular expression'), in the current editor window. If it is found, it goes to the position in the editor and returns `True', otherwise it returns `False'.
The optional second argument can contain a combination of the following flags:
Evaluates a mathematical expression in real or complex numbers. The expression may consist of
The expression is evaluated according to the usual mathematical rules (which are not quite the same as those in most programming languages). E.g., a `*' may be omitted between two expressions, the second of which is not a numeric constant, and arguments to functions do not need parentheses unless they are necessary to override precedence rules.
Precedence, from highest to lowest:
Please note: Due to the e notation, there is an ambiguity with terms like `2e' which will be interpreted as `2*10^...'. If you mean `2*e', write so, or `2 e' (with a space between the `2' and the `e'). Expressions like `3e+4+5' can be confusing, but are interpreted according to the e notation (i.e., this expression equals 30005).
If called with no arguments, `RANDOM' returns a random real number between 0 (inclusively) and 1 (exclusively). If called with 1 argument, which must be a positive integer n, `RANDOM' returns a random integer number between 1 and n (inclusively). If called with 2 arguments, which must be integers m and n with m <= n, `RANDOM' returns a random integer number between m and n (inclusively).
Tries to open an info reader with the given node name (see section The Format Of An Info Node Description), like `INFO' (see section `INFO' (any)). Returns `True' if successful, and `False' otherwise.
Invokes a system command with arguments by calling your shell (the one that is given in the SHELL environment variable). Unlike the other functions, quotes are honoured, but not removed here, so you don't have to double-quote special characters to prevent the shell from expanding them. Variable evaluations and function calls are evaluated before calling the shell, however, so you do have to quote `$' signs meant for the shell unless they occur within single quotes. The output and error of the command, unless redirected (see section Redirecting The Output Of Shell Tools), is returned, with multiple lines separated by spaces (just like backquotes do in the usual shells).
Like `SHELL' (see section `SHELL' (*)), but returns the status rather than the output and error of the command. I.e., a successful command returns `0', an unsuccessful one returns a number not equal to 0, a command terminated/stopped by a signal returns `Signal 42' or `Stopped 42', respectively, where 42 is the number of the signal. The output and error of the command are discarded, unless redirected (see section Redirecting The Output Of Shell Tools).
Evaluates the argument like the tool actions do (see section How Tools Are Evaluated). Can be used, e.g., to let variables refer to other variables by `$VARNAME' or even to some of the tool functions (see section Tool Functions). The expression to be evaluated can contain `EVAL' calls again, to a maximum depth of (currently) 16 -- this is to prevent endless recursion as in `$(SET foo '$(EVAL $foo)') $(EVAL $foo)'.
Ignores its argument and returns nothing. Useful if you don't care for the result of other tool functions such as `SEARCH' (see section `SEARCH' (1 or 2))
Sets an environment variable with the name given in the first argument to the value given in the second argument. These variables are persistent while PENG runs. This can be useful, e.g., to have a Compile tool which stores the name of the generated executable in a variable, and a Run tool which runs the executable with the `SHELL' (see section `SHELL' (*)) function. If a PENG variable of that name is defined, and has `Read from environment' enabled, its value is also updated.
Does not return anything.
Opens the given file names as editor windows. If they are already open, they are just brought to the top and if the files on disk were modified, e.g., by a previous `SHELL' (see section `SHELL' (*)) execution, they're automatically reloaded without asking for confirmation (unless the editor window contains unsaved modifications).
Does not return anything.
Like `OPEN' (see section `OPEN' (any)), but opens the editor windows read-only if they are not already open.
Does not return anything.
Opens info reader(s) with the given node names (see section The Format Of An Info Node Description) if they exist.
Does not return anything.
Closes all the files that are opened in an editor window and whose name (with or without directory) matches one of the patterns given. If no arguments are given, the current editor window, if any, is closed. If a window's contents are modified, the user is asked whether to save them. If this question is aborted, the whole tool operation is aborted.
Does not return anything.
Saves all the files that are opened in an editor window and were modified and whose name (with or without directory) matches one of the patterns given (so `$(SAVE *)' will save all files opened). If no arguments are given, the current editor window, if any, is saved if it was modified.
Does not return anything.
Goes to the given line [and column] in the current editor window.
Does not return anything.
Inserts the given text into the current editor window at the cursor position, and does not return anything.
C-like escape sequences (esp. `\n', also `\007') are recognized as well as the following special sequences:
These sequences make it possible to define tools that insert, e.g., an indented block into a program and place the cursor at a certain position within the block and provide an easy way to jump to other important positions (see section PENG Tools Used As Syntax Macros).
The `INSERT' tool function (see section `INSERT' (*)) makes it possible to define PENG tools that provide syntax macros for various languages.
The PENG built-in tools provide several macros for Pascal, C, LaTeX and Texinfo. They can be found in the `Tools/Macros/LANGUAGE' menus (see section The `Tools/Macros' Submenus).
All of the syntax macros are only active for files whose extension matches some common extensions used for the particular language.
Therefore, the macros for different languages can share the same hotkeys. All the macro hotkeys use the EXTRA key, so if you have a system with a working EXTRA key (see section Modifier Keys On Different Systems), these macros can save you a lot of typing.
Whenever possible, the hotkeys are chosen so that similar constructs use the same hotkey in all languages, so people who often program or write in different languages don't have to remember too many different hotkyes. (Ideally, they could write their program just by using hotkeys without caring about the language at all, but we're not quite there yet... ;-). All languages have a `New program' (or `New text') macro which is best used immediately after opening a new empty file, with an EXTRA-N hotkey, and e.g., the `case' statement in Pascal and the `switch' statemtent in C share the same hotkey EXTRA-C.
Changes to the given directory. Does not return anything.
Displays the given text to the user and waits for a `y'/`n' answer. If the answer is `n', or the question is aborted with ESC, the tool operation is aborted, otherwise is just continues.
Does not return anything.
Shows the argument as an error message to the user and aborts the tool operation.
Does not return anything.
Shows the argument as a warning to the user, but does not abort the tool operation.
Does not return anything.
Output redirections are possible for the arguments to the `SHELL' (see section `SHELL' (*)) and `STATUS' (see section `STATUS' (*)) functions and for the main command (the whole tool action). They are of the form `#1', `#2' or `#' (and therefore can be escaped by single or double quotes) to redirect the output, error, or both of them, respectively, and must be followed by the destination (see below).
Please note: Normal redirections with `>' are left to the shell to be handled in the usual way. Under Dos, bash style redirections are automatically converted into `redir' calls. Redirections of the shell and of PENG are each evaluated from left to right. However, redirections of the shell always take precedence before those of PENG, so `foo > bar #i' will redirect the output of `foo' to `bar' and not insert it into the current editor window.
The following destinations are recognized. An `S' in parentheses means, if the process returns non-zero status, the tool operation is aborted (not with `STATUS'). An `I' means, the process gets an empty input. A `T' means, PENG keeps control of the terminal, and the process (together with its child processes) can be aborted by ESC (of course, this does not apply under non-multitasking systems). All of these properties apply for unredirected output/error. They are effective only when they apply to both the actual output and the actual error redirection.
Value = Offset + Size * Given_Value / Range,where the given values are expected to be between 0 and Range. Multiple levels of nested scaling are allowed. One level of scaling is terminated with `#progress-bar-#'. Scaling is useful to fit the progress bar values of sub-processes into a global process bar. All numbers can be in either integer or real format.
PENG has some built-in tools for compiling Pascal and C programs with `GPC' and `GCC' and writing `LaTeX' and `Texinfo' texts, and some macros for those languages, and various other useful things.
They are used by default, but you can disable them if you don't want them (see section Command Line Arguments). You can also dump them to a file (see section Command Line Arguments), and use this as a base for your own configuration. You are explicitly allowed to modify these tools. However, note that it might make upgrading to a new PENG version a little harder because the new version will probably come with more or less different built-in tools and you might have to adapt your modifications accordingly. If you send useful modifications to me (and give me permission), I will include them in future PENG distributions.
The tools are available in the `Run' (see section The `Run' Menu), `Compile' (see section The `Compile' Menu), `Tools' (see section The `Tools' Menu), `Options' (see section The `Options' Menu) and `Help' (see section The `Help' Menu) menus and are documented in this manual. They are differentiated from the unchangeable menu items by a header line `The PENG Built-In Tool...', and the corresponding variables by a header line `The PENG Built-In Tool Variable...'
Please note: Many of the tools expect certain programs to be installed on the system -- sometimes particular programs for certain purposes (e.g., compilers for the different languages), and sometimes generic shell, text, file or other utilities. Therefore, if you are using the tools on a system without appropriate tools (e.g., Dos without a complete DJGPP installation), don't expect everything to work.
Go to the first, previous, next, last section, table of contents.