Category:Guish: Difference between revisions

From Rosetta Code
Content added Content deleted
No edit summary
No edit summary
Line 13: Line 13:




'''guish''' ['''-h''']['''-e''']['''-z''']['''-c''']['''-q''']['''-x''']['''-d''']['''-F''']['''-V''']['''-v <var>=<val>''']['''-f''' <file>][<code>]
'''guish''' ['''-c''' <code>]['''-s''']['''-q''']['''-k''']['''-t''']['''-f''']['''-v''']['''-h'''][<file>]


= DESCRIPTION =
= DESCRIPTION =
Line 27: Line 27:




; '''-h'''
; '''-c <code>'''
: read and execute commands from command line.
: guess
; '''-e'''
; '''-s'''
: quit program on errors/warnings.
; '''-z'''
: display elements when created.
: display elements when created.
; '''-c'''
: quit guish when closing last element/window.
; '''-q'''
; '''-q'''
: quit when closing last element/window.
; '''-k'''
: terminate all external programs when quitting.
: terminate all external programs when quitting.
; '''-x'''
; '''-t'''
: fallback on tty after reading data from other inputs.
: fallback on tty after reading data from other inputs.
; '''-d'''
; '''-f'''
: show available X11 fonts.
: daemonize, excluding fallback on tty if set.
; '''-F'''
; '''-v'''
: show available x11 fonts.
; '''-V'''
: show version.
: show version.
; '''-v <var>=<val>'''
; '''-h'''
: guess.
: register a variable with value, can be used multiple times.
; '''-f <file>'''
: read and execute commands from <file>.


= INPUTS AND SOURCES =
= INPUTS AND SOURCES =
Line 54: Line 48:




guish reads commands from multiple source sequentially; these source are: command line, file, standard input, and if '''-x''' option is given, controlling terminal. After reading commands from a source, it tries to switch to another one, and when there are no more sources, it simply stays idle.
guish reads commands from multiple source sequentially; these source are: command line (with '''-c''' option), file, standard input, and if '''-t''' option is given, controlling terminal. After reading commands from a source, it tries to switch to another one, and when there are no more sources, it simply stays idle.


So this is the sequence: if there is a file (script) specified with '''-f''' option, execute from there, else if there are commands on command line, execute them. If standard input is a pipe, switch to it and execute from there, then finally switch to controlling terminal (if '''-x''' option is given) and execute from there.
After executing from file or command line or standard input, then finally it switchs to controlling terminal (if '''-t''' option is given) and executes from there.


If a named pipe is given with '''-f''' option, then it will be opened in non-blocking mode, allowing to issue commands from the other end of the pipe.
If the file given is a named pipe, then it will be opened in non-blocking mode, allowing to issue commands from the other end of the pipe.


= SYNTAX OVERVIEW =
= SYNTAX OVERVIEW =
Line 130: Line 124:
Here the evaluation of the code block is done when the click signal is triggered.
Here the evaluation of the code block is done when the click signal is triggered.


== Scopes ==
== Scopes and closures ==




Line 151: Line 145:
Here "a" is defined in the global scope, then modified from block scope and printed from there, and its value doesn't change.
Here "a" is defined in the global scope, then modified from block scope and printed from there, and its value doesn't change.


If a variable is defined inside a block, then all embedded blocks that reference that variable will get its value at definition time (a closure):

<pre> {
a = 1
return {
puts @a
}
}()()</pre>
== Quotes, blocks and functions ==
== Quotes, blocks and functions ==


Line 157: Line 159:
There are single and double quoting: anything embedded inside single quotes '', is treated literally (no escaping takes place) and as a single token.
There are single and double quoting: anything embedded inside single quotes '', is treated literally (no escaping takes place) and as a single token.


Variable interpolation is used inside double quotes &quot;&quot;, external command substitution quotes ``, element expressions || and external window id substitution &lt;( ).
Variable interpolation is used inside double quotes &quot;&quot;, external command substitution quotes `` and external window id substitution &lt;( ).


Escaping (&quot;\n\t\r\f\v\b&quot;) takes place only inside double quotes &quot;&quot;.
Escaping (&quot;\n\t\r\f\v\b&quot;) takes place only inside double quotes &quot;&quot;.


<pre> a = 'my string'; puts &quot;this is: @{a}&quot;</pre>
<pre> a = 'my string'; puts &quot;this is: @{a}&quot;</pre>
Anything embedded inside '''{}''' is treated as a code block and no variable substitution is done at definition time except when using the special operator '''%''':
Anything embedded inside '''{}''' is treated as a code block and no variable substitution is done at definition time.


To &quot;execute&quot; a block, simply use parens '''()'''. If arguments are given, they can be referenced inside block by using '''@n''', where &quot;n&quot; is a number which represents a specific argument by position (indexes start at 1). To refer to all arguments (at once) given to the block use '''@*''' operator (when in string interpolation, argument separator is a space).
<pre> a = 1234; fn = {puts(&quot;here&quot;, %a)}; fn()</pre>
To &quot;execute&quot; a block, simply use parens '''()'''. If arguments are given, they can be referenced inside block by using '''@n''', where &quot;n&quot; is a number which represents a specific argument by position (indexes start at 1). To refer to all arguments given to the block as a &quot;list&quot; instead, it's possible to use '''@*''' operator (when in string interpolation, argument separator is a space).


<pre> v = myvar
<pre> v = myvar
Line 180: Line 181:


<pre> fn = {return add(@1, @2)}
<pre> fn = {return add(@1, @2)}
puts join(&quot; &quot;, &quot;my func res:&quot;, fn(2, 4)) </pre>
puts join(&quot;my func res:&quot;, fn(2, 4)) </pre>
In addition, when defining a new function, it's possible to &quot;overwrite&quot; the builtin functions in the current scope.
In addition, when defining a new function, it's possible to &quot;overwrite&quot; the builtin functions in the current scope.


Line 186: Line 187:


<pre> fn = {return 1 2 3}
<pre> fn = {return 1 2 3}
puts join('+', fn())</pre>
puts join(fn())</pre>
== Joining ==



By using the special '''++''' operator, it's possible to join tokens and blocks; it works simirarly to the '''join''' function, except that the second operand it's treated always as a token (even if it is a '{').

<pre> puts a ++ b</pre>
== Conditionals ==
== Conditionals ==






Anything equal to 0 or &quot;empty&quot; (like '''''''', '''&quot;&quot;''') is false, true otherwise. This is useful with '''if''' and '''else''' commands:
Anything equal to 0, &quot;0&quot; or empty (like '''''''', '''&quot;&quot;''', '''{}''') is false, true otherwise. This is useful with '''if''' and '''else''' commands:


<pre> if 1 { |b|&lt;text } else { |b|&lt;neverhere }</pre>
<pre> if 1 { |b|&lt;text } else { |b|&lt;neverhere }</pre>
Line 197: Line 205:


<pre> if ge(@a,4) { |l|&lt;4 }</pre>
<pre> if ge(@a,4) { |l|&lt;4 }</pre>
It is possible to &quot;exit&quot; a block with the '''leave''' command on a certain condition too:

<pre> if seq(t(@a), 'b') {
puts &quot;a button!&quot;
leave seq(d(@a), &quot;test&quot;)
puts &quot;end of if&quot;
}</pre>
In the last example, the execution jumps out of the &quot;if&quot; block if the text of the button is equal to &quot;test&quot;, otherwise it reaches the last block command and prints &quot;end of it&quot;.

== Loops and iteration ==
== Loops and iteration ==


Line 218: Line 217:
}
}
puts 'end'</pre>
puts 'end'</pre>
And here another one of a '''for''' loop:
And here another one using '''each''' function:

<pre> each({puts @1}, 1, 2, 3, 4, 5}</pre>
And another one of a '''for''' loop:


<pre> for x 1 2 3 4 { puts @x }</pre>
<pre> for x 1 2 3 4 { puts @x }</pre>
Line 259: Line 261:


<pre> |b|&lt;`echo clickme`</pre>
<pre> |b|&lt;`echo clickme`</pre>
== Expressions ==
== Slicing ==




Anything inside '''[]''' is trated as a slice expression. The usage is [&lt;n&gt;[,&lt;x&gt;]], when &lt;n&gt; is an index, and &lt;x&gt; is an optional end index (always inclusive); if the preceding argument is a regular token, then the expression will return its characters as specified by index(es), otherwise if it's a block, the expression will return its tokens:


<pre> puts {1, 2, 3, 4, {a, b}, cat}[4][1]</pre>
The output of this example is 'b'.


If the index(es) given are out of range, an empty token is returned.
<pre> puts add(4, mul(5, 6))</pre>
Here 34 is printed by '''puts''' special command.


= SPECIAL VARIABLES =
= SPECIAL VARIABLES =
Line 309: Line 315:
: A checkbox.
: A checkbox.


= COMMANDS =
= SPECIAL COMMANDS =



== Special commands ==




Line 321: Line 323:
; '''=&gt; &lt;signal&gt; &lt;subcmd&gt;'''
; '''=&gt; &lt;signal&gt; &lt;subcmd&gt;'''
: register a sub-command &lt;subcmd&gt; to run when &lt;signal&gt; triggers. For normal signals (eg. signals tied to elements), there must exist an implied subject.
: register a sub-command &lt;subcmd&gt; to run when &lt;signal&gt; triggers. For normal signals (eg. signals tied to elements), there must exist an implied subject.
; '''global &lt;var&gt; = &lt;val&gt;'''
: defines a variable using the same rules of variable definition, but defining that variable in the global scope; this usually can be used inside functions to define a global variable which doesn't exist already.
; '''q'''
; '''q'''
: quit guish.
: quit guish (exit status 0).
; '''exit &lt;status&gt;'''
: quit guish (exit status &lt;status&gt;).
; '''run &lt;cmd&gt;'''
; '''run &lt;cmd&gt;'''
: execute shell command &lt;cmd&gt;.
: execute shell command &lt;cmd&gt;.
Line 333: Line 339:
; '''e &lt;arg&gt;'''
; '''e &lt;arg&gt;'''
: print &lt;arg&gt; to stderr.
: print &lt;arg&gt; to stderr.
; '''unset &lt;name/scheduled num&gt;'''
; '''unset &lt;namescheduled num&gt;'''
: unset variable or timed scheduled procedure registered with &lt;num&gt;, see '''every''' command.
: unset variable or timed scheduled procedure registered with &lt;num&gt;, see '''every''' command.
; '''source &lt;file&gt;'''
; '''source &lt;file&gt;'''
Line 343: Line 349:
; '''del &lt;wid&gt;'''
; '''del &lt;wid&gt;'''
: delete a widget with id &lt;wid&gt;.
: delete a widget with id &lt;wid&gt;.
; '''opts'''
: show options status on standard error.
; '''setopt &lt;name&gt; &lt;val&gt;'''
: set an option using name and val.
; '''every &lt;seconds&gt; &lt;block&gt;'''
; '''every &lt;seconds&gt; &lt;block&gt;'''
: schedule &lt;code&gt; to run after &lt;seconds&gt; seconds are elapsed.
: schedule &lt;code&gt; to run after &lt;seconds&gt; seconds are elapsed.
Line 361: Line 363:
; '''return &lt;phrase&gt;'''
; '''return &lt;phrase&gt;'''
: when used inside a function, returns all its arguments (the remaining phrase) to the caller.
: when used inside a function, returns all its arguments (the remaining phrase) to the caller.
; '''leave &lt;condition&gt;'''
: leaves the enclosing block if &lt;condition&gt; evaluates to true (does not apply to loops).
; '''while &lt;condition&gt; &lt;block&gt;'''
; '''while &lt;condition&gt; &lt;block&gt;'''
: executes &lt;block&gt; until &lt;condition&gt; evaluates to true (see Conditionals).
: executes &lt;block&gt; until &lt;condition&gt; evaluates to true (see Conditionals).
Line 380: Line 380:
: send control key sequence to an element (must be enabled at compilation time).
: send control key sequence to an element (must be enabled at compilation time).


== Generic commands ==
= GENERIC COMMANDS =




Line 436: Line 436:
; '''nbfill'''
; '''nbfill'''
: resize an element in bottom direction to fit its parent.
: resize an element in bottom direction to fit its parent.
; '''at &lt;x&gt; &lt;y&gt;'''
: when setting text, write text at &lt;x&gt; &lt;y&gt; coords inside element.
; '''L'''
; '''L'''
: clear element's data.
: clear element's data.
Line 448: Line 446:
; '''z &lt;w&gt; &lt;h&gt;'''
; '''z &lt;w&gt; &lt;h&gt;'''
: resize element by width and height.
: resize element by width and height.
; '''i'''
: increment element's width by 10px.
; '''I'''
: decrement element's width by 10px.
; '''k'''
: increment element's height by 10px.
; '''K'''
: decrement element's height by 10px.
; '''m &lt;x&gt; &lt;y&gt;'''
; '''m &lt;x&gt; &lt;y&gt;'''
: move element to coords &lt;x&gt; &lt;y&gt;.
: move element to coords &lt;x&gt; &lt;y&gt;.
; '''&gt; &lt;element&gt; &lt;alignment&gt;'''
; '''A &lt;element&gt; &lt;alignment&gt;'''
: moves implied element to &lt;element&gt; using &lt;alignment&gt; (see alignment in STYLE AND ATTRIBUTES section, as &lt;alignment&gt; opts are similar).
: moves implied element to &lt;element&gt; using &lt;alignment&gt; (see alignment in STYLE AND ATTRIBUTES section, as &lt;alignment&gt; opts are similar).
; '''&lt; &lt;text&gt;'''
; '''&lt; &lt;text&gt;'''
Line 464: Line 454:
; '''&lt;+ &lt;text&gt;'''
; '''&lt;+ &lt;text&gt;'''
: add additional text to element text using &lt;text&gt;.
: add additional text to element text using &lt;text&gt;.
; '''&gt; &lt;var&gt;'''
: define a variable named &lt;var&gt; using element text to set its value.
; '''g'''
; '''g'''
: enable/disable (toggle) moving the parent of the element by click-and-drag it. Enabling this will automatically exclude x/y moving flags below.
: enable/disable (toggle) moving the parent of the element by click-and-drag it. Enabling this will automatically exclude x/y moving flags below.
Line 471: Line 463:
: enable/disable (toggle) moving an element inside its parent by click-and-drag on y axis Enabling this will automatically exclude the flag to click-and-drag and move parent.
: enable/disable (toggle) moving an element inside its parent by click-and-drag on y axis Enabling this will automatically exclude the flag to click-and-drag and move parent.


== Normal commands ==
= NORMAL COMMANDS =





Normal commands are per element.


'''checkbox commands'''
== checkbox commands ==


; '''C'''
; '''C'''
Line 484: Line 474:
: uncheck.
: uncheck.


'''input commands'''
== input commands ==


; '''S'''
; '''S'''
Line 495: Line 485:
: toggles &quot;go to the next line&quot; when hitting return (triggers return signal anyway).
: toggles &quot;go to the next line&quot; when hitting return (triggers return signal anyway).


'''page commands'''
== page commands ==


; '''Q'''
; '''Q'''
Line 520: Line 510:
: inverts the order of sub-elements.
: inverts the order of sub-elements.


= SIGNALS =
= SPECIAL SIGNALS =






; Special signals are independent from elements, and are tied to internal guish events.
== Special signals ==
:



Special signals are independent from elements, and are tied to internal guish events.

; '''q'''
; '''q'''
: triggered at program exit.
: triggered at program exit.
Line 535: Line 521:
: triggered when program receives a SIGINT or a SIGTERM.
: triggered when program receives a SIGINT or a SIGTERM.


== Generic signals ==
= GENERIC SIGNALS =





Generic signals are common to all elements.


; Generic signals are common to all elements.
:
; '''x'''
; '''x'''
: triggered when element is closed.
: triggered when element is closed.
Line 592: Line 578:
: triggered when un-focusing the element.
: triggered when un-focusing the element.


== Normal signals ==
= NORMAL SIGNALS =






Normal signals are per element.
; Normal signals are per element.
:


'''checkbox signals'''
== checkbox signals ==


; '''U'''
; '''U'''
Line 605: Line 592:
: triggered when checkbox is checked.
: triggered when checkbox is checked.


'''input signals'''
== input signals ==


; '''R'''
; '''R'''
Line 652: Line 639:




With the '''=''' operator (actually, it's a special statement command), it's possible to assign a value to a variable, reusing it later by simply referencing it using '''@''' operator when not inside quotes or by wrapping it inside '''@{}''' when in double quotes or shell command substitution quotes '''``'''.
With the '''=''' operator (actually, it's a special statement command), it's possible to assign a value to a variable, reusing it later by simply referencing it using '''@''' operator when not inside quotes or by wrapping it inside '''@{}''' when in double quotes, shell command substitution quotes '''``''', or external window id substitution '''&lt;( )'''.

In addition, with the special operator '''%''', it is possible to substitute a variable into a code block at definition time; in this case if the variable is not defined, the &quot;%var&quot; will remain inside the block, instead of being removed as in plain variable subsitution with '''@''' operator.


There are two methods to define/create empty variables: by explicitely assing an empty string to a variable (ex. a = &quot;&quot;) or by simply omit the value (ex. a =).
There are two methods to define/create empty variables: by explicitely assing an empty string to a variable (ex. a = &quot;&quot;) or by simply omit the value (ex. a =).
Line 679: Line 664:
name = 'random name'
name = 'random name'
puts &quot;@{gname} is maybe @{name}&quot;</pre>
puts &quot;@{gname} is maybe @{name}&quot;</pre>
It's also possible to assign &quot;lists&quot; to a variable by putting the tokens inside '''[]''':

<pre> a = [a, b]; for x @a { puts @x }</pre>
Beware that this works just for assignment and '''let''' function.

== Element substitution ==
== Element substitution ==


Line 780: Line 760:
; '''env(&lt;var&gt;)'''
; '''env(&lt;var&gt;)'''
: returns the value of the environment variable &quot;var&quot;
: returns the value of the environment variable &quot;var&quot;
; '''rev(...)'''
; '''rev([&lt;block&gt;], ...)'''
: returns a reversed list of arguments. This function is somewhat special, as when there are no arguments to get, it'll return nothing (statement behaviour).
: if a block is given as first argument, its element will be returned in reverse, otherwise '''rev''' will return all its arguments in reverse. This function is somewhat special, as when there are no arguments to get, it'll return nothing (statement behaviour).
; '''let([&lt;var&gt;, &lt;val&gt;], ...)'''
; '''let([&lt;var&gt;, &lt;val&gt;], ...)'''
: sets variables, works exactly like assignment with special operator '''=''', but in expressions. This function is somewhat special, it'll return nothing (statement behaviour).
: sets variables, works exactly like assignment with special operator '''=''', but in expressions. This function is somewhat special, it'll return nothing (statement behaviour).
; '''if(&lt;cond&gt;, [&lt;v1&gt;, [&lt;v2&gt;]])'''
; '''list(...)'''
: if &lt;cond&gt; is true and &lt;v1&gt; is given, returns &lt;v1&gt;, else if &lt;cond&gt; is false and &lt;v2&gt; is given, returns &lt;v2&gt;.
; '''flat(...)'''
: returns all given arguments; if a block is found, then it is flatted.
: returns all given arguments; if a block is found, then it is flatted.
; '''block(...)'''
; '''block(...)'''
Line 802: Line 784:
; '''slice(&lt;si&gt;, &lt;ei&gt;, ...)'''
; '''slice(&lt;si&gt;, &lt;ei&gt;, ...)'''
: returns arguments starting at &quot;si&quot; and ending at &quot;ei&quot; (inclusive). This function is somewhat special, as when there is nothing to get, it'll return nothing (statement behaviour).
: returns arguments starting at &quot;si&quot; and ending at &quot;ei&quot; (inclusive). This function is somewhat special, as when there is nothing to get, it'll return nothing (statement behaviour).
; '''head(...)'''
: returns the first argument given. This function is somewhat special, as when there are no tokens to get.
; '''tail(...)'''
: returns all arguments except the first one. This function is somewhat special, as when there is nothing to get, it'll return nothing (statement behaviour).
; '''times(&lt;n&gt;, &lt;arg&gt;)'''
; '''times(&lt;n&gt;, &lt;arg&gt;)'''
: returns a &quot;list&quot; made by &lt;n&gt; times &lt;arg&gt;. This function is somewhat special, as when there are 0 tokens to replicate, it'll return nothing (statement behaviour).
: returns a sequence of tokens made by &lt;n&gt; times &lt;arg&gt;. This function is somewhat special, as when there are 0 tokens to replicate, it'll return nothing (statement behaviour).
; '''get(&lt;name&gt;)'''
; '''get(&lt;name&gt;)'''
: returns the value of the variable with name &lt;name&gt;, or an empty token if the variable doesn't exist.
: returns the value of the variable with name &lt;name&gt;, or an empty token if the variable doesn't exist.
Line 816: Line 794:
; '''false(&lt;arg&gt;)'''
; '''false(&lt;arg&gt;)'''
: returns 0 if &lt;arg&gt; is true, 1 otherwise.
: returns 0 if &lt;arg&gt; is true, 1 otherwise.
; '''in(&lt;substr&gt;, &lt;token&gt;)'''
; '''in(&lt;n&gt;, &lt;heap&gt;)'''
: returns 1 if substr is found in token, otherwise 0.
: returns 1 if &lt;n&gt; is found in &lt;heap&gt;, 0 otherwise; the arguments can be of any type (single tokens and blocks).
; '''join(&lt;sep&gt;, ...)'''
; '''join(...)'''
: joins blocks and/or tokens by applying the following rules to all arguments given, and accumulates the result as the first operand. If the operands are blocks, then a single new block is created by joining them; if the operands are tokens, then a single new token is created by joining them, and its type will be that of the &quot;second&quot; token; if the operands are mixed (eg. a block and a token), then the token will be embedded inside the block.
: returns a single token from a variable number of tokens, joining them using &lt;sep&gt;; resulting token will have the same type of &lt;sep&gt;.
; '''range(&lt;start&gt;, &lt;end&gt;)'''
; '''range(&lt;start&gt;, &lt;end&gt;)'''
: returns integers starting at &lt;start&gt; and ending at &lt;end&gt; (inclusive) as multiple tokens.
: returns integers starting at &lt;start&gt; and ending at &lt;end&gt; (inclusive) as multiple tokens.
Line 970: Line 948:


Francesco Palumbo &lt;phranz@subfc.net&gt;
Francesco Palumbo &lt;phranz@subfc.net&gt;

= THANKS =



La vera Napoli, Carme, Pico, Titina, Molly, Leo, i miei amati nonni, mio padre, mia madre, e tutti coloro su cui ho potuto e posso contare. Grazie mille.


= LICENSE =
= LICENSE =

Revision as of 19:05, 4 January 2023

Language
Guish
This programming language may be used to instruct a computer to perform a task.
Official website
See Also:


Listed below are all of the tasks on Rosetta Code which have been solved using Guish.

NAME

guish - A language to make and modify GUIs

SYNOPSIS

guish [-c <code>][-s][-q][-k][-t][-f][-v][-h][<file>]

DESCRIPTION

guish is a language to create and modify GUIs; it can be used to tie different programs together by embedding, or to make simple GUIs.

This is version 2.x, which depends just on Xlib as all toolkits have been removed (there are some optional dependencies).

OPTIONS

-c <code>
read and execute commands from command line.
-s
display elements when created.
-q
quit when closing last element/window.
-k
terminate all external programs when quitting.
-t
fallback on tty after reading data from other inputs.
-f
show available X11 fonts.
-v
show version.
-h
guess.

INPUTS AND SOURCES

guish reads commands from multiple source sequentially; these source are: command line (with -c option), file, standard input, and if -t option is given, controlling terminal. After reading commands from a source, it tries to switch to another one, and when there are no more sources, it simply stays idle.

After executing from file or command line or standard input, then finally it switchs to controlling terminal (if -t option is given) and executes from there.

If the file given is a named pipe, then it will be opened in non-blocking mode, allowing to issue commands from the other end of the pipe.

SYNTAX OVERVIEW

Being a command interpreter, guish has a little set of syntax rules. They comprises expressions, commands, quotes and special operators. Generic commands and signals are common to all elements, while there are ones which are specific to each element. A phrase is the execution unit, and ends if the program encounters a newline-like character, or a semicolon (";").

Comments

Single line comments begin with a #, and end at newline like character:

 a = 4 # this is a comment

Multiline comments instead are embedded inside #[ and ]# (or end at the end of source):

 a = 4 #[ This,
 is a multiline comment,
 ending here. ]# puts "a: @{a}"

Elements and element expressions

Elements are basically widgets and have some commands and signals associated with them; they can be created using element expressions, enclosing element name within ||:

 |b|+

In this example, "|b|" is an expression which creates an element of type button, and returns its X11 window id (ex, "65011718").

The + command will then show the button (all elements are hidden by default unless -z option is given).

Subject and implied subject

To refer to the last created/modified element, you can use it without naming it explicitly, for example:

 |i|;+

The "+" command will by applied to element created by "|i|" expression automatically.

Variables and variable substitution

We can refer to elements by using variable substitution, instead of using their window ids:

 bt = |b|

and then:

 @bt < "new button"

Commands

Commands instead can be of three distinct types: special, generic and normal.

Special commands are meant to change guish behaviour, generic ones are meant to modify an element of any type and normal ones are for a specific element type (every element can have specialized commands).

Signals

Signals make it possible to run actions on UI changes (or, more generally, on some events).

 |b|=>c{run free}

Here, the user creates a button that when clicked will make guish execute a system command (free in this case) (see run in SPECIAL COMMANDS).

 |b|<generator =>c{|b|<clone}

A button which is a factory of buttons (run this with -z option).

Here the evaluation of the code block is done when the click signal is triggered.

Scopes and closures

All variables (functions too, as blocks can be assigned to variables) have a specific scope:

 a = 1
 {b = 2}()
 puts "@{a}:@{b}"

Here the variable "a" is defined in the global scope, while "b" is defined in a temporarily block scope; hence just "a" is printed to stdout.

When accessing reading/defining a variable in a local scope, if the variable is already defined in the enclosing scope then that variable is picked to be read/modified:

 a = 1
 {
     a = 5
     puts@a
 }()
 puts@a

Here "a" is defined in the global scope, then modified from block scope and printed from there, and its value doesn't change.

If a variable is defined inside a block, then all embedded blocks that reference that variable will get its value at definition time (a closure):

 {
     a = 1
     return {
         puts @a
     }
 }()()

Quotes, blocks and functions

There are single and double quoting: anything embedded inside single quotes , is treated literally (no escaping takes place) and as a single token.

Variable interpolation is used inside double quotes "", external command substitution quotes `` and external window id substitution <( ).

Escaping ("\n\t\r\f\v\b") takes place only inside double quotes "".

 a = 'my string'; puts "this is:	 @{a}"

Anything embedded inside {} is treated as a code block and no variable substitution is done at definition time.

To "execute" a block, simply use parens (). If arguments are given, they can be referenced inside block by using @n, where "n" is a number which represents a specific argument by position (indexes start at 1). To refer to all arguments (at once) given to the block use @* operator (when in string interpolation, argument separator is a space).

 v = myvar
 a = {puts "here is @{v}"}
 a()

Here the variable "v" is not substituted when assigning the block to "a"; it's substituted later, when function "a" is called.

 {
     puts join("", "string length is: ", len(@1))
 }("home")

Here instead, the block is defined and executed immediately, using "home" as the first argument.

Being a block a piece of code, it can be used to define functions by simply being assigned to a variable:

 fn = {return add(@1, @2)}
 puts join("my func res:", fn(2, 4)) 

In addition, when defining a new function, it's possible to "overwrite" the builtin functions in the current scope.

When returning from a function, instead, it's possible to return multiple arguments (the remaining phrase) to the caller:

 fn = {return 1 2 3}
 puts join(fn())

Joining

By using the special ++ operator, it's possible to join tokens and blocks; it works simirarly to the join function, except that the second operand it's treated always as a token (even if it is a '{').

 puts a ++ b

Conditionals

Anything equal to 0, "0" or empty (like ''', ""', {}) is false, true otherwise. This is useful with if and else commands:

 if 1 { |b|<text } else { |b|<neverhere }

or

 if ge(@a,4) { |l|<4 }

Loops and iteration

Here an example of a while loop:

 a = 1
 after 4 {a = 0}
 while eq(@a, 1) {
     wait 1 puts 'true'
 }
 puts 'end'

And here another one using each function:

 each({puts @1}, 1, 2, 3, 4, 5}

And another one of a for loop:

 for x 1 2 3 4 { puts @x }

Tail recursion optimization (TCO)

Since 2.2.1 version, guish supports tail recursion optimization too, effectively turning a tail recursive function into a loop:

 upto = {
     if gt(@1, @2) {
         return
     }
     puts @1
     return upto(add(@1, 1), @2)
 }
 upto(1, 7)

To use TCO, the last phrase of a function must use return command directly (not inside another block like if-else).

External window id substitution

Everything inside <( ) is recognized as an external command (X11 GUI), forked and executed, and its window id is substituted (using _NET_WM_PID).

Note that this method will not work with programs that fork.

For example:

 a = <(xterm)

xterm program is spawn, and can be driven (almost) like a normal element.

External command substitution

Everything inside `` is recognized as an external command and executed. Then the command output (STDOUT) is substituted inside source code and interpreted after that.

For example:

 |b|<`echo clickme`

Slicing

Anything inside [] is trated as a slice expression. The usage is [<n>[,<x>]], when <n> is an index, and <x> is an optional end index (always inclusive); if the preceding argument is a regular token, then the expression will return its characters as specified by index(es), otherwise if it's a block, the expression will return its tokens:

 puts {1, 2, 3, 4, {a, b}, cat}[4][1]

The output of this example is 'b'.

If the index(es) given are out of range, an empty token is returned.

SPECIAL VARIABLES

SW
primary screen width, in pixels.
SH
primary screen height, in pixels.
X
pointer's x coord.
Y
pointer's y coord.
self
variable holding the window id when in signal code.
FILE
variable holding the path of current source file.
LINE
variable holding current line number at "that" point in source code.

ENVIRONMENT VARIABLES

GUISH_MAXWIDWAIT
the maximum number of seconds to wait when applying external window id substitution (defaults to 3 seconds)

ELEMENTS

Available elements are:

b
A button.
i
An input box.
l
A label.
p
A page (container of other elements; show and hide are applied to all subelements).
c
A checkbox.

SPECIAL COMMANDS

Special commands are not tied to elements, they are like statements.

=> <signal> <subcmd>
register a sub-command <subcmd> to run when <signal> triggers. For normal signals (eg. signals tied to elements), there must exist an implied subject.
global <var> = <val>
defines a variable using the same rules of variable definition, but defining that variable in the global scope; this usually can be used inside functions to define a global variable which doesn't exist already.
q
quit guish (exit status 0).
exit <status>
quit guish (exit status <status>).
run <cmd>
execute shell command <cmd>.
dump <args>
print <args> to stdout with a newline added.
puts <arg>
print <arg> to stdout with a newline added.
p <arg>
print <arg> to stdout.
e <arg>
print <arg> to stderr.
unset <namescheduled num>
unset variable or timed scheduled procedure registered with <num>, see every command.
source <file>
execute commands from file.
vars
display all variables on standard error.
ls
display all existing widgets on standard error.
del <wid>
delete a widget with id <wid>.
every <seconds> <block>
schedule <code> to run after <seconds> seconds are elapsed.
after <seconds> <block>
schedule <block> to run once after <seconds> seconds are elapsed.
wait <seconds>
stop command execution and wait <seconds> seconds before resuming; XEvent handling, schedules actions and signal execution are unaffected by this option.
if <condition> <block>
executes <block> if condition evaluates to true (see Conditionals).
unless <condition> <block>
executes <block> if condition evaluates to false (see Conditionals).
else <block>
executes <block> if last conditional command was successful (see Conditionals).
return <phrase>
when used inside a function, returns all its arguments (the remaining phrase) to the caller.
while <condition> <block>
executes <block> until <condition> evaluates to true (see Conditionals).
until <condition> <block>
executes <block> until <condition> evaluates to true (see Conditionals).
for <variable> <list of items> <code>
executes <code> for each item in list of items using a variable. Note that <code> must be a code block.
break
exit from current loop.
rel <element1> <element2> <alignment>
relates <element1> to <element2>, moving <element1> near <element2> using <alignment> (see alignment in STYLE AND ATTRIBUTES section, as <alignment> opts are similar) every time <element2> is moved. If "0" is specified as alignment, the relation is deleted.
pass [<args>]
do nothing, consuming remaining arguments.
send <keysequence>
send a keysequence to an element (must be enabled at compilation time).
ctrl <keysequence>
send control key sequence to an element (must be enabled at compilation time).

GENERIC COMMANDS

Generic commands are applicable to any element, regardless of its type (there are exceptions though).

G
element is undetectable in taskbar.
F
resize the element to fit the entire screen.
d
restore element's default window attributes.
!
bypass window manager.
!!
follow window manager as default.
n
center element in its parent.
-
hide element.
+
show element.
c
click element.
f
focus element.
t
make element stay at top.
b
make element stay at bottom.
x
hide element, or quit guish if quit-on-last-close is on and the element is the last closed one.
l
lower the element.
r
raise the element.
M
maximize the element.
D
disable the element.
E
enable the element.
o
fits element's size to its content.
w
resize an element in right-bottom directions to fit its parent, respecting limits of other elements.
nfill
resize an element in right-bottom directions to fit its parent.
rfill
resize an element in right direction to fit its parent, respecting limits of other elements.
nrfill
resize an element in right direction to fit its parent.
bfill
resize an element in bottom direction to fit its parent, respecting limits of other elements.
nbfill
resize an element in bottom direction to fit its parent.
L
clear element's data.
: <title>
set element title.
a <data>
attach custom <data> to a widget; to retrieve it see "BUILTIN FUNCTIONS" section.
s <text>
set element style (see STYLE AND ATTRIBUTES section).
z <w> <h>
resize element by width and height.
m <x> <y>
move element to coords <x> <y>.
A <element> <alignment>
moves implied element to <element> using <alignment> (see alignment in STYLE AND ATTRIBUTES section, as <alignment> opts are similar).
< <text>
set element text using <text>.
<+ <text>
add additional text to element text using <text>.
> <var>
define a variable named <var> using element text to set its value.
g
enable/disable (toggle) moving the parent of the element by click-and-drag it. Enabling this will automatically exclude x/y moving flags below.
X
enable/disable (toggle) moving an element inside its parent by click-and-drag on x axis Enabling this will automatically exclude the flag to click-and-drag and move parent.
Y
enable/disable (toggle) moving an element inside its parent by click-and-drag on y axis Enabling this will automatically exclude the flag to click-and-drag and move parent.

NORMAL COMMANDS

checkbox commands

C
check.
U
uncheck.

input commands

S
show input data as normal while typing.
H
hide input data while typing.
P
use password mode, displaying just asterisks.
W
toggles "go to the next line" when hitting return (triggers return signal anyway).

page commands

Q
make subelements equals (in size).
S <style>
style all subelements.
P
free all embedded elements.
<< <element>
embeds element (or an external client).
<<< <element>
embeds element (or an external client), fitting the page to its content.
>> <element>
free element, reparenting it to root window.
>>> <element>
free element, reparenting it to root window and fitting the page to its content.
v
set vertical layout readjusting all subwidgets.
h
set horizontal layout readjusting all subwidgets.
Z <e1> <e2>
swaps sub-elements position.
N
inverts the order of sub-elements.

SPECIAL SIGNALS

Special signals are independent from elements, and are tied to internal guish events.
q
triggered at program exit.
t
triggered when program receives a SIGINT or a SIGTERM.

GENERIC SIGNALS

Generic signals are common to all elements.
x
triggered when element is closed.
c
triggered when element is clicked.
lc
triggered when element is left-clicked.
rc
triggered when element is right-clicked.
mc
triggered when element is middle-clicked.
cc
triggered when element is double clicked.
lcc
triggered when element is double left-clicked.
rcc
triggered when element is double right-clicked.
mcc
triggered when element is double middle-clicked.
p
triggered when element is pressed.
lp
triggered when element is left-pressed.
rp
triggered when element is right-pressed.
mp
triggered when element is middle-pressed.
r
triggered when element is released.
lr
triggered when element is left-released.
rr
triggered when element is right-released.
mr
triggered when element is middle-released.
m
triggered when element is moved.
s
triggered when element scrolled down.
S
triggered when element scrolled up.
z
triggered when element is resized.
e
triggered when mouse pointer "enters" the element.
l
triggered when mouse pointer "leaves" the element.
f
triggered when focusing the element.
u
triggered when un-focusing the element.

NORMAL SIGNALS

Normal signals are per element.

checkbox signals

U
triggered when checkbox is unchecked.
C
triggered when checkbox is checked.

input signals

R
triggered when input has focus and "return" is hit.

REDUNDANT TOKENS

These tokens are ignored: ",", "->".

EVALUATION ORDER AND SUBSTITUTIONS

Every time a new phrase is evaluated, it goes through a series of special substitutions/evaluations before it's commands are interpreted.

The evaluation order is: hex substitution (at tokenizer level), evaluation of expressions (where code evaluation/execution, substitutions and functions are computed), evaluation of special commands and execution of generic/normal commands.

Moreover if after the execution phase (the last one) the phrase is not empty, the evaluation cycle will restart from evaluation of expressions phase, and it will continue until there are no more tokens in the phrase.

Every phrase is reduced to an empty phrase while evaluating:

 a = 234 {i1=|i|<'input1'+}(); {i2=|i|<'input2'+}() |b|<btn+

This example is composed by 2 phrases, and the code block in each phrase is executed before each assignment.

Hex substitution

Non quoted tokens are subject to hex substitution: if a "\x" plus 2 hexadecimal characters is found, it's substituted with corresponding ascii characters.

 puts \x68\x6F\x6D\x65

Here, the string "home" is printed.

Globbing

If a "*" is given, then all widgets wids are substituted.

 |b||b||b|+
 dump *

Variable substitution

With the = operator (actually, it's a special statement command), it's possible to assign a value to a variable, reusing it later by simply referencing it using @ operator when not inside quotes or by wrapping it inside @{} when in double quotes, shell command substitution quotes ``, or external window id substitution <( ).

There are two methods to define/create empty variables: by explicitely assing an empty string to a variable (ex. a = "") or by simply omit the value (ex. a =).

Each block has it's own scope, and variable resolution works by searching from the last scope to the first. Ex:

 a = 1
 puts(@a)
 {
     a=345
     b=6534
 }()
 puts@a
 puts"b:@{b}"

In the last example, a is set to 1 and printed, then it's changed to 345 from another scope, in which another variable (b) is set. After code block, just "a" is updated, and "b" doesn't exist anymore.

For example:

 gname = MY_GRIP_NAME
 |l|<@gname

or

 gname = MY_GRIP_NAME
 name = 'random name'
 puts "@{gname} is maybe @{name}"

Element substitution

Anything inside || is an element expression; a widget of a given element is created and its X11 window id substituted. Ex.

 |b|+

If an integer is given, instead of one of available element types, then the program tries to find an existing program having that integer as window id. Ex.

 |12341234|-

This creates a widget ("external") for the external program and hides it.

Shell command substitution

Anything inside `` is treated as a shell command, and it's output is substituted.

 d = `date`
 ols = `ls -l`

External window id substitution

Everything inside <( ) is recognized as an external command (X11 GUI), forked and executed, and its window id is substituted (using _NET_WM_PID).

For example:

 a = <(xterm)

xterm program is spawn, and can be driven (almost) like a normal element.

BUILTIN FUNCTIONS

Widget's related functions

First argument <eid> must be an element id.

t(<eid>)
widget's type.
w(<eid>)
widget's width.
h(<eid>)
widget's height.
x(<eid>)
widget's x coord.
y(<eid>)
widget's y coord.
b(<eid>)
widget's border width.
g(<eid>)
widget's margin width.
d(<eid>)
widget's text data.
a(<eid>)
widget's custom/attached data.
T(<eid>)
widget's title.
c(<eid>)
widget's checked/unchecked status (only for checkbox).
n(<eid>)
widget's number of subwidgets (only for page).
s(<eid>)
widget's subwidgets ids (one token each, only for page).
pid(<eid>)
process ID associated with the widget.
v(<eid>)
widget is visible.
e(<eid>)
widget is enabled (freezed/unfreezed).
f(<eid>)
widget is focused.
exists(<eid>)
widget exists.

Generic functions

Symbol "..." means a variable number of arguments.

read([<file>])
reads and returns a line (excluding newline) from standard input; if an existing [file] is given, reads and returns all its content. Beware that this function blocks the GUI events, and returns nothing when reading from stdin and source is non-blocking.
write(<text>, <file>)
writes text into file and returns the number of characters written. Creates the file if it doesn't exist yet.
append(<text>, <file>)
append text to the end of file and returns the number of characters written. Creates the file if it doesn't exist yet.
call(<name>, ...)
gets a variable name and a variable number of arguments, then calls the function whose name is "name" with those arguments and returns the result (if any).
each(<function>, ...)
executes <function> for each additional argument given passing it as the first argument to the block. If return values are present, they will be accumulated and then returned.
env(<var>)
returns the value of the environment variable "var"
rev([<block>], ...)
if a block is given as first argument, its element will be returned in reverse, otherwise rev will return all its arguments in reverse. This function is somewhat special, as when there are no arguments to get, it'll return nothing (statement behaviour).
let([<var>, <val>], ...)
sets variables, works exactly like assignment with special operator =, but in expressions. This function is somewhat special, it'll return nothing (statement behaviour).
if(<cond>, [<v1>, [<v2>]])
if <cond> is true and <v1> is given, returns <v1>, else if <cond> is false and <v2> is given, returns <v2>.
flat(...)
returns all given arguments; if a block is found, then it is flatted.
block(...)
returns a code block, embedding the given arguments into {}.
some(...)
returns given arguments. If nothing is given, returns an empty token.
puts(...)
prints given arguments to stdout. This function is somewhat special, it'll return nothing (statement behaviour).
push(...)
pushes given arguments to current function arguments (when inside a function). This function is somewhat special, it'll return nothing (statement behaviour).
pushb(...)
pushes given arguments to current function arguments from the beginning (when inside a function). This function is somewhat special, it'll return nothing (statement behaviour).
pop()
pops the last argument from function arguments (when inside a function). This function is somewhat special, as if there are no arguments to pop, it'll return nothing (statement behaviour).
popb()
pops the first argument from function arguments (when inside a function). This function is somewhat special, as if there are no arguments to pop.
slice(<si>, <ei>, ...)
returns arguments starting at "si" and ending at "ei" (inclusive). This function is somewhat special, as when there is nothing to get, it'll return nothing (statement behaviour).
times(<n>, <arg>)
returns a sequence of tokens made by <n> times <arg>. This function is somewhat special, as when there are 0 tokens to replicate, it'll return nothing (statement behaviour).
get(<name>)
returns the value of the variable with name <name>, or an empty token if the variable doesn't exist.
at(<n>, ...)
returns the "nth" argument given (by index). This function is somewhat special, as when there is nothing to get, it'll return nothing (statement behaviour).
true(<arg>)
returns 1 if <arg> is true, 0 otherwise.
false(<arg>)
returns 0 if <arg> is true, 1 otherwise.
in(<n>, <heap>)
returns 1 if <n> is found in <heap>, 0 otherwise; the arguments can be of any type (single tokens and blocks).
join(...)
joins blocks and/or tokens by applying the following rules to all arguments given, and accumulates the result as the first operand. If the operands are blocks, then a single new block is created by joining them; if the operands are tokens, then a single new token is created by joining them, and its type will be that of the "second" token; if the operands are mixed (eg. a block and a token), then the token will be embedded inside the block.
range(<start>, <end>)
returns integers starting at <start> and ending at <end> (inclusive) as multiple tokens.
isdef(<token>)
returns 1 if <token> is a variable, 0 otherwise.
isvar(<token>)
returns 1 if <token> is a (type) variable, 0 otherwise.
isfunc(<token>)
returns 1 if <token> refers to a function, 0 otherwise.
isblock(...)
returns 1 if just one argument is given and is a block, 0 otherwise.
isint(...)
returns 1 if just one argument is given and is an integer, 0 otherwise.
len(<token>)
returns the length of the token.
split(<token>, <sep>)
splits "token" using separator "sep" and returns resulting tokens having their type equal to that of "token".
csplit(<token>, <sep>)
splits "token" using separator "sep" and returns resulting tokens as normal commands.
seq(<t1>, <t2>, ...)
returns 1 if all arguments are equal (string comparison), 0 otherwise.
count(...)
returns the number of given arguments.
any(...)
returns the first true argument; if there are no true arguments, returns the last one which is false. This function is special, as the evaluation will be interrupted as soon as there is at least 1 true argument.
all(...)
returns the last true argument if all arguments are true, otherwise returns the first false argument. This function is special, as the evaluation will be interrupted as soon as there is at least 1 false argument.
add(...)
perform addition.
sub(...)
perform subtraction.
mul(...)
perform multiplication
div(...)
perform division.
mod(...)
perform modulus.
xor(<n1>, <n2>, ...)
perform bitwise XOR.
and(<n1>, <n2>, ...)
perform bitwise AND.
or(<n1>, <n2>, ...)
perform bitwise OR.
lsh(<n1>, <n2>, ...)
perform bitwise left shift.
rsh(<n1>, <n2>, ...)
perform bitwise right shift.
not(<n>)
perform negation
eq(<n1>, <n2>, ...)
equal-to
ne(<n1>, <n2>, ...)
not-equal-to
lt(<n1>, <n2>, ...)
less-than
gt(<n1>, <n2>, ...)
greater-than
le(<n1>, <n2>, ...)
less-equal-than
ge(<n1>, <n2>, ...)
greater-equal-than
abs(<n>)
perform absolute value
neg(<n>)
unary minus.

STYLE AND ATTRIBUTES

Each element has some properties/attributes which can be set by using style command. This command takes a string that has a format like CSS:

 |l| s 'bg: blue; fg: white'

Here, we create a label with a blue background and white foreground.

Each field must be separated by newlines, ; or |. Colors can be specified by using a common shortname, such as "yellow", or by using RGB value, such as "#ff32ae".

background | bg: <color>
set background color
color | foreground | fg: <color>
set foreground color
pressed-background | pbg: <color>
background color when element is pressed
pressed-color | pfg: <color>
foreground color when element is pressed
hovered-background | hbg: <color>
background color when element is hovered
hovered-color | hfg: <color>
foreground color when element is hovered
border-color | bc: <color>
set border color
background-image | i: <path>
set background image by specifying image path; if the string "null" is given, current image is removed. (This attribute requires building guish with Imlib2 support.)
width | w: <value in pixels>
set width
height | h: <value in pixels>
set height
border | b: <value in pixels>
set border width
margin | g: <value in pixels>
set margin width
mode | m: <expanding mode>
set expanding mode type (See Expanding mode)
align | a: <alignment>
set alignment type (See Alignment)
f | font: <font name>
set font type using a X11 font name

Expanding mode

fixed | f
width and height are fixed (default for all elements)
wfixed | w
width is fixed, height can change
hfixed | h
height is fixed, width can change
relaxed | r
width and height can change

Alignment

Any element that's not a page has a particular text alignment that can be changed. If an alignment is specified for a page element instead, (whose defaults alignments are top-center for horizontal layout, and middle-left for vertical one), then its sub-elements will be aligned accordingly, depending from page layout type too.

l | left | middle-left
show text at middle left
r | right | middle-right
show text at middle right
c | center | middle-center
show text at middle center
tl | top-left
show text at top left
tr | top-right
show text at top right
t | top-center
show text at top center
bl | bottom-left
show text at bottom left
br | bottom-right
show text at bottom right
b | bottom-center
show text at bottom center

AUTHOR

Francesco Palumbo <phranz@subfc.net>

THANKS

La vera Napoli, Carme, Pico, Titina, Molly, Leo, i miei amati nonni, mio padre, mia madre, e tutti coloro su cui ho potuto e posso contare. Grazie mille.

LICENSE

GPL3

Pages in category "Guish"

The following 3 pages are in this category, out of 3 total.