Category:Guish: Difference between revisions
no edit summary
No edit summary |
No edit summary |
||
| (12 intermediate revisions by the same user not shown) | |||
Line 13:
'''guish''' ['''-c''' <code>]['''-s''']['''-q''']['''-k''']['''-t''']['''-f''']['''-v''']['''-b''']['''-h'''][<file>][<arguments>]
= DESCRIPTION =
Line 41:
; '''-v'''
: show version.
; '''-b'''
: show build (compiled in) options.
; '''-h'''
: guess.
Line 81 ⟶ 83:
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 '''-
== Subject and implied subject ==
Line 120 ⟶ 122:
<pre> |b|<generator =>c{|b|<clone}</pre>
A button which is a factory of buttons (run this with '''-
Here the evaluation of the code block is done when the click signal is triggered.
Line 159 ⟶ 161:
There are single and double quoting: anything embedded inside single quotes '', is treated literally (no escaping takes place) and as a single token.
Variable
Escaping ("\n\t\r\f\v\b") takes place only inside double quotes "".
<pre> a = 'my string'; puts "this is: @{a}"
puts "sum of 1 + 5 is: @(add(1, 5))"</pre>
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, with
<pre> v = myvar
Line 174 ⟶ 177:
<pre> {
puts join(
}("home")</pre>
Here instead, the block is defined and executed immediately, using "home" as the first argument.
Line 188 ⟶ 191:
<pre> fn = {return 1 2 3}
puts join(fn())</pre>
== Conditionals ==
Line 213 ⟶ 209:
<pre> a = 1
after 4 {a = 0}
while {eq(@a, 1)} {
wait 1 puts 'true'
}
Line 219 ⟶ 215:
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 in 1 2 3 4: { puts @x }</pre>
== Tail recursion optimization (TCO) ==
Line 265 ⟶ 261:
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:
<pre> puts {1, 2, 3, 4, {a, b}, cat}[4][1]</pre>
Line 286 ⟶ 282:
; '''self'''
: variable holding the window id when in signal code.
; '''args'''
: refers to the block in which there are positional arguments and function arguments (alternative syntax).
; '''FILE'''
: variable holding the path of current source file.
Line 314 ⟶ 312:
; '''c'''
: A checkbox.
; '''t'''
: A label with a totally transparent background (requires a compositor).
= SPECIAL COMMANDS =
Line 323:
; '''=> <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.
; '''
: unregister a sub-command <subcmd> previously registered on signal <signal>.
; '''q'''
: quit guish (exit status 0).
; '''exit <status>'''
: quit guish (exit status <status>).
; '''cd <path>'''
: change current working directory using <path>.
; '''run <cmd>'''
: execute shell command <cmd>.
; '''
:
; '''
:
; '''
:
; '''
: unsets a variable (<name>) or timed scheduled procedure registered with <num>, see '''every''' command. If, instead of <name|num>, an element id <wid> is given and a name attribute <attr> is given, deletes that element attribute.
; '''source <file>'''
: execute commands from file.
; '''vars [<wid>]'''
: shows all variables present in the current scope or, if <wid> element id is given, shows all element attributes (uses stderr).
; '''ls'''
: display all existing widgets
; '''del <wid>'''
: delete a widget with id <wid>.
Line 354:
: schedule <block> to run once after <seconds> seconds are elapsed.
; '''wait <seconds>'''
: stop command execution and wait <seconds> seconds before resuming
; '''if <condition> <block>'''
: executes <block> if condition evaluates to true (see Conditionals).
Line 367:
; '''until <condition> <block>'''
: executes <block> until <condition> evaluates to true (see Conditionals).
; '''for [<
: executes the block <
; '''break'''
: exit from current loop.
Line 375:
; '''pass [<args>]'''
: do nothing, consuming remaining arguments.
; '''send <wid> <keysequence>'''
: send a keysequence to an element whose id si <wid> (must be enabled at compilation time).
; '''ctrl <wid> <keysequence>'''
: send control key sequence to an element whose id si <wid> (must be enabled at compilation time).
= GENERIC COMMANDS =
Line 440:
; ''': <title>'''
: set element title.
; '''s <text>'''
: set element style (see STYLE AND ATTRIBUTES section).
Line 448 ⟶ 446:
; '''m <x> <y>'''
: move element to coords <x> <y>.
; '''/ [<l|L|a|A|p|x|n> [<...>]]'''
: draws/fills lines, points and arcs depending on operation (See Drawing operations subsection). Origin coordinates correspond to the bottom-left corner as default Cartesian axes (instead of upper-left one used for windows/elements). If no operation is given, then all drawings are discarded from the implied element.
; '''A <element> <alignment>'''
: moves implied element to <element> using <alignment> (see alignment in STYLE AND ATTRIBUTES section, as <alignment> opts are similar).
Line 462:
; '''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.
== Drawing operations ==
; '''l [<color> <x1> <y1> <x2> <y2> [<...>]]'''
: draws lines between given points using color <color> (beware this command consumes all the phrase). If no arguments are given, then all element lines are discarded.
; '''L [<color> <x1> <y1> <x2> <y2> [<...>]]'''
: fills the polygon described by given points using color <color> (beware this command consumes all the phrase). If no arguments are given, then all filled polygons are discarded.
; '''a [<color> <x> <y> <w> <h> <alpha> <beta> [<...>]]'''
: draws an arc using color <color> and whose "center" is at <x> <y>, major and minor axes are respectively <w> and <h>, start and stop angles are <alpha> and <beta> (consumes all the phrase). If no arguments are given, then all element arcs are discarded.
; '''A [<color> <x> <y> <w> <h> <alpha> <beta> [<...>]]'''
: fills an arc using color <color> and whose "center" is at <x> <y>, major and minor axes are respectively <w> and <h>, start and stop angles are <alpha> and <beta> (consumes all the phrase). If no arguments are given, then all element arcs are discarded.
; '''p [<color> [<...>]]'''
: draws given points using color <color> (beware this command consumes all the phrase). If no arguments are given, then all points are discarded.
; '''x [<color> [<...>]]'''
: draws given pixels using color <color> (beware this command consumes all the phrase). If no arguments are given, then all pixels are discarded.
; '''n [<color> <name> <x> <y>]'''
: draws given point using color <color> and putting the text <name> at that point. If no arguments are given, then all points are discarded.
= NORMAL COMMANDS =
Line 615 ⟶ 634:
Every phrase is reduced to an empty phrase while evaluating:
<pre> a
This example is composed by 2 phrases, and the code block in each phrase is executed before each assignment.
Line 634 ⟶ 653:
<pre> |b||b||b|+
== Variable substitution ==
With the '''=''' operator (actually, it's a special statement command), it's possible to assign
<pre> b = 123; puts @a</pre>
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 =).
In addition, if there is more than one value to assign, a block is automatically created (embedding those values) and assigned to that variable:
<pre> a = 1 # this simply assigns '1' to the variable 'a'
b = 1, 2, 3, 4 # this instead assigns the block '{1, 2, 3, 4}' to the variable 'a'
c = {1, 2, 3, 4} # same but explicit</pre>
Each block has it's own scope, and variable resolution works by searching from the last scope to the first. Ex:
Line 664 ⟶ 689:
name = 'random name'
puts "@{gname} is maybe @{name}"</pre>
== Element
Anything inside '''||''' is an element expression; a widget of a given element is created and its X11 window id substituted. The synopsis is: |<element>[{<width>, <height>}]| Ex.
<pre> |b|+</pre>
Line 695 ⟶ 720:
xterm program is spawn, and can be driven (almost) like a normal element.
= OPERATORS =
== Binary ==
; '''<s> .. <e>'''
: returns integers starting at <s> and ending at <e> (inclusive) as multiple tokens.
; '''<var> = [<val>, [<val1>, ...]]'''
: defines a variable (consumes all the phrase). If no value is given, an empty token is assigned to the variable. If a single value is given, that value is assigned to the variable. If multiple values are given, then all these values are wrapped inside a block, and this block is assigned to the variable.
; '''<attr> .= [<val>, [<val1>, ...]]'''
: defines an element using the implied subject attribute (consumes all the phrase). If no value is given, an empty token is assigned to the variable. If a single value is given, that value is assigned to the variable. If multiple values are given, then all these values are wrapped inside a block, and this block is assigned to the variable.
== Unary ==
; '''@<varname|num>'''
: dereferences a variable name (or positional argument).
; '''@*'''
: returns all function parameters as tokens (usable with command line parameters too).
; '''[<eid>].<attr>'''
: dereferences an element attribute; if <eid> is given, uses that element, otherwise uses implied subject.
= ELEMENT ATTRIBUTES =
Every element can have some default readonly attributes and a variable number of custom attributes (which can be set by using assignment only, not by using '''let''' function). To set an attribute, use the "'''.='''" operator; to get it instead use the "'''.'''" operator.
<pre> b = |b|; myattr .= 'here'; puts(@b.myattr)</pre>
In the last example, a custom attribute, "myattr" is created and used.
The following are default attributes (readonly):
; '''t'''
: widget's type.
; '''w
: widget's width.
; '''h
: widget's height.
; '''x
: widget's x coord.
; '''y
: widget's y coord.
; '''b
: widget's border width.
; '''g
: widget's margin width.
; '''d
: widget's text data.
; '''
: widget's title.
; '''c
: widget's checked/unchecked status (only for checkbox).
; '''n
: widget's number of subwidgets (only for page).
; '''s
: widget's subwidgets ids (one token each, only for page).
; '''pid
: process ID associated with the widget.
; '''v
: widget is visible.
; '''e
: widget is enabled (freezed/unfreezed).
; '''f
: widget is focused.
Line 748 ⟶ 796:
Symbol "'''...'''" means a variable number of arguments.
; '''exists(<eid>)'''
: returns 1 if a widget with id <eid> exists, 0 otherwise.
; '''read([<file>])'''
: reads and returns a line (excluding newline) from standard input; if an existing
; '''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.
; '''
:
; '''builtin(<func>, ...)'''
: gets the name of a builtin function and a variable number of arguments, then calls the builtin function with those arguments and returns the result (if any). It's useful when overriding builtin functions.
; '''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".
; '''cwd()'''
: returns the value of the current working directory.
; '''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).
Line 766 ⟶ 820:
; '''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>.
; '''unless(<cond>, [<v1>, [<v2>]])'''
: if <cond> is false and <v1> is given, returns <v1>, else if <cond> is true and <v2> is given, returns <v2>.
; '''and(...)'''
: returns the first true argument; if there are no true arguments, returns the last one which is false. The function evaluates any block given.
; '''or(...)'''
: returns the last true argument if all arguments are true, otherwise returns the first false argument. The function evaluates any block given.
; '''flat(...)'''
: returns all given arguments; if a block is found, then it is flatted.
Line 775 ⟶ 835:
: prints given arguments to stdout. This function is somewhat special, it'll return nothing (statement behaviour).
; '''push(...)'''
: pushes given arguments to current function arguments (
; '''pushb(...)'''
: pushes given arguments to current function arguments from the beginning (
; '''pop()'''
: pops the last argument from function arguments (
; '''popb()'''
: pops the first argument from function arguments (
; '''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
; '''true(<arg>)'''
: returns 1 if <arg> is true, 0 otherwise.
Line 798 ⟶ 854:
; '''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.
; '''isdef(<token>)'''
: returns 1 if <token> is a variable, 0 otherwise.
Line 810 ⟶ 864:
; '''isint(...)'''
: returns 1 if just one argument is given and is an integer, 0 otherwise.
; '''len(<
: if a block is given, returns the
; '''split(<token>, <sep>)'''
: splits "token" using separator "sep" and returns resulting tokens having their type equal to that of "token".
Line 818 ⟶ 872:
; '''seq(<t1>, <t2>, ...)'''
: returns 1 if all arguments are equal (string comparison), 0 otherwise.
; '''add(...)'''
: perform addition.
Line 834 ⟶ 882:
; '''mod(...)'''
: perform modulus.
; '''rand()'''
: returns a random positive integer.
; '''sqrt(<n>)'''
: returns the square root of <n>.
; '''cbrt(<n>)'''
: returns the cube root of <n>.
; '''pow(<n>, <e>)'''
: returns the power of <n> raised to <e>.
; '''log(<n>)'''
: returns the base 10 logarithm of <n>.
; '''ln(<n>)'''
: returns the natural logarithm of <n>.
; '''sin(<n>)'''
: returns the sine of <n> (degrees).
; '''cos(<n>)'''
: returns the cosine of <n> (degrees).
; '''tan(<n>)'''
: returns the tangent of <n> (degrees).
; '''hex(<n>)'''
: returns <n> in its hexadecimal representation.
; '''int(<n>)'''
: returns integral part of given number <n>; rounds to nearest integer.
; '''xor(<n1>, <n2>, ...)'''
: perform bitwise XOR.
; '''
: perform bitwise AND.
; '''
: perform bitwise OR.
; '''lsh(<n1>, <n2>, ...)'''
Line 874 ⟶ 944:
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|/<path to image>>'''
: set background color or a background image by specifying image path; if the string "null" is given as <path to image>, current image is removed. (Background image loading requires building guish with Imlib2 support.)
; '''color | foreground | fg: <color>'''
: set foreground color
Line 888 ⟶ 958:
; '''border-color | bc: <color>'''
: set border color
; '''width | w: <value in pixels>'''
: set width
Line 896 ⟶ 964:
; '''border | b: <value in pixels>'''
: set border width
; '''line | l: <value in pixels>'''
: set line width (use with "/" command)
; '''margin | g: <value in pixels>'''
: set margin width
| |||