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)