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, gs‐
menu and the like.
1mOPTIONS0m
1m-f 4m22mprogram-file0m
1m--file 4m22mprogram-file0m
Read a program fragment from the file 4mprogram-file24m. Multiple 1m-f 22mop‐
tions 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-e0m
options 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--fd 22moptions 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 man‐
ager 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 under‐
scores. 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 ambigu‐
ity.
1mOverview0m
The Sindre language is extremely similar to Awk in syntax and semantics,
although there are subtle differences as well. A program primarily con‐
sists 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 declara‐
tion 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 wid‐
gets. 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- (Con‐
trol), 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 Con‐
trol 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 seman‐
tics, 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), dic‐
tionaries, 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 men‐
tioned 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. BE‐
GIN 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.
1mRLENGTH0m
The length of the most recent regular expression match.
1mENVIRON0m
A dictionary containing the environment variables of the Sindre
process. Note that changing this dictionary currently has no ef‐
fect on the environment.
1mEXITVAL0m
Whenever an external program has been run, this variable will con‐
tain its exit value.
1mNumeric functions0m
1mabs(4m22mn24m1m) 22mThe numeric value of 4mn24m.
1matan2(4m22mx24m1m, 4m22my24m1m)0m
Arctangent 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)0m
Return 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 in‐
dex 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)0m
Run 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 ex‐
iting, short of killing the process manually. Actions are executed atomi‐
cally and synchronously, so an infinite loop can freeze the program, re‐
quiring the user to kill it manually.
sindre-VERSION 4mSINDRE24m(1)