deskshell(XC)

deskshell -- syntax and control constructs of the Deskshell command language

Description

Deskshell is a command language that allows you to manipulate most aspects of the Desktop. The Deskshell script language is used to specify the actions to be performed in a trigger_action, drop_in_action, initial_actions, final_actions, or menu_item rule or within an object script. For more information on rules, rule files, and objects, see the Graphical Environment Guide.

Deskshell commands and scripts can define actions to be taken when:

an icon is triggered
an icon is dragged and dropped on a directory or the desktop window
a directory or a desktop is opened
a directory or a desktop is closed
a menu item is chosen
an object is triggered in some other way

Deskshell offers a flexible range of control structures and a wide selection of commands. Deskshell provides the same basic functionality as the UNIX^® Bourne shell language.

Although regular UNIX commands and shell scripts can be used instead of Deskshell commands, Deskshell is recommended for the following reasons:

Deskshell commands execute faster than regular shell commands because no extra processes need to be opened (Deskshell operates within the Desktop processes).
Deskshell commands are specifically designed for the Desktop and therefore necessary for defining Desktop-specific actions.
Deskshell understands regular UNIX shell commands. Consequently, these commands can be included in Deskshell scripts if their functionality is necessary.

For information on Deskshell commands, see the deskcommands(XC) manual page.

Deskshell syntax

Deskshell syntax is very similar to Bourne shell language. Deskshell is a command interpreter, not a macro interpreter. This distinction, along with Deskshell's simpler syntax, eliminates some of the more awkward elements of Bourne shell syntax.

For example, Deskshell avoids the four different types of quoting and the need for exponentially growing numbers of backslashes that are sometimes necessary in Bourne shell language. The discussion on Deskshell syntax describes how to use strings, variables, and operators in Deskshell.

Deskshell strings

An unquoted string is interpreted to be a sequence of characters. The following characters have global meanings in Deskshell and are therefore restricted.

An unquoted string cannot contain or begin with the following characters:

: space, tab, or newline
': quote
( ): parentheses
{ }: braces
<: less than
>: greater than
;: semicolon
|: bar
&: ampersand
$: dollarsign
`: backquote
^: circumflex

An unquoted string cannot begin with the following characters:

#: hashmark
=: equals

The following characters are reserved for later wildcard processing:

: asterisk
[: open bracket
]: close bracket
?: question mark

Quoting in Deskshell

Unlike Bourne shell language, which includes four different kinds of quoting, Deskshell achieves the same functionality using only one kind of quoting: single quotes. Text within single quotes is uninterpreted by Deskshell. Quoting is only necessary to allow the special Deskshell characters to be treated literally.

After a piece of text has been interpreted by Deskshell, it is never interpreted again. For example, the values of variables are never interpreted and so can safely hold places.

NOTE: To include a single quote in quoted text, the single quote should be repeated.

   echo 'Can''t delete file.'

Values in Deskshell

All values are represented in Deskshell as strings, which are converted into numbers or Boolean values when required in specific contexts. Because all Deskshell variables are strings, Deskshell does not require variable ``typing''.

When strings are converted to numbers, the first non-digit is taken as the end of the number and remaining characters are ignored. Strings starting with a minus sign ``-'' have an undefined value.

When numbers or strings are converted to Boolean values, zero is taken as true and non-zero values are false. A list of numbers or strings is true if every element is zero and false if any element is non-zero.

Numbers are converted to strings in conventional decimal representation.

The preceding principles are illustrated by the following examples:

String Number Boolean

val 0 true

12X24 12 false

(val 2 3) (0 2 3) false

String	Number	Boolean
val	0	true
12X24	12	false
(val 2 3)	(0 2 3)	false

Deskshell variables

Each Deskshell variable can have a list of strings as its value (Bourne shell supports only one string per variable).

A list is represented by enclosing a sequence of strings in parentheses, for example:

(mon tues wed thur fri sat sun)

is a list of seven strings.

NOTE: ( ) is an empty list with no elements.

Environment variables

When Deskshell starts, the value of each environment variables is copied into a Deskshell variable of the same name. For example, the $PATH environment variable is copied into the Deskshell path variable. The path variable is a list of strings with a space-separated string for each path element. All other variables are set to contain no strings.

Special variables

The following special variables are provided in Deskshell and therefore reserved:

Variable Value

static_arg the static object in canonical (unambiguous) form

dynamic_args a list of the dynamic objects in canonical form

the elements of dynamic_args

s_desktop, d_desktop the name of the open desktops that the static and dynamic arguments are on, if any

s_position, d_position the position of the static or dynamic argument, or V if there is more than one argument

s_obj_type, d_obj_types the object types of the static and dynamic arguments, respectively

trigger the trigger name

desktop_name the name of the desktop

For a full description of these variables, see ``Deskshell variable descriptions''.

Variable	Value
static_arg	the static object in canonical (unambiguous) form
dynamic_args	a list of the dynamic objects in canonical form
	the elements of dynamic_args
s_desktop, d_desktop	the name of the open desktops that the static and dynamic arguments are on, if any
s_position, d_position	the position of the static or dynamic argument, or V if there is more than one argument
s_obj_type, d_obj_types	the object types of the static and dynamic arguments, respectively
trigger	the trigger name
desktop_name	the name of the desktop

Variable names

Variable names can consist of any sequence of letters, digits, and underscores; but they cannot start with a digit. You should not define variables that are the same as environment variables or one of the special Deskshell variables.

Variables are assigned with the equals (=) operator. For example,

days=(mon tues wed thur fri sat sun)

sets days to the list of seven strings.

Variable substitutions

The value of a variable can be substituted into a Deskshell script with:

$name

and the number of strings in a variable with:

$#name.

A subset of the value can be generated by placing appropriate subscripts in parentheses after the name. For example, the assignment:

days=(mon tues wed thur fri sat sun)

and the command:

echo $#days

will produce ``7'', while the command:

echo $days(3 1 3)

will produce:

``wed mon wed''

as will:

echo $days(3 0 1 8 3)

Function arguments

The special name

holds the list of arguments to the current function. For convenience, the forms $1, $2 ..., can be used as abbreviations for $

(1), the first argument; $

(2), the second argument, ...

Deskshell operators and script delimiters

The following table lists the operators and script delimiters provided in Deskshell:

Operator/Delimiter Description

= assignment

<, >, and >> redirection

<< here-document

`(backquote) substitution

^(circumflex) catenation

| pipeline

%//, # comment

&&, ||, &, and ; sequencing

These operators and delimiters are explained in more detail in the following sections. For a full description of each, see ``Deskshell operator and script delimiter descriptions''.

Operator/Delimiter	Description
=	assignment
<, >, and >>	redirection
<<	here-document
`(backquote)	substitution
^(circumflex)	catenation
\|	pipeline
%//, #	comment
&&, \|\|, &, and ;	sequencing

Assignments =

The assignment operator (=) assigns a list value to a variable. For example,

foo=(1 1 2 3 5)

assigns the list (1 1 2 3 5) to the variable foo.

Redirections <, >, and >>

A redirection causes a file descriptor to be redirected to a different file. The following options are available:

<: The file is opened on descriptor 0 for reading only; it must already exist.
>: The file is opened on descriptor 1 for writing and is truncated; it is created if necessary and will be overwritten if it exists.
>>: The file is opened on descriptor 1 for append only; it is created if necessary and will not be overwritten if it exists.

The following variants are available for each redirection; in each case < can be replaced by > or >>.

Variant Description

<filename Read from filename

<[number] filename Read from filename on descriptor number

<[new = number] Make new a duplicate of number

<[number =] Close descriptor number

Variant	Description
<filename	Read from filename
<[number] filename	Read from filename on descriptor number
<[new = number]	Make new a duplicate of number
<[number =]	Close descriptor number

Here-documents <<

The expression: <<name or <<[number] name causes text to be read from the script until name is found on a line of its own; the text is written to a temporary file, and then rewound and opened for reading on the specified descriptor number.

Substitutions `

Many Deskshell and UNIX commands perform an action and print a result. You can trap the output of such a command, and use it in a Deskshell script with the backquote ```'' operator.

For example,

size= `{ls -s $1}

assigns the string representing the size and name of the file in the variable $1 to the variable size.

NOTE: The use of the curly braces causes another process to be run.

Certain Deskshell commands generate text output. These may be used directly, without requiring a separate process. For example,

var=`(basename $list)

which sets var to a list of the basenames of the files in $list without requiring another process to be run.

Command substitution can be nested to any depth.

NOTE: No final backquote (`) is needed to end the substitution.

Catenations ^

Two words or lists can be catenated or joined together using the circumflex (^) character. Lists can only be catenated if they both contain the same number of elements, or if one of them only contains one element or is empty, as illustrated in the following examples:

a b a^b

w x wx

w (x y z) (wx wy wz)

(w x y) (a b c) (wa xb yc)

(w x y) ( ) (w x y)

(w x y) (a b) illegal

Several catenations can be included in one expression, as in:

s.^(in proc out)^.main.^(c h s)

a	b	a^b
w	x	wx
w	(x y z)	(wx wy wz)
(w x y)	(a b c)	(wa xb yc)
(w x y)	( )	(w x y)
(w x y)	(a b)	illegal

which evaluates to:

(s.in.main.c s.proc.main.h s.out.main.s)

Deskshell allows circumflexes to be omitted in a few common cases. For example, the strict form

$file^.c

can be written as

$file.c

instead.

Pipelines |

A pipeline consists either of a single command or several commands separated by pipe descriptors. A pipe descriptor consists of one of the following character sequences:

|
|[number1]
|[number1 = number2]

If number2 is omitted, it is equivalent to specifying zero. If both number1 and number2 and brackets are omitted, it is equivalent to specifying |[1=0]. White space can safely be inserted around the descriptor.

If there is only one command, it is executed directly by Deskshell. If there is more than one, then one child thread is created for each command. These are connected by pipes, one per pipe descriptor; none of the pipelines is executed by the original thread. number1 is the file descriptor to be connected to the writing end of the pipeline, and number2 is to be connected to the reading end of the pipe.

When a pipeline is executed, Deskshell waits for all the children to terminate. The individual statuses are converted to strings, and these are all stored in the status variable, in the same order as the commands in the pipeline. For example, the pipeline:

true | false

generates the status (0 1).

Comments %//, #

The ``%//'' delimiter defines comments in rules clauses and ``#'' defines comments in Deskshell scripts.

If a comment character occurs at what would be the start of an unquoted string, then the comment character, and all characters up to (but excluding) the next newline, are ignored. A comment character within an unquoted string is treated like any other character.

Scripts and sequences &&, ||, & , and ;

A script is made up of one or more sequences, separated by the delimiters ampersand (&) and semi-colon (;). A sequence is made up of one or more pipelines, separated by the delimiters double ampersand (&&) and double bar (||). Each of these delimiters can be surrounded by white space.

A sequence is executed by conditionally executing each pipeline in turn. The first pipeline in the sequence is always executed. Every other pipeline is executed if the preceding delimiter is ``&&'' and the status is true, or if the preceding delimiter is ``||'' and the status is false. A pipeline can be executed even if the previous one is not.

The status of a sequence is that of the last pipeline executed.

A script is executed by each of its constituent sequences. If the command sequence is terminated by ``&'', then it is executed in a child thread with fd 0 set to /dev/null, and its returned status is ignored. In the parent thread, the name of the child thread is placed in the variable last_background_action; the parent does not wait for the child to terminate. If the sequence is terminated by a semicolon, it is executed in this thread.

Deskshell control constructs

Deskshell offers most of the control flow structures and commands provided by the Bourne shell. Deskshell provides the following control constructs:

case: executes a script depending on the value of the variable
exit: terminates a thread
for: executes a script for each value of a variable in a specified list
function: defines a function
if: executes a script if a condition is true
return: returns from a function
until: executes a script until a condition is true
while: executes a script while a condition is true

For a more detailed description of each construct, see ``Deskshell script control construct descriptions''.

Deskshell function definitions

The command function assigns a function name to a script. The function command has the following syntax:

function name {script}

It assigns name to the script.

This assignment can be canceled with:

function name;

The script is not evaluated at this point, although it will be parsed and any syntax errors detected.

Deskshell status variable

When a Deskshell command is executed, it generates a numerical status between 0 and 1023.

When a command is executed and generates a status, that status is converted to a string and stored in the variable status. When a pipeline is executed, the individual statuses are collected, and the strings all stored in the variable status, in the same order as the commands in the pipeline.

For more information on the status variable, see ``status''. For information on the returned statuses for specific commands, see the deskcommands(XC) manual page.

NOTE: Certain built-in Deskshell commands and the function command do not return a status.

Deskshell variable descriptions

The following sections provide detailed descriptions of the Deskshell variables:

* (variable)

The list of arguments to a function or action.

Description

The variable * is set in the following situations:

Situation Result

within a function, or script executed by source the list of arguments to the function call, or source command

within a thread created by an actions_of or menu_actions_of command the dynamic arguments; identical to dynamic_args

for the duration of the script executed by a do_actions_of or do_menu_actions_of command the dynamic arguments; identical to dynamic_args

The variable * is used implicitly in a for construct.

Situation	Result
within a function, or script executed by source	the list of arguments to the function call, or source command
within a thread created by an actions_of or menu_actions_of command	the dynamic arguments; identical to dynamic_args
for the duration of the script executed by a do_actions_of or do_menu_actions_of command	the dynamic arguments; identical to dynamic_args

   for i in *

is equivalent to:

   for i

d_desktop

The name of the open desktop containing the dropped icon.

Description

The variable is set for threads run as a result of trigger actions and menu actions to give the desktop that the first dynamic argument, $dynamic_args(1), resides in.

Example

The following example defines a Putback icon which puts icons dropped from a desktop back onto it:

   icon_rules
   {
      Putback /F
      {
        picture=putback.px;
   
        trigger_action: d*
        {
          put_back $dynamic_args -d $d_desktop
        }
      }
   }

d_position

The nominal position of the first dynamic object.

Description

This variable is set in threads run as the result of a trigger action to give the position in the window of the first dynamic argument. See desktop_layout for details of how the position is specified.

Example

The following rule displays the value of d_position when an icon is dropped onto MyIcon:

   icon_rules
   {
      MyIcon /F
      {
        trigger_action: drop
        {
          for_info $d_position
        }
      }
   }

See also:

s_position, which is the position of the static argument

dynamic_args

The list of icons dropped for an action.

Description

The variable dynamic_args is set in the following situations:

Situation: What it is set to:

in a menu action thread the list of currently selected icons

in a static trigger action thread the list of currently selected icons

in a drag action thread the list of dragged icons

in a thread created by a menu_actions_of or actions_of command a list of the icons passed to the command

Situation:	What it is set to:
in a menu action thread	the list of currently selected icons
in a static trigger action thread	the list of currently selected icons
in a drag action thread	the list of dragged icons
in a thread created by a menu_actions_of or actions_of command	a list of the icons passed to the command

Example

The following icon_rules clause defines an icon that displays a dialog box listing the names of icons dropped onto it:

   icon_rules
   {
      * /F
      {
        trigger_action: d*
        {
          if == $#dynamic_args 1
          then
            for_info $dynamic_args 'was dropped on this icon'
          else
            for_info $dynamic_args 'were dropped on this icon'
          fi
        }
      }
   }

See also:

* (variable), which gives the list of arguments to a function or action
static_arg, which is the static argument

entered_name

Set to the name entered by the user when prompted to rename a file.

Description

The variable is set by the rename, make_new_file, duplicate, duplicate_link, and duplicate_symlink commands.

Example

The following example provides a New File (secure) menu command which creates a new file, and then changes its access permissions using the UNIX chmod command:

   menu_item: New File (secure) _s__
   {
     make_new_file $static_arg
     chmod 400 $entered_name
   }

ifs

Specifies the character at which strings should be split.

Description

The variable ifs affects strings split into lists by the split command and by `{...} substitutions. If ifs is unset, i.e., $#ifs is ``0'', strings are split on the three white space characters; i.e., space, tab, and newline.

The variable ifs affects the split command as follows:

If ifs (1) is set to the empty string, split splits its argument into a list of single characters.

Example

The following function, time, returns the current system time in the variable $timeofday:

   function time
   {
     ifs=' ' { datelist=`{ date } }
     timeofday=$datelist(4)
   }

The variable $datelist is set to a list such that, for example, on one system:

   $datelist(1)=Fri
   $datelist(2)=Mar
   $datelist(3)=15
   $datelist(4)=11:55:40
   $datelist(5)=PST
   $datelist(6)=1991

See also:

split, which splits a string into a list

last_background_action

The name of a background thread.

Syntax

last_background_action

Description

When a script runs a command in the background, with the & delimiter, the name of the thread is available in the variable last_background_action.

Example

The following example:

   for_info 'Hello' &
   sleep 10
   kill $last_background_action

will display an information dialog box, and then kill it by sending the default sigint signal, even if the user does not close it.

See also:

``&'', which runs a command in the background

ofs

Specifies the separators to be used when joining strings together.

Description

The variable ofs contains a list of four separators, which have the following functions:

$ofs(1): separator to be inserted between strings. Defaults to a single space if ofs has no elements.
$ofs(2): prefix placed in front of result
$ofs(3): suffix placed after result
$ofs(4): result if list is empty

The variable ofs is used in the following circumstances:

joining together the arguments of the eval and join Deskshell commands
joining together the lists generated by any command not run in a `(...) substitution
building the string value of each entry in the environment of an external program from the list value of the corresponding variable
building the value to be tested in the case statement

Example

The following example illustrates the result of executing:

   ofs=('//' '[' ']' '***')
   echo `(join $value)

for different values of $value:

Value Result

( ) ***

(Jan) [Jan]

(Jan Feb) [Jan//Feb]

(Jan Feb Mar) [Jan//Feb//Mar]

The appropriate element of ofs can be set to ``\n'' to use newline as the separator, prefix, or suffix.

Value	Result
( )	***
(Jan)	[Jan]
(Jan Feb)	[Jan//Feb]
(Jan Feb Mar)	[Jan//Feb//Mar]

See also:

join, which joins its arguments into one string

s_desktop

The name of the open desktop the static argument is on, if any.

Description

This variable is set at the start of a new thread generated by the actions_of Deskshell command, or for the duration of a script executed by the do_actions_of Deskshell command.

The value is set to the -s argument of the command or, if none is specified, to the empty list.

Example

The following example defines a Which Desktop icon, which displays the full pathname of the desktop on which it is activated:

   icon_rules
   {
      which_desktop /F
      {
         picture=desktop_c.px
         title=Which Desktop;
         trigger_action: activate
         {
            for_info You are on desktop $s_desktop
         }
      }
   }

See also:

d_desktop, which is the name of the desktop the dynamic arguments are on

s_position

The position of the static argument.

Description

This variable is set at the start of a new thread generated by the actions_of Deskshell command, or for the duration of the script invoked by the do_actions_of Deskshell command.

The value is the argument provided to the -S flag of the command, if one exists, or the string V otherwise.

Example

The following example is from the trigger_action: drop of a *.dt rule. When an icon is dragged across a desktop, s_position is the position where the mouse button is released, i.e. the destination of a drag and drop:

   get_out -a $s_position -l $dynamic_args -d $static_arg

See also:

d_position, which is a list of the positions of the dynamic arguments

static_arg

The static argument in canonical form.

Description

This variable is set at the start of a new thread generated by the actions_of and menu_actions_of Deskshell commands, and for the duration of the script executed by do_actions_of and do_menu_actions_of Deskshell commands.

For the action commands, $static_arg is set to a single string containing the canonical form of the static argument to the command.
For the menu commands, $static_arg is set to the argument to the -s, -d, or -D flag, in that order of precedence.

Example

The following rule is for an executable file called xprog. When the icon is clicked on, it will run xprog (which will be $static_arg) no matter where xprog is, or how many of them there are. This therefore always runs the correct xprog rather than an xprog in the $PATH somewhere:

   icon_rules
   {
      xprog /FX
      {
         trigger_action: activate
         {
            $static_arg
         }
      }
   }

See also:

dynamic_args, which is the list of dynamic arguments

status

The status of the previous command.

Description

When a command is executed, it generates a numerical status between 0 and 1023. (Note that certain built-in Deskshell commands do not return a status.)

When a command is executed and generates a status, that status is converted to a string and stored in the variable status. When a pipeline is executed, the individual statuses are collected and the strings are all stored in the variable status, in the same order as the commands in the pipeline.

The value of status is used implicitly by the following control constructs and operators:

if
while
until
&&
||

The following sections list the values of status that can be returned by commands.

Success:

OK (0)
the command completed successfully
Interaction return codes:

YES (0)
the answer is ``Yes'' or the user pressed Yes (for yni)

NO (1)
the answer is ``No'' or the user pressed No (for yni)

WASCLOSED (0)
the window was closed (report_status only)

WASOPEN (1)
the window was open (report_status only)

CANCELED (2)
the user canceled the command
Specific errors:

ERROR (255)
there was an error (not specified further)

NOTOPEN (1)
the specified desktop was not open

NOTRIGGER (1)
the specified file did not have an action for that trigger

NOTINPRIORITY (512)
the specified command is not permitted in a priority thread
Parsing errors:

NOTCOMMAND (768)
the specified command is unkown

BADFLAG (769)
the specified command is unkown

KEYCLASH (770)
the specified command is unkown

ATTRCLASH (771)
the specified command is unkown

MISSINGARG (772)
there is an error in the flags of a comment, e.g., unknown flag
Special errors:

MANY (780)
a command returning a count produced a count of 256 or above

ARGCOUNT (781)
the number of positional parameters was wrong

Some commands set status to a count of the number of operations of the command that failed, or MANY if the number of failures is greater than 255. External commands generate a status of 0 to 255, or 256 to 511 if terminated by a signal.

Example

The following example displays the status of a copy_desktop Deskshell command:

   copy_desktop -d $desktop $file
   case $status
   0   : for_info 'Desktop' $desktop 'saved in' $file ;;
   1   : for_info $desktop 'is not open' ;;
   255 : for_info 'Can''t save' $desktop 'in' $file;;
   *   : for_info 'Unknown error saving' $desktop 'in' $file ;;
   esac

thread_name

The name of the executing thread, and its parents.

Syntax

thread_name

Description

The element thread_name(1) contains the name of the current thread, thread_name(2) its parent thread, and so on.

Example

To set the variables THIS and DAD to contain the thread names of the current thread and the parent thread for manipulating later:

   THIS=$thread_name(1)
   DAD=$thread_name(2)

trigger

Set to the trigger name after an action command.

Example

The following rule displays the mouse button used to activate a Wizard icon:

   icon_rules
   {
     wizard /FWM
     {
       picture=wizard.px;
       title=Wizard;
       trigger_action: s*
       {
         if == $trigger 'activate'
         then
           for_info 'You double-clicked with mouse button 1 on me.'
         else
           for_info 'You double-clicked with another mouse button on me.'
         fi
       }
     }
   }

:Xdesktop_name

The name of this invocation of the Desktop.

Description

This variable is set at start-up to the name of the Desktop invocation. This name is intended to be unique amongst all invocations of the Desktop on a given machine or display, and is used by the tellxdt3 program to indicate which Desktop invocation is to be accessed.

Example

The following example sends the for_info Deskshell command to the desktop named in the :Xdesktop_name variable.

   tellxdt3 -name $:Xdesktop_name for_info 'Read this message'

See also:

tellxdt3(XC)

Deskshell operator and script delimiter descriptions

The following sections provide detailed descriptions of the Deskshell operators and script delimiters:

!

Negates the status of a command. A Deskshell operator.

Syntax

! command

Description

When the command completes, the value of status will be changed as follows:

``false'': the list (0)
``true'': the list (1)

Example

The following example uses the UNIX grep command to search the password file for a username:

   if ! grep $name /etc/passwd
   then
     for_info 'There is no account for' $name '.'
   fi

%

Defines a substitution. A Deskshell operator.

The following substitutions can be included:

%+filename+: include the file filename
%$variables$: include UNIX environment variable variable

In addition, the following special sequences can be substituted in picture and title clauses in icon_rules clauses:

%B0: the basename of the file
%C0: the class of the file, given as six characters in standard order
%D0: the absolute pathname of the directory holding the file
%E0: As %B0, but with the last dot and any characters following removed
%P0: the absolute pathname of the file
%R0: the relative pathname of the file, except when a title clause is being expanded within a directory window, when it is the same as ``%B0''

Example

For example, the file /fred/jim/data.tmp will be substituted as follows:

Sequence Substitution

%B0 data.tmp

%C0 FXWM (for example)

%D0 /fred/jim

%E0 data

%P0 /fred/jim/data.tmp

%R0 jim/data.tmp (if /fred is home)

Sequence	Substitution
%B0	data.tmp
%C0	FXWM (for example)
%D0	/fred/jim
%E0	data
%P0	/fred/jim/data.tmp
%R0	jim/data.tmp (if /fred is home)

<

Reads from a file. A Deskshell operator.

Syntax

< filename

OR:

< [number] filename

where:

filename

the filename to read from

number

an optional descriptor number. The following are examples:

0: standard input (the default)
1: standard output
2: standard error

Description

The following special constructs can also be used:

< [new=number]

makes new a duplicate of number, and:

< [number=]

closes descriptor number.

Example

The following example will mail the user claudio the contents of textfile:

   mail claudio < textfile

See also:

``>'', which writes to a file

=

Assigns a value to a variable. A Deskshell operator.

Syntax

variable=value

where:

variable: a Deskshell variable. If it begins with a ``:'', it is taken to be a global variable; otherwise it is a local variable.
value: a list value

Example

In the following examples:

   count=99

assigns the string ``99'' to the local variable count.

   fib=(1 1 2 3 5)

assigns the list ``(1 1 2 3 5)'' to the local variable fib.

   :temperature='hot'

assigns the list ``('hot')'' to the global variable :temperature.

See also:

``=='', which tests whether two strings are equal

>

Writes to a file. A Deskshell operator.

Syntax

> filename

OR:

> [number] filename

where:

filename

the filename to write to

number

an optional descriptor number. The following are examples:

0: standard input
1: standard output (the default)
2: standard error

Description

The following special constructs can also be used:

> [new=number]

make new a duplicate of number, and

> [number=]

closes descriptor number.

Example

The following example puts the output of the who command into a file called Users.Log:

   who > Users.Log

See also:

``<'', which reads from a file
``>>'', which appends to a file

>>

Appends to a file. A Deskshell operator.

Syntax

>> filename

OR:

>> [number] filename

where:

filename

the filename to append to

number

an optional descriptor number. The following are examples:

0: standard input
1: standard output (the default)
2: standard error

Description

The following special constructs can also be used:

>> [new=number]

makes new a duplicate of number, and

>> [number=]

closes descriptor number.

Example

The following example appends the output of the who command to the file Users.Log:

   who >> Users.Log

See also:

``<'', which reads from a file
``>'', which writes to a file

\

Includes a special character. A Deskshell operator.

Syntax

\code

Description

The following special codes can be specified within scripts, outside quoted strings:

\n: newline character
\t: tab character
\nnn: character with octal code nnn (up to 3 digits)
\xnn: character with hex code nn (any number of digits)

Example

The following example displays an information dialog box containing two lines of text:

   for_info 'Current directory:'^\n^`pwd

^

Concatenates lists. A Deskshell operator.

Syntax

list^list

Description

Lists can only be concatenated if they both contain the same number of elements, or if one of them only contains one element or is empty, as illustrated by the following examples:

a b a^b

w x wx

w (x y z) (wx wy wz)

(w x y) (a b c) (wa xb yc)

(w x y) ( ) (w x y)

(w x y) (a b) illegal

Several concatenations can be included in one expression, as in:

a	b	a^b
w	x	wx
w	(x y z)	(wx wy wz)
(w x y)	(a b c)	(wa xb yc)
(w x y)	( )	(w x y)
(w x y)	(a b)	illegal

   s.^(in  proc  out)^.main.^(c  h  s)

which evaluates to:

   (s.in.main.c  s.proc.main.h  s.out.main.s)

Deskshell performs an implicit concatenation where the syntax is unambiguous. For example, the strict form $file^.c can be written as $file.c instead.

Example

The following script provides:

   Edit: fred

as the title of a shell window:

   name='/usr/test/fred'
   shell -n 'Edit: '^`(basename $name) $EDITOR $name

` (backquote)

Returns the result of executing a command. A Deskshell operator.

Syntax -- command substitution

`{script}

where:

script: a general script, which can include external commands

Description

The script is executed, and its output is then split at the characters specified in the first string in the variable ifs. If ifs is an empty list, the output is split at white space. The resulting list is substituted into the script.

Example

The following script displays the number of words entered in a string:

   for_info You entered `{gti Enter a string | wc -w} words

Syntax -- list substitution

`(command)

where:

command: a built-in Desktop command or function

Description

The command is executed and its output is substituted directly into the script. If the command does not return text the result is an empty list. The result of a function is specified by the return command, or is an empty list if there is no return command. If the command does not have any arguments, the brackets can be omitted. For example, `pwd is equivalent to `(pwd).

The following built-in commands return text, and so can be useful in this construction:

absreadlink basename

canonical dirname

extension fileclass

followlink get_attribute

get_resource gti

join list count

list intersect list sort

list subtract list uniq

merge pwd

query all_triggers query contents

query main_desktop query open_desktops

query open_directories query open_treeviews

query thread_info query picture

query pixmap query selections

query size query threads

query title query visibility

readlink relativepath

sequence split

tolower toupper

unextended variables

Example

This example sets var to a list of the basenames of the files in $list:

   var=`(basename $list)

match (~)

Tests whether a string matches other strings. This operator can be abbreviated to ``~'' (tilde). A Deskshell operator.

Syntax

match test target . . .

where:

test: string to be matched
target: one or more strings to be matched against

Description

The match succeeds if test matches any of the target strings, and fails if no string matches. The target strings can contain wildcards.

The test and target strings can come from variables, or other constructs. However, wildcards in targets have to be stated explicitly.

Status

The command sets the value of status as follows:

YES (0): if at least one string matches
NO (1): otherwise

Example

To test that $x begins with ``a'':

   match $x a*

To see if $x is the name of an existing file beginning with ``a'':

   a=a*
   match $x $a

Note that the following commands:

   x=((test a1) a2)
   match $x b*

are equivalent to:

   match test a1 a2 b*

and result in the string ``'test''' being tested against ``'a1''', ``'a2''', and ``'b*'''.

#

Defines a comment to the end of the line in a Deskshell script. A Deskshell script delimiter.

Syntax

# comment

Description

The # character can be used within scripts to comment out everything up to the end of the line. It can be used anywhere a script delimiter, such as ``;'' or ``&'', would be valid. Elsewhere, # is treated like any other character.

Example

In the following example:

   number=`(gti 'Enter # of files') # Get file count

only the section ``Get file count'' is treated as a comment.

Note, however, that:

   number-`(gti Enter # of files)

is an incomplete command, equivalent to:

   number=`(gti Enter

See also:

``%//'', which defines a comment in a rule clause

%//

Defines a comment line in a rule clause. A Deskshell script delimiter.

Syntax

%// comment

Description

The %// comment prefix can be used anywhere in rule files, but not in object trigger files.

Example

In the following example, the text after the %// will be taken as a comment:

   for_info 'Use %// for comments'

In this case you would need to use:

   for_info 'Use %%// for comments'

See also:

``#'', which defines a comment in a Deskshell script

&

Runs a command in the background. A Deskshell script delimiter.

Syntax

command &

where:

command: the command to be executed in the background

Description

The command is run in a separate thread, which is a child of the current thread. In the parent thread, the name of the child thread is available in the variable last_background_action. The command does not wait for the child thread to terminate.

A script of several commands can be run in the background by using { } brackets, as in:

   {
      command1
      command2  
      command3
   } &

or by defining a function and then executing the function in the background:

   function myfun
   {
      command1
      command2
      command3
   }
   
   myfun &

Example

The following example runs a script in the background to update open directories continuously:

   {
      while true
      do
         mark_changed_directory
         sleep 30
      done
   } &

See also:

``;'', which terminates a command
``|'', which pipes output from one command into another

&&

Runs a second command if a first command returns a true status. A Deskshell script delimiter.

Syntax

commandif && commandthen

where:

commandif: the command
commandthen: the command to be run if commandif returns ``true''

Description

This delimiter is equivalent to:

if commandif then commandthen fi

Example

The following example displays a message if $A and $B are equal:

   == $A $B && for_info 'They are the same'

See also:

``||'', which runs a command if the first command returns a false status

;

Terminates a command. A Deskshell script delimiter.

Syntax

command ;

Description

The command is executed in the same thread. The ``;'' may be omitted at the end of a line.

Example

The script:

   for file
   do
      get_out $file
   done

could be written on one line:

   for file; do get_out $file; done

See also:

``&'', which runs a command in the background
``|'', which pipes output from one command into another

{ ... }

Group commands together. A Deskshell script delimiter.

Syntax

{ commands }

Example

Braces can be used to override the priority of the ``&&'' and ``||'' script delimiters, as illustrated in the following example:

   if -eq $x 1 || -eq $y 2 && -eq $z 3
   then
     for_info '$z is 3 and also $x is 1 and $y is 2'
   fi
   if -eq $x 1 || { -eq $y 2 && -eq $z 3 }
   then
     for_info 'Either $x is 1 or $y is 2 and also $z is 3'
   fi

See also:

``&'', which runs commands in the background
` (backquote), which returns the result of executing a command

|

Pipes the output of one command to the input of another. A Deskshell script delimiter.

Syntax

commandout | commandin

where:

commandout: the command from which output is taken
commandin: the command to which output is passed

Description

A child thread is created for each command, and these are connected by pipes, one pipe per descriptor. The original thread stays blocked until all the children have terminated. For each pipe you can specify the input and output file descriptors using the syntax:

commandout |[output] commandin

or:

commandout |[output=input] commandin

where output is the output file descriptor (which defaults to ``1'', standard output), and input is the input file descriptor (which defaults to ``0'', standard input).

Status

The individual statuses are converted to strings, and these are all stored in the variable status, in the same order as the commands in the pipeline. For example, the pipeline:

   true | false

generates the status ``(0 1)''.

Example

The following example counts the number of words in a directory listing by piping the output of the UNIX ls command through the wc command:

   ls | wc -l

||

Runs a second command if a first command returns a false status. A Deskshell script delimiter.

Syntax

commandif || commandelse

where:

commandif: the command
commandelse: the command to be run if commandif returns false

Description

This delimiter is equivalent to:

if commandif else commandelse fi

The order of priority is:

Highest { }

if for case

|

&& ||

Lowest & ;

The following table illustrates how these priorities work for a range of examples:

This example: Is equivalent to:

a && b || c if if a then b fi else c fi

a && b ; c { a && b } ; c

a && {b || c} if a then if b else c fi fi

This example:	Is equivalent to:
a && b \|\| c	if if a then b fi else c fi
a && b ; c	{ a && b } ; c
a && {b \|\| c}	if a then if b else c fi fi

Example

The following example displays a message if $A and $B are not equal:

   == $A $B || for_info 'They are not equal'

See also:

``&&'', which runs a command if the first command returns a true status

Deskshell script control construct descriptions

The following sections provide detailed descriptions of the Deskshell script control constructs:

case

Executes alternative commands depending on the value of a variable.

Syntax

case test

[ target . . . : script ;; ] . . .
esac

where:

test: a test string
target: the target string
script: the script to be executed if test matches any of the target strings

Description

The test string is compared with each of the target strings until a match is found. If a match is found, the corresponding script is executed.

The target strings can contain any of the following:

'string': the string
``?'': one character
``*'': zero or more character
[string: any character in string

If test is a command, it is evaluated to form a list of strings, and after wildcard expansion, these are concatenated together using the delimiters supplied in ofs to give the test string.

Example

The following example sets button to a textual string depending on the numerical value of b:

   
   case $b
      1:button='first' ;;
      2:button='second' ;;
      3:button='third' ;;
      *:button='unknown' ;;
   esac

In the above example, the quotes are optional.

The following example identifies a string $c:

   
   case $c
      *day         : value='day of week' ;;
      [0123456789] : value='number' ;;
      [*?]         : value='wildcard * or ?' ;;
      *            : value='not recognized' ;;
   esac

See also:

match (~), which matches a test string against arguments

exit

Terminates a thread.

Syntax

exit [status . . .]

where:

status: value to be assigned to the variable status when the thread terminates

Description

Terminates a thread. System and window threads will not exit, but will suspend, unless the window has been closed or the Desktop is exiting.

Note that if exit is performed within a function called by a script, then both the function and the script are exited immediately.

Status

If there are any arguments, status is set to the arguments.

Example

The exit command can be used to exit prematurely from a script, as in:

   trigger_action: drop
   {
      if != $#dynamic_args 1
      then
         for_info 'Please drop one icon'
         exit
      fi
      script
   }

which only executes script if one icon has been dropped.

for

Executes a script for each value in a list.

Syntax

for name [in arguments]
do
script
done

where:

name: variable name
arguments: a list of values. If omitted, defaults to $*.
script: script which is executed once for each value in the list

Description

The arguments are converted to a list of strings; wildcard expansion is performed on the list. The script is then executed once for each string in the arguments list, with the variable name set to that string for that iteration. The value of name is undefined after the for statement completes.

The argument list is stored before the first iteration of the loop, so changes to the list or the loop variable have no effect.

Status

The status is the status of the script the last time it was executed.

Examples

The following script compresses all the files dropped onto a Compress icon:

   icon_rules
   {
      compress /F
      {
         trigger_action: drop
         {
            for file
            do
               compress $file
            done
         }
      }
   }

Similarly, to compress all files in a particular directory:

   cd $directory_to_compress
   for file in *
   do
      compress $file
   done

The following example:

   x=(a b c)
   y=''
   for i in $x
   do
      i='**'$i
      y=$y$i
      x=(d $y)
   done

will set y to ``'**a**b**c''' and x to ``(d '**a**b**c')''.

See also:

until, which executes a script until a condition is satisfied
while, which executes a script while a condition is satisfied

function

Defines a function.

Syntax

function name { script }

where:

name: the function name
script: the commands to be executed

Description

Functions can be used to avoid repeating the same commands in a rule file. The script is not evaluated when a function definition is executed, though it will be parsed and syntax errors detected.

A function is called with the syntax:

name [argument . . .]

where the arguments are passed to the function in the variable ``*''.

The function definition can be canceled with:

function name { }

Example

The following function returns a string identifying the kind of window an action originated in:

   function what_window
   {
      if match `(fileclass $1) D*
      then
         _window_type='Desktop'
      else
         _window_type='Directory'
      fi
   }

See also:

return, which returns from a function

if

Executes a script if a condition is true.

Syntax

if scripttest
[then scripttrue]
[else scriptfalse]
fi

where:

scripttest: a script evaluated for ``true'' or ``false'' status
scripttrue: the script executed if scripttest is true
scriptfalse: the script executed if scripttest is false

Description

An elif can be included to provide further tests:

if scripttest1
then scripttrue
elif scripttest2
then scripttrue
else scriptfalse
fi

The scripts following if or elif are executed in order until one completes with a true status. The script following the corresponding then, if any, is executed. If no scripts complete with a true status, the script following else, if any, is executed.

Status

The status is that of the last script executed.

Example

The following function returns a string identifying the kind of window an action originated in.

   function what_window
   {
      if
      then
         _window='Desktop'
      else
         _window='Directory'
      fi
   }

return

Returns from a function.

Syntax

return [argument . . .]

Description

The currently executing function, if any, is exited as if control had reached its end. If there are no functions currently executing, then the effect is the same as the exit command.

The result is the specified argument strings.

Example

The following function multiplies two numbers together. If the number of arguments is not equal to 2, the return will cause the function to return back to where it was called from:

   function multiply
   {
     if -ne $#* 2
     then
        return
     fi
     answer=`{expr $1 '*' $2}
   }

A function can return a result. For example:

   function strip_first
   {
     return $*(`(sequence 2 $#*))
   }
   A=(this is a list)
   B=`(strip_first $A)

sets B to the list:

   (is a list)

See also:

function, which defines a function

until

Executes a script until a condition is true.

Syntax

until script1
do script2
done

where:

script1: the script in which status is tested
script2: the script to be executed

Description

First script1 is executed. If the status is ``false'', script2 is executed and script1 is re-executed. If the status is ``true'', the until statement is completed.

Status

The variable status is true on exit normally, but could be false if the loop was exited by a break command.

Example

The following script will loop until the user clicks Yes to the question ``Are you finished yet?''. The until loop will keep looping until the variable ans is set to ``Finished'':

   ans=''
   until == $ans Finished
   do
      ...
      if yni 'Are you finished yet?'
      then ans='Finished'
      fi
      ...
   done

See also:

while, which executes a script while a condition is true

while

Executes a script while a condition is true.

Syntax

while script1
do script2
done

where:

script1: test
script2: script to be executed

Description

First script1 is executed. If the status is ``true'' after it completes, then script2 is executed and script1 is re-executed. If the status is ``false'', the while statement is completed.

Status

The variable status is normally false on exit, but could be true if the loop was exited by a break.

Example

The following script will loop until the user clicks Yes to the question ``Are you finished yet?''. The while loop will keep looping until the variable ans is set to ``Finished'':

   ans='Busy'
   while == $ans Busy
   do
      ...
      if yni 'Are you finished yet?'
      then ans='Finished'
      fi
      ...
   done

See also:

until, which executes a script until a condition is true

Deskshell test descriptions

The following sections provide detailed descriptions of the Deskshell tests:

!=

Tests whether two strings are not equal.

Syntax

!= string1 string2

Status

The command sets the value of status as follows:

YES (0): the strings are not equal
NO (1): the strings are equal

Example

The following example tests whether the strings $A and $B are not the same:

   != $A $B

See also:

``=='', which test whether two strings are equal

--

Tests two integers to generate a status.

Syntax

-predicate number1 number2

where:

predicate: the predicate; see table below
number1, number2: the integers to test

Description

The predicate can be any of the following:

-eq: test whether number1 is equal to number2
-ne: test whether number1 is not equal to number2
-lt: test whether number1 is less than number2
-le: test whether number1 is less than or equal to number2
-gt: test whether number1 is greater than number2
-ge: test whether number1 is greater than or equal to number2

Status

The command sets the value of status as follows:

YES (0): the predicate is true
NO (1): the predicate is false

Example

The following example tests whether the number $A is equal to the number $B:

   -eq $A $B

The tests are purely numeric, involving only integers. Any character not in the range ``0'' to ``9'' terminates that number, so:

   -eq 1 1
   -eq 1 01
   -eq 1A 01.5
   -eq 0 Fred

are all true. In the last case there is no numeric part, so the second argument is treated as zero.

See also:

``=='', which tests whether two strings are equal
``-same'', which tests whether two variables have the same contents

-class

Tests whether a pathname has a specified class.

Syntax

-class object class

where:

object: the object to be tested
class: a sequence of characters specifying the class

Status

The command sets the value of status as follows:

YES (0): the object has specified class
NO (1): the object does not have specified class

Example

The following example does not allow directories to be dropped onto the SomeFile icon:

   SomeFile /F
   {
      trigger_action: drop
      {
         if -class $dynamic_args D
         then
           for_info 'Directories may not be dropped on this icon.'
         fi
      }
   }

See also:

fileclass, for more information about file classes

-same

Tests whether two variables have the same contents.

Syntax

-same name1 name2

where:

name1: first variable to be tested
name2: second variable to be tested

Status

The command sets the value of status as follows:

YES (0): the variables have the same contents
NO (1): the variables do not have the same contents

Example

The following table illustrates the difference between -eq, which compares two numbers, ``=='', which compares two strings (and expects only two arguments), and -same, which compares the contents of two variables.

The results assume the following assignments:

   A=(cat)  B=(cat dog)  C=(cat dog)  D=5  E=6

Example Value of status

-eq $D $E NO(1)

-eq 10 10 YES(0)

-eq $A $B illegal

== $A 'cat' YES(0)

== $A $B(1) YES(0)

== $A $B illegal

-same A B NO(1)

-same B C YES(0)

-same $A $B

illegal

Example	Value of status
-eq $D $E	NO(1)
-eq 10 10	YES(0)
-eq $A $B	illegal
== $A 'cat'	YES(0)
== $A $B(1)	YES(0)
== $A $B	illegal
-same A B	NO(1)
-same B C	YES(0)
-same $A $B
illegal

==

Tests whether two strings are equal.

Syntax

== string1 string2

where:

string1: first string to be tested
string2: second string to be tested

Status

The command sets the value of status as follows:

YES (0): the strings are equal
NO (1): the strings are not equal

Example

The following example tests whether the string $A is the same as string $B:

   == $A $B

See also:

-eq, which tests whether two numbers are equal
-same, which tests whether two variables have the same contents

Files

/usr/lib/X11/IXI/XDesktop/rules/system/xdtsysinfo
/usr/lib/X11/IXI/XDesktop/rules/modules
/usr/lib/X11/app-defaults/XDesktop3

absreadlink	basename
canonical	dirname
extension	fileclass
followlink	get_attribute
get_resource	gti
join	list count
list intersect	list sort
list subtract	list uniq
merge	pwd
query all_triggers	query contents
query main_desktop	query open_desktops
query open_directories	query open_treeviews
query thread_info	query picture
query pixmap	query selections
query size	query threads
query title	query visibility
readlink	relativepath
sequence	split
tolower	toupper
unextended	variables