SINDRE(1)		    General Commands Manual		     SINDRE(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 4mn0m
		       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			     SINDRE(1)