GetInp

Introduction
Commands by type
Full command list
How are aliases substituted
Startup

Introduction

Beside the normal commands used in this program, there is a group of extra commands available. With these commands simple scripting facilities, startup scripts, aliases and other useful options are available.

All these commands have to be prefixed with a backslash (\). Note: if you want to specify a backslash on the commandline, you may have to escape the backslash from the shell.
The prefix character can be changed with the \prefix command.

This is how a command is presented in this manual.
Aliases are case insensitive and are always stored in uppercase.
Lines starting with ! are treated as comments.

Commands by type

Aliases
\alias	define or list aliases
\alphanum	define alias
\arg	define alias with default
\export	put alias to environment
\import	import alias from environment
\store	save result from evaluate
\unalias	remove alias
Directories
\back	return to previous directory
\cd	change working directory
\dir	directory listing
\mkdir	create directory
\pwd	print working directory name
Evaluate
\addeval	add a variable
\evaluate	calculator
\listeval	show stored variables
\removeeval	remove a variable
Files
@	execute commandfile
&	execute commandfile
\command	show command list
\dir	directory listing
\edit	invoke editor
\journal	copy input commands to file
\overwrite	overwrite existing files
\rename	rename file
Flow Control
\exit	emulate end-of-file
\fatal	terminate program
\goto	skip statements
\if	conditional execution
\repeat	multiple execution
Keyboard
@	execute commandfile
&	execute commandfile
\bell	keyboard bell
\help	try to display program help
\journal	write input commands to file
\pause	pause until user types go
Process
\spawn	execute command as subshell
\shell	create new shell
Screen
\cls	clear screen
\echo	echo input commands and command files
\output	more or less output
\title	display the rest of the line in the titlebar of the terminal window
\wl	set terminal width to 132
\wn	set terminal width to 80
Timing
\cpu	show cpu time since last setcpu
\date	show date
\pause	wait for user (if interactive)
\second	show cpu time since last setcpu
\setcpu	initialize cpu timer
\time	show time
\wait	wait

Commands

@

Syntax: @filename
Open a command file and read until end-of-file.

If filename is an environment variable, the value of this variable is used.
The default file type is build from the first two characters of the image name and the letter c (f.e. if the program is called view, the default file type is .vic).
The default file type can be changed by creating an alias scripttype
You may specify arguments to the script. The syntax is: @filename(arg1;arg2;..argn) These arguments may be used within the script as $1, $2,...$n
Example: Content of file script.bat
```
!check for 2 input arguments
\if not alias $1' \exit
\if not alias $2' \exit
!now show the values of the arguments
\alias $1
\alias $2
```
Note the single quote in the second line. We do not want $1 to be substituted here. (see the alias substitution rules).
Another example:
```
!substitute the arguments, but use defaults if absent
\arg v $1 0.70
\arg w $2 something else
!show the values
\alias v
\alias w
```
The program will give an error if filename cannot be opened. Use &filename for a conditional execution of filename.
As long as the script is active, the name part of filename (without the filetype) is stored in the alias script (but a nested @anotherfile will temporarily change the alias).

&

Syntax: &filename
Check a command file and read until end-of-file.
If filename exist, run the command @filename, otherwise nothing happens.

\addeval

Syntax: \addeval name expression
Evaluate expression and save the result in the internal variable name.
name can be used in succeeding expressions of the internal evaluate routines. See \evaluate, \listeval and \removeeval.

\alias

Define or list aliases. Actions are dependent of the number of parameters.
Syntax:

\alias	list all aliases
\alias a	list specific alias a
\alias a line	set alias a to line

See the substitution rules.

\alphanum

Similar to \alias a line, but all non-alphanumeric characters are stripped from line.

\arg

Define alias with default.
\arg a1 a2 a3.....

if a2 is an existing alias: \alias a1 'a2'
if a2 is not an alias: \alias a1 a3......

This may be usefull within scripts, see @

\back

return to the previous directory. See \cd.

\bell

Ring keyboard bell.

\cd

Syntax: \cd new-directory-name
Change working directory
See \back. The alias WORK_DIR contains the directoryname where the program was started from, so you may return to this directory with \cd WORK_DIR.

\cls

Clear screen

\command

Display the contents of file CONFIG_PATH/IMAGE_NAME.commands (if this file exists).

\cpu

Show cpu time used (in hh:mm:ss) since last \setcpu. See also \second.

\date

Show current date

\dir

Syntax: \dir [name]
Get a directory listing.
The number of files will be stored in the alias DIRCOUNT.

\echo

Set/reset echo of input commands.
Syntax: \echo on/off/auto/debug

\echo on	echo all input commands
\echo off	do not echo input commands
\echo auto	echo input commands only from @files
\echo debug	echo all input commands. Echo cannot be switched off anymore

\edit

Invoke the default editor.
Syntax: \edit filename
The editor is defined with the shell environment variable EDITOR.

\evaluate

Syntax: \evaluate expression
Evaluate expression.
Evaluate always stores the result in the alias EVAL_RESULT. (use \store to save the result into another alias.)

Expressions
+	add
-	subtract
*	multiply
/	divide
**	power
^	power
Functions (radians)
acos	arc cosine
asin	arc sine
atan	arc tangent
atan2	atan2
cos	cosine
sin	sine
tan	tangent
Functions (degrees)
acosd	arc cosine
asind	arc sine
atand	arc tangent
atan2d(f,g)	atan2
cosd	cosine
sind	sine
tand	tangent
Boolean Tests
eq(f,g)	1.0 if f is equal to g, else 0.0
eq(f,g,v,w)	v if f is equal to g, else w
even(f)	1.0 if f even, else 0.0
even(f,v,w)	v if f even, else w
ge(f,g)	1.0 if f is greater than or equal to g, else 0.0
ge(f,g,v,w)	v if f is greater than or equal to g, else w
gele(f,g,h)	1.0 if f is greater than or equal to g and less than or equal to h, else 0.0
gele(f,g,h,v,w)	v if f is greater than or equal to g and less than or equal to h, else w
gelt(f,g,h)	1.0 if f is greater than or equal to g and less than h, else 0.0
gelt(f,g,h,v,w)	v if f is greater than or equal to g and less than h, else w
gt(f,g)	1.0 if f is greater than g, else 0.0
gt(f,g,v,w)	v if f is greater than g, else w
gtle(f,g,h)	1.0 if f is greater than g and less than or equal to h, else 0.0
gtle(f,g,h,v,w)	v if f is greater than g and less than or equal to h, else w
gtlt(f,g,h)	1.0 if f is greater than g and less than h, else 0.0
gtlt(f,g,h,v,w)	v if f is greater than g and less than h, else w
le(f,g)	1.0 if f is less than or equal to g, else 0.0
le(f,g,v,w)	v if f is less than or equal to g, else w
lt(f,g)	1.0 if f is less than g, else 0.0
lt(f,g,v,w)	v if f is less than g, else w
ne(f,g)	1.0 if f is not equal to g, else 0.0
ne(f,g,v,w)	v if f is not equal to g, else w
odd(f)	1.0 if f odd, else 0.0
odd(f,v,w)	v if f odd, else w
Other Functions
abs	absolute value
between(f,g)	bring f between -g and g (modulo 2*g)
entier	largest integer less than f
exp	exponent
gauss	GAUSS4+GAUSS1exp(-0.5((x-GAUSS2)/GAUSS3)**2)
int	truncate
log	natural log
log10	base 10 log
max(f....)	maximum of (at most) 5 arguments
min(f....)	minimum of (at most) 5 arguments
mod(f,g)	f modulo g
nint	round
plog	natural log (zero for arg ≤ 1)
plog10	base 10 log (zero for arg ≤ 1)
sign(f)	-1.0 if f<0, +1.0 if f≥0
sqrt	square root
within(f,g,h)	f if g<f<h, otherwise the extreme value. min(max(f,g),h)
Constants
Pi	3.1415....
PiOver2	0.5*Pi
TwoPi	2*Pi
Grad	180.0/Pi
rnd	0.0-1.0

rnd is not actually a constant. It returns a random number between 0.0 and 1.0, but the syntax resembles a constant due the lack of an argument.
Constants can be added to this list with \addeval. See \listeval.

\exit

emulate an end-of-file
If this command is executed from a script (@file), the rest of the file is ignored. If you type \exit from the keyboard, you will probably end the program.

\export

Syntax: \export aliasname
Define an environment variable with the same name as aliasname.
This is only useful if you are going to create new processes (via \shell or \spawn).

\fatal

Terminate program with a fatal error.

\goto

Syntax: \goto label
Skip statements
All input is skipped until a line with !label is encountered. Notes:

Always skip forward.
The exclamation is necessary.

\help

Try to display program help
Syntax: \help [text]
The program will search for an URL with information. The search order is:

Environment variable IMAGE_NAME
CONFIG_PATH/IMAGE_NAME.html
CONFIG_PATH/doc/index.html
CONFIG_PATH/doc/IMAGE_NAME.html

If the subdirectory doc does not exist, the search will be tried for subdirectory html.
If you specify the optional [text] the search order will be

Environment variable IMAGE_NAME
CONFIG_PATH/IMAGE_NAME.html
CONFIG_PATH/doc/commands.html
CONFIG_PATH/doc/IMAGE_NAME_commands.html
CONFIG_PATH/doc/IMAGE_NAME.html

If the URL is found, a html browser (firefox, mozilla, netscape) will be launched with the URL as option. First the program tries to launche a daughter of a running browser (with options -remote and new-window). If this fails, the browser will be started. You may define the browser with the environment variable BROWSER or with an alias BROWSER.

If the URL is not found, a search is done for a (VMS-like) .hlp file. The search order is:

CONFIG_PATH/doc/IMAGE_NAME.hlp
CONFIG_PATH/IMAGE_NAME.hlp

If found, the program will allow you to browse this hlp file.

\if

Execute commands depending on a condition.

\if alias name commands
Execute commands if alias name exists
\if dir name commands
Execute commands if name is a directory
\if eqs string1 string2 commands
Execute commands if string1 equals string2
\if file filename commands
Execute commands if filename exists
\if filez filename commands
Execute commands if one of filename, filename .Z, filename .gz or filename .bz2 exists.
\if expr evalexpr commands
Use evaluate to calculate evalexpr. Execute commands if the result equals to 1.

or negate with the statement \if not

\import

Syntax: \import variable
Get the value of an environment variable.
The value is stored in an alias with the same name as variable

\journal

Syntax: \journal auto/on/off/suspend
Echo input commands to a journal file.

\journal auto
If the program runs interactively, enable journalling.
\journal on
Enable journalling. If the previous state was \journal suspend, the journal continues into the open file, otherwise a new file is created with the name of the current image and filetype .jrn
\journal off
Disable journalling.
\journal suspend
Temporarily suspend journalling.

\listeval

Syntax: \listeval
Prints an overview of the constants available to the internal evaluate routines (see \evaluate. Constants can be added or changed with \addeval and removed with \removeeval.

\mkdir

Syntax: \mkdir directory-name
Create a new directory

\output

Syntax: \output none/normal/full/debug
Default: \output normal
Selects less or more output.

OutputLevel	Command	Action
full	@	echo script name
	\command	list obsolete commands
	\alias	echo alias definition
	\repeat	echo repeat nr and command
	\unalias	echo removal of alias
debug		a lot during file search
debug		echo input and substituted lines

\overwrite

Syntax: \overwrite on/off
Default: \overwrite off

off: Before a new file is created, an existing file will be renamed to filename.~x~ whith x an increasing number.
on: New files will overwrite existing files.

\pause

Wait until the user enters the command go. Pause is only activated if the process mode is interactive. You may use this command in a @script to suspend execution.

\prefix

Syntax: \prefix c
Set the prefix character to c. The default is a backslash (\).

\pwd

Syntax: \pwd
Show working directory name
See \back. The alias WORK_DIR contains the directoryname where the program was started from, so you may return to this directory with \cd WORK_DIR.

\removeeval

Syntax: \removeeval name
Remove the internal variable name.
See \addeval and \listeval.

\repeat

Syntax: \repeat n line
Repeat a command
n (evaluated as \evaluate) is the number of times to repeat the command line. If NREP is an existing alias (with a value >0), the value of NREP will be incremented after each execution of line. If the value of NREP starts with a leading 0, the number of digits in NREP will be kept constant.

\rename

Syntax: \rename oldfile newfile
Rename oldfile into newfile.

\second

Show cpu time (in seconds) used since last \setcpu. See also \cpu.

\setcpu

Initialize cpu timer. You can use \cpu or \second to show the used cpu time.

\shell

Create a new shell. The program will be suspended. If you terminate the shell (control-d) the program will be reactivated.

\spawn

Syntax: \spawn command
Start a subprocess and execute command.

\status

Show the status of all internal commands.

\store

Syntax: \store aliasname
Save the result of \evaluate into an alias.
\evaluate always stores the result in the alias EVAL_RESULT, and the contents of this alias are copied into the alias you specify.

\time

Show current time.

\title

Syntax: \title string
display the rest of the commandline in the titlebar of the terminal window. This will not work if output is redirected to a file.

\unalias

Undefine aliases. Actions depend on the parameters.

\unalias *
remove all aliases. Use with caution.
\unalias aliasname
remove aliasname.

The first word of a line is always substituted
All following whole words are substituted if they are not preceded by an \alias, \unalias, \store, \import or \export command.
Substitution may be forced by using pairs of single quotes (everything between the quotes will be substituted) or one single quote (substitution from the quote to the end of the word).
One single quote will be removed, two succeeding single quotes are replaced by one.
The disable substitution, add a single quote at the end of a word.

Examples:

Before	With Alias	Without Alias
abcd	[abcd]	abcd
ab'cd	ab[cd]	abcd
'abcd	[abcd]	abcd
ab''cd		ab'cd
''abcd		'abcd
ab'c'd	ab[c]d	abcd
'ab'cd	[ab]cd	abcd
abcd'		abcd

Startup

Some aliases are created at the startup of the program.

alias	value
CONFIG_PATH	path where image configuration files reside
IMAGE_NAME	name of current image
USER_NAME	user invoking the program
WORK_DIR	directory where program was started from
NODE_NAME	host name
PROCESS_MODE	Batch, Interactive.....
PROCESS_NAME	process name or process id

At program startup 3 init files (if they exist) will be executed if the following order:

CONFIG_PATH/IMAGE_NAME.init
CONFIG_PATH/IMAGE_NAME.initlocal
IMAGE_NAME.init in the current directory

Example

This is how a .init file could look like:

#make an alias script1 which executes a file
\alias script1 @'config_path'script1

#if script2 exists, make an alias script2
\if file 'config_path'script2 \alias script2 @'config_path'script2
#so script2 will be an unknown command if the file does not exist

#another approach:
\alias script2 &'config_path'script2
#so script2 will be defined, but does nothing if the file does not exist.

\alias x 600
\alias y 400
\alias w 1000
\alias h 800
\alias zoom2 zoomfactor 2 zoom 'hx'-'w'/4  'hy'-'h'/4  'hx'+'w'/4  'hy'+'h'/4
\alias zoom3 zoomfactor 3 zoom 'hx'-'w'/6  'hy'-'h'/6  'hx'+'w'/6  'hy'+'h'/6
\alias zoom4 zoomfactor 4 zoom 'hx'-'w'/8  'hy'-'h'/8  'hx'+'w'/8  'hy'+'h'/8
\alias zoom5 zoomfactor 5 zoom 'hx'-'w'/10 'hy'-'h'/10 'hx'+'w'/10 'hy'+'h'/10
\unalias w \unalias h \unalias x \unalias y

#go5 will run go 5 times
\alias go5 \repeat 5 go