4mSINDRE24m(1) General Commands Manual 4mSINDRE24m(1)
1mNAME0m
sindre - GUI programming language
1mSYNOPSIS0m
sindre [1m-f 4m22mprogram-file24m] [1m-e 4m22mprogram-text24m]
1mDESCRIPTION0m
Sindre is a programming language inspired by Awk that makes it easy to
write simple graphical programs in the spirit of dzen, dmenu, xmobar,
gsmenu and the like.
1mOPTIONS0m
1m-f 4m22mprogram-file0m
1m--file 4m22mprogram-file0m
Read a program fragment from the file 4mprogram-file24m. Multiple 1m-f0m
options may be used, and may be interleaved with 1m-e 22moptions.
See the section on 1mMultiple Fragments 22mbelow.
1m-e 4m22mprogram-text0m
1m--expression 4m22mprogram-text0m
Read program fragment from the argument 4mprogram-text24m. Multiple
1m-e 22moptions may be used, and may be interleaved with 1m-f 22moptions.
See the section on 1mCode Substitution 22mbelow.
1m--fd 4m22mNAME=FD0m
Create an input stream with the given name that reads from the
given file descriptor. The file descriptor should be created by
the script invoking Sindre, for example 1msindre --fd foostream=30m
1m3<~/.xsession-errors. 22mYou should never create more than one
stream per file descriptor. The standard input stream is
automatically available as the stream 'stdin'. If multiple 1m--fd0m
options are given that define the same stream name, the last one
will take priority.
1m--wmmode 4m22mnormal|dock|override24m 1m(defaults to override)0m
If 4mnormal24m, put the program under the management of the window
manager as a normal client. If 4mdock24m, run as a dock/panel,
assuming window manager support. If 4moverride24m (the default),
grab control of the display and stay on top until the program
terminates.
1mUSAGE0m
1mLexical conventions0m
Identifiers start with a letter and consist of alphanumerics or
underscores. Class names start with a capital letter, while object and
variable names start with lowercase. Line-comments are supported with
// and block comments with /* ... */. Semicolons are used to separate
statements and declarations, although they are optional when not needed
to resolve ambiguity.
1mOverview0m
The Sindre language is extremely similar to Awk in syntax and
semantics, although there are subtle differences as well. A program
primarily consists of action declarations that have the form
4mpattern24m 1m{ 4m22mstatements24m 1m}0m
When an event arrives, each declaration is checked in order, and those
whose pattern matches have their statements executed. Some patterns
also bind variables while executing the statements, like a function
call. The statement 1mnext 22mcan be used to immediately stop further
processing of an event. Additionally there are a few special
declarations. A GUI declaration defines a tree of possibly named
widgets, and looks like
1mGUI { 4m22mname24m1m=4m22mclass24m1m(4m22mparameters24m1m) { 4m22mchildren24m 1m} }0m
where both name (including the equal sign), parameters (including the
parentheses) and children (including the braces) are optional. Each
child follows the same syntax as the body (the text between the braces)
of a GUI declaration, and should be separated by semicolons. Widget
parameters are of the form
4mparam124m 1m= 4m22mexp124m1m, 4m22mparam224m 1m= 4m22mexp224m1m, ... , 4m22mparamN24m 1m= 4m22mexpN0m
and are evaluated left-to-right. A parameter whose value is considered
false (see section 1mVALUES22m) will be ignored if its value is otherwise
not valid for the parameter. Otherwise, an error will occur if the
value is not what the widget expects (for example, the string "foo"
passed as the widget height).
A global variable declaration looks like
4mname24m1m=4m22mexp0m
Global variables are initialised before the GUI is created, so they can
be used in widget parameters. On the other hand, they cannot refer to
widgets. If you need to perform work after the GUI has been created,
use a BEGIN declaration.
Function are defined as in Awk, and recursion is supported:
1mfunction 4m22mname24m1m(4m22marg124m1m, 4m22marg224m1m, ..., 4m22margN24m1m) { 4m22mstatements24m 1m}0m
Arguments are lexically scoped within the function. If a function is
called with fewer arguments than given in its declaration, the
leftovers are given a false value. This is the only way to emulate
local variables.
1mPatterns0m
1mBEGIN 22mAt program startup, after the GUI has been created.
1m<4m22mkey24m1m> 22mWhen the given key is pressed. The syntax for keys is taken
from GNU Emacs and consists of an optional set of modifiers (C-
(Control), M- (Meta/Alt), Shift, S- (Super) or H- (Hyper))
followed by a key name. The Shift modifier is stripped from
keypresses that are characters. For example, 1m<C-a> 22mmeans a
press of "a" while the Control key is held down, and 1m<C-A> 22mis
with a capital "A". Modifiers can be chained, so you can match
1m<C-M-Shift-S-H-BackSpace> 22mif you really want to. The names for
control characters, such as BackSpace above, are taken from X11
keynames. You can use 1mxev22m(1) to figure out the names to a given
key.
4mobject24m1m->4m22mevent24m1m(4m22mname124m1m, 4m22mname224m1m, ..., 4m22mnameN24m1m)0m
Matches when the named object sends the named event. The names
will be bound to the value payload of the event, in the same way
as with a function call.
1m$4m22mclass24m1m(4m22mname24m1m)->4m22mevent24m1m(4m22mname124m1m, 4m22mname224m1m, ..., 4m22mnameN24m1m)0m
As above, but matches when any widget of the given class sends
the named event. 4mname24m will be bound to the widget that emitted
the event.
4mpat124m 1m|| 4m22m...24m 1m|| 4m22mpatN0m
Matches if any of the patterns, checked left-to-right, match.
1mStatements0m
If-conditions, while-loops and for-loops are supported with the same
syntax as in Awk, except that braces are always mandatory. All
variables, except for function parameters, are global and initialised
to false at program startup. A loop can be stopped with 1mcontinue 22mor
1mbreak22m, with usual C semantics, and 1mreturn 22mcan be used to exit early
from a function.
1mExpressions and Values0m
All values, except for objects, are always passed by value in arguments
and return values. Sindre supports numbers (integers and decimal
syntax), dictionaries, strings and objects. Boolean values are
canonically represented as integers, with the number 0 being false and
any other value considered true. Strings follow the Haskell literal
syntax (which is essentially identical to that of C). Objects can be
used as event sources, as mentioned above, and have methods and fields.
A method call has the syntax object.method(args) and a field is
object.field, and can be used as an lvalue. Dictionaries differ
significantly from those in Awk, as they have no special syntactical
treatment. An empty dictionary is written as 1m[] 22mand elements can be
added/changed by using the usual Awk-like syntax 1mfoo["bar"]=422m, although
the variable must already contain a dictionary or you will get an error
(so use 1mfoo=[] 22mto initialise). Keys and values can have any type.
Multidimensional dictionaries are only supported by making the values
dictionaries themselves, and has no special syntax, and arrays are
merely dictionaries with integral keys.
1mMultiple Fragments0m
When multiple 1m-f 22mand 1m-e 22moptions are used, Sindre conceptually
concatenates the given program text fragments in the order of the
options. There are two differences from plain concatenation, however:
1mDuplicate definitions0m
A program fragment is normally not allowed to define two global
variables or functions with the same name, nor to contain two
GUI declarations. When the above options are used,
redefinitions of previous definitions appearing in later
fragments take precedence.
1mEvent handling priority0m
Event handlers are run from top to bottom in terms of the
program text, but event handlers in later fragments are run
first. Thus,
1msindre -e 'obj->ev() { print "foo" }0m
1mobj->ev() { print "bar" }'0m
1m-e 'obj->ev() { print "baz" }'0m
will print "baz foo bar" whenever the event 1mobj->ev() 22mhappens.
BEGIN declarations are similarly executed in reverse order.
1msindre -e 'BEGIN { print "I go last" }'0m
1m-e 'BEGIN { print "I go first" }'0m
1mSpecial Variables0m
1mRSTART 22mAfter regular expression matching, this variable will be set to
the index (1-based) of the match.
1mRLENGTH 22mThe length of the most recent regular expression match.
1mENVIRON 22mA dictionary containing the environment variables of the Sindre
process. Note that changing this dictionary currently has no
effect on the environment.
1mEXITVAL 22mWhenever an external program has been run, this variable will
contain its exit value.
1mNumeric functions0m
1mabs(4m22mn24m1m) 22mThe numeric value of 4mn24m.
1matan2(4m22mx24m1m, 4m22my24m1m) 22mArctangent of 4mx/y24m in radians.
1mcos(4m22mx24m1m) 22mCosine of 4mx24m, in radians.
1msin(4m22mx24m1m) 22mSine of 4mx24m, in radians.
1mexp(4m22mx24m1m) 22mNatural exponent of 4mx24m.
1mlog(4m22mx24m1m) 22mNatural logarithm of 4mx24m.
1mint(4m22mx24m1m) 4m22mx24m truncated to an integer.
1msqrt(4m22mx24m1m) 22mThe square root of 4mx24m.
1mString Functions0m
Note that indexes are 1-based.
1mlength(4m22ms24m1m) 22mReturns the number of characters in 4ms0m
1msubstr(4m22ms24m1m, 4m22mm24m1m, 4m22mn24m1m) 22mReturn 4mn24m characters of 4ms24m, starting from character
number 4mm24m. If either 4mn24mor4mm24m is out of bounds, the
resulting string may be less than 4mn24m characters.
1mindex(4m22ms24m1m, 4m22mt24m1m) 22mReturn the index at which 4mt24m is found in 4ms24m, or 0 if 4mt24m is
not present.
1mmatch(4m22ms24m1m, 4m22mr24m1m) 22mMatch the regular expression 4mr24m against 4mt24m, returning the
index of the first match, as well as setting 1mRMATCH 22mand
1mRLENGTH22m.
1mgsub(4m22mr24m1m, 4m22mt24m1m, 4m22ms24m1m) 22mFor each match of the regular expression 4mr24m in 4ms24m, return
a new string where each of those matches is replaced
with 4mt24m.
1msub(4m22mr24m1m, 4m22mt24m1m, 4m22mS24m1m) 22mLike 4msub24m, but only the first match is replaced.
1mtolower(4m22ms24m1m) 22mReturn an all-lowercase version of 4ms24m.
1mtoupper(4m22ms24m1m) 22mReturn an all-uppercase version of 4ms24m.
1mSystem Functions0m
1mosystem(4m22ms24m1m) 22mRun 4ms24m as a shell command and return its output.
1msystem(4m22ms24m1m) 22mRun 4ms24m as a shell command and return its exit value.
1mEXIT STATUS0m
Sindre returns a 1m0 22mexit status on success, and 1m1 22mif there was an
internal problem.
1mEXAMPLES0m
See the examples/ subdirectory of the Sindre source tree.
1mSEE ALSO0m
1mdmenu22m(1), 1mawk22m(1), 1msinmenu22m(1)
1mBUGS0m
The syntax and semantics for local variables are inherited from Awk,
and are rather ugly. It is possible to write programs that have no way
of exiting, short of killing the process manually. Actions are
executed atomically and synchronously, so an infinite loop can freeze
the program, requiring the user to kill it manually.
sindre-VERSION 4mSINDRE24m(1)