SINDRE(1)		    General Commands Manual		     SINDRE(1)



NAME
       sindre - GUI programming language

SYNOPSIS
       sindre [-f program-file] [-e program-text]

DESCRIPTION
       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.

OPTIONS
       -f program-file
       --file program-file
	      Read a program fragment from the file program-file.  Multiple -f
	      options may be used, and may be  interleaved  with  -e  options.
	      See the section on Multiple Fragments below.

       -e program-text
       --expression program-text
	      Read  program fragment from the argument program-text.  Multiple
	      -e options may be used, and may be interleaved with -f  options.
	      See the section on Code Substitution below.

       --fd NAME=FD
	      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 sindre --fd foostream=3
	      3<~/.xsession-errors.  You should never  create  more  than  one
	      stream  per  file  descriptor.   The  standard  input  stream is
	      automatically available as the stream 'stdin'.  If multiple --fd
	      options are given that define the same stream name, the last one
	      will take priority.
       --wmmode normal|dock|override (defaults to override)
	      If normal, put the program under the management  of  the	window
	      manager  as  a  normal  client.	If  dock, run as a dock/panel,
	      assuming window manager support.	 If  override  (the  default),
	      grab  control  of  the display and stay on top until the program
	      terminates.

USAGE
   Lexical conventions
       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.

   Overview
       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

       pattern { statements }

       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 next can  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

       GUI { name=class(parameters) { children } }

       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

       param1 = exp1, param2 = exp2, ... , paramN = expN

       and are evaluated left-to-right.  A parameter whose value is considered
       false (see section VALUES) 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

       name=exp

       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:

       function name(arg1, arg2, ..., argN) { statements }

       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.

   Patterns
       BEGIN  At program startup, after the GUI has been created.
       <key>  When  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, <C-a> means a
	      press of "a" while the Control key is held down,	and  <C-A>  is
	      with  a capital "A".  Modifiers can be chained, so you can match
	      <C-M-Shift-S-H-BackSpace> if you really want to.	The names  for
	      control  characters, such as BackSpace above, are taken from X11
	      keynames.  You can use xev(1) to figure out the names to a given
	      key.
       object->event(name1, name2, ..., nameN)
	      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.
       $class(name)->event(name1, name2, ..., nameN)
	      As  above,  but matches when any widget of the given class sends
	      the named event.	name will be bound to the widget that  emitted
	      the event.
       pat1 || ... || patN
	      Matches if any of the patterns, checked left-to-right, match.

   Statements
       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  continue  or
       break,  with  usual  C  semantics, and return can be used to exit early
       from a function.

   Expressions and Values
       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 [] and  elements  can  be
       added/changed by using the usual Awk-like syntax foo["bar"]=4, although
       the variable must already contain a dictionary or you will get an error
       (so  use  foo=[]  to  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.

   Multiple Fragments
       When  multiple  -f  and	-e  options  are  used,  Sindre   conceptually
       concatenates  the  given  program  text	fragments  in the order of the
       options.  There are two differences from plain concatenation, however:

       Duplicate definitions
	      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.

       Event handling priority
	      Event handlers are run from  top	to  bottom  in	terms  of  the
	      program  text,  but  event  handlers  in later fragments are run
	      first.  Thus,

		      sindre -e 'obj->ev() { print "foo" }
				 obj->ev() { print "bar" }'
			     -e 'obj->ev() { print "baz" }'

	      will print "baz foo bar" whenever the event  obj->ev()  happens.
	      BEGIN declarations are similarly executed in reverse order.

		      sindre -e 'BEGIN { print "I go last" }'
			     -e 'BEGIN { print "I go first" }'
   Special Variables
       RSTART  After regular expression matching, this variable will be set to
	       the index (1-based) of the match.
       RLENGTH The length of the most recent regular expression match.
       ENVIRON A dictionary containing the environment variables of the Sindre
	       process.   Note	that changing this dictionary currently has no
	       effect on the environment.
       EXITVAL Whenever an external program has been run, this	variable  will
	       contain its exit value.

   Numeric functions
       abs(n)	   The numeric value of n.
       atan2(x, y) Arctangent of x/y in radians.
       cos(x)	   Cosine of x, in radians.
       sin(x)	   Sine of x, in radians.
       exp(x)	   Natural exponent of x.
       log(x)	   Natural logarithm of x.
       int(x)	   x truncated to an integer.
       sqrt(x)	   The square root of x.

   String Functions
       Note that indexes are 1-based.
       length(s)       Returns the number of characters in s
       substr(s, m, n) Return  n  characters  of  s,  starting	from character
		       number m.   If  either  norm  is  out  of  bounds,  the
		       resulting string may be less than n characters.
       index(s, t)     Return the index at which t is found in s, or 0 if t is
		       not present.
       match(s, r)     Match the regular expression r against t, returning the
		       index of the first match, as well as setting RMATCH and
		       RLENGTH.
       gsub(r, t, s)   For each match of the regular expression r in s, return
		       a  new  string  where each of those matches is replaced
		       with t.
       sub(r, t, S)    Like sub, but only the first match is replaced.
       tolower(s)      Return an all-lowercase version of s.
       toupper(s)      Return an all-uppercase version of s.

   System Functions
       osystem(s) Run s as a shell command and return its output.
       system(s)  Run s as a shell command and return its exit value.

EXIT STATUS
       Sindre returns a 0 exit status on  success,  and  1  if	there  was  an
       internal problem.

EXAMPLES
       See the examples/ subdirectory of the Sindre source tree.

SEE ALSO
       dmenu(1), awk(1), sinmenu(1)

BUGS
       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)