<box begindoc>**This is automatically generated documentation.**  Edit after the "[[#COMMENTS|COMMENTS]]" heading; changes to the main body will be lost.</box>

====== Script Element Documentation ======

===== NAME =====

**Script** -- Click element;
script a Click router configuration

===== SYNOPSIS =====

Script(INSTRUCTIONS...)

**Ports**: none\\ 
**Package**: standard (core)\\ 

===== DESCRIPTION =====

The Script element implements a simple scripting language useful for
controlling Click configurations.  Scripts can set variables, call handlers,
wait for prodding from other elements, and stop the router.


===== INSTRUCTIONS =====

Each configuration argument is an //instruction// (except for optional
keywords; see below).  Script generally processes these instructions
sequentially.


==== Handler Instructions ====

In all cases, text arguments are subject to substitutions; see below.


 ? **%%'%%''set'' VAR TEXT'**
 ! Sets the script variable $VAR to TEXT.

 ? **%%'%%''init'' VAR TEXT'**
 ! Initializes the script variable $VAR to TEXT.  This assignment happens exactly
once, when the Script element is initialized; later the instruction has no
effect.

 ? **%%'%%''print'' [>FILE | >>FILE] [TEXT | HANDLER]'**
 ! Prints text, or the result of calling a read handler, followed by a newline.
At user level, the text is written to the standard output, except that if the
argument begins with > or >>, then the text is written or appended to the
specified FILE.  In the kernel, the text is written to the system log.
If ''print''%%'%%s argument starts with a letter, '@', or '_', then it is treated
as a read handler.  Otherwise, it is treated as quoted text; Script prints the
unquoted version.  For example, assuming the 'c.count' read handler
returns "0":
     print c.count     => 0
     print "c.count"   => c.count
     print '"c.count"' => "c.count"
     set x c.count
     print $x          => c.count
     print $($x)       => 0


 ? **%%'%%''read'' HANDLER [ARG...]'**
 ! Call a read handler and print the handler name and result to standard error.  (In the kernel, the result is printed to the system log.)  For example, the
configuration 'Idle -> c::Counter -> Idle; Script(read c.count)' would print
print this to standard error:
     c.count:
     0
Contrast the %%'%%''print''%%'%% instruction.


 ? **%%'%%''write'' HANDLER [ARG...]'**
 ! Call a write handler.  The handler's return status is available in following
instructions as the '$?' variable.

 ? **%%'%%''readq'' HANDLER [ARG...]', %%'%%''writeq'' HANDLER [ARG...]'**
 ! Same as ''read'' and ''write'', but removes one layer of quoting from the ARGs
before calling the handler.


==== Blocking Instructions ====


 ? **%%'%%''pause'' [COUNT]'**
 ! Block until the Script element's 'step' handler is called COUNT times.  COUNT
defaults to 1.

 ? **%%'%%''wait'' TIME'**
 ! Wait for TIME seconds, or until a step, whichever comes first; then go to the
next instruction.  TIME has microsecond precision.


==== Control Instructions ====


 ? **%%'%%''label'' LABEL'**
 ! Defines a label named LABEL.

 ? **%%'%%''goto'' LABEL [CONDITION]'**
 ! Transfers control to the named label.  Script elements detect loops; if an
element's script appears to be looping (it executes 1000 goto instructions
without blocking), the script is disabled.  If CONDITION is supplied, then the
branch executes only when CONDITION is true.
As a special case, %%'%%''goto exit [CONDITION]''%%'%% or %%'%%''goto end [CONDITION]''%%'%%
ends execution of the script, much like an %%'%%''exit''%%'%% or %%'%%''end''%%'%% instruction.

 ? **%%'%%''loop''%%'%%**
 ! Transfers control to the first instruction.

 ? **%%'%%''return'' [VALUE]'**
 ! End execution of this script, returning VALUE.  This instruction is most
useful for passive scripts; VALUE will be returned as the value of the ''run''
handler.

 ? **%%'%%''exit''%%'%%, %%'%%''end''%%'%%**
 ! End execution of this script.  For signal scripts, the %%'%%''exit''%%'%% instruction
//does not// reinstall the script, whereas the %%'%%''end''%%'%% instruction does.


===== SCRIPT TYPES =====

Scripts come in several types, including active scripts, which start running
as soon as the configuration is loaded; passive scripts, which run only when
prodded; signal scripts, which run in response to a signal; and driver
scripts, which are active scripts that also control when the driver stops.
The optional TYPE keyword argument is used to select a script type.  The types
are:


 ? **''ACTIVE''**
 ! An active script starts running as soon as the router is initialized.  This is
the default.

 ? **''PASSIVE''**
 ! A passive script runs in response to a handler, namely the ''run'' handler.
Passive scripts can help build complex handlers from existing simple ones; for
example, here's a passive script whose ''s.run'' read handler returns the sum
of two Counter handlers.
     ... c1 :: Counter ... c2 :: Counter ...
     s :: Script(TYPE PASSIVE,
            return $(add $(c1.count) $(c2.count)))
Within the script, the ''run'' handler's arguments, if any, are available
via the ''$args'' variable.  The first, second, and so forth space-separated
portions of ''$args'' are available via the ''$1'', ''$2'', ... variables.
            

 ? **''DRIVER''**
 ! A driver script manages the Click driver's stop events.  See [[DriverManager]] for
more information.

 ? **''SIGNAL'' SIGNO...**
 ! User-level only: A signal script runs in response to the signal(s) specified
by the SIGNO argument(s).  Each SIGNO can be an integer or a signal name, such
as INT or HUP.  Soon after the driver receives a named signal, this script
will run.  The signal handler is automatically blocked until the script runs.
The signal script will be reinstalled atomically as long as the script
completes without blocking.  If it blocks, however, the signal script will not
be installed from the blocking point until the script completes.  If multiple
Script elements select the same signal, all the scripts will run.


===== SUBSTITUTIONS =====

Text in most Script instructions undergoes variable substitution.  References
to script variables, such as %%'%%''$x''%%'%%, are replaced by the variable text.
Additionally, the form %%'%%''$(HANDLER [ARG...])''%%'%% can be used to interpolate a
read handler's value.  Variable and handler references can be nested inside
a %%'%%''$(...)''%%'%% block.  For example, the following script will print 0, 1, 2, 3,
and 4 on separate lines, then exit.  Note the use of Script's arithmetic
handlers.
     s :: Script(set x 0,
                 label begin_loop,
                 print $x,
                 set x $(s.add $x 1),
                 goto begin_loop $(s.lt $x 5),
                 stop);
This can be further shortened since local handler references do not require
the element name.  Thus, "$(s.add ...)" can be written "$(add ...)", as below.
     Script(set x 0,
            label begin_loop,
            print $x,
            set x $(add $x 1),
            goto begin_loop $(lt $x 5),
            stop);


===== ELEMENT HANDLERS =====


 ? **step (write-only)**
 ! Advance the instruction pointer past the current blocking instruction (''pause'' or ''wait'').  A numeric argument will step past that many blocking instructions.

 ? **goto (write-only)**
 ! Move the instruction pointer to the specified label.

 ? **run (read/write)**
 ! Run the script.  If the script ends with a %%'%%''return''%%'%% instruction, then the
handler returns with that value.

 ? **add (read with parameters)**
 ! Useful for arithmetic.  Adds a space-separated list of integers; for example,
%%'%%''add 10 5 2''%%'%% returns "''17''".  (At user level, the arithmetic and
comparison operators can parse floating-point numbers as well as integers.)

 ? **sub (read with parameters)**
 ! Subtracts a space-separated list of
numbers; for example, %%'%%''sub 10 5 2''%%'%% returns
"''3''".

 ? **mul, div, idiv (read with parameters)**
 ! Multiplies or divides a space-separated list of numbers and returns the
result.  At user level, the %%'%%''idiv''%%'%% handler truncates its result to an
integer and returns that, whereas the %%'%%''div''%%'%% handler returns a
floating-point number; in the kernel, %%'%%''idiv''%%'%% and %%'%%''div''%%'%% both perform
integer division.

 ? **eq, ne, lt, gt, le, ge (read with parameters)**
 ! Compares two parameters and return the result.  For example, %%'%%''eq 10
0xA''%%'%% returns "''true''", but %%'%%''le 9 8''%%'%% returns "''false''".  If either
parameter cannot be interpreted as a number, performs a string comparison.
For example, %%'%%''eq 10x 10x''%%'%% return "''true''".

 ? **not (read with parameters)**
 ! Useful for true/false operations.  Parses its parameter as a Boolean and
returns its negation.

 ? **sprintf (read with parameters)**
 ! Parses its parameters as a space-separated list of arguments.  The first
argument is a format string; the remaining arguments are formatted
accordingly.  For example, %%'%%''sprintf "%05x" 127''%%'%% returns "''0007F''".


===== SEE ALSO =====

[[DriverManager]]


Generated by 'click-elem2man' from '../elements/standard/script.hh' on 18/Jul/2007.


===== COMMENTS =====