QL(1): clive shell
__________________________________________________
USAGE
usage: ql [-DLNYcinux] [file] ...
-D: debug
-L: debug lex
-N: debug nodes
-Y: debug yacc
-c: run args as a command
-i: interactive
-n: dry run
-u: do not use unix IO
-x: print commands as they are run
DESCRIPTION
Ql is the Clive shell. In reads commands from either the
standard input or a file given in the command line and executes
them. Flag -c may be used to make the arguments represent a
command to be executed and not file names.
When executing a file, the entire file is read before processing
its contents. It is safe to edit or remove the file while it
runs. Arguments following the given file name are used as
arguments for the script file being executed. Under flag -c the
command is supplied in the argument list.
Text enclosed in single or reverse quotes, like '...' and `....`
is taken verbatim as a single word.
The # character can be used to write line comments. Empty lines
are ignored. All other text is parsed as a series of commands.
Each command is executed only after its source text has been
fully parsed. For example, commands within a block are not
executed until the entire block is read from the input text and
parses correctly.
The prompt is '> '. Any run of '>' characters (and blanks) at the
start of line are silently discarded, to help the user in
selecting command lines and executing them again.
Commands are one or more words (none for the empty command)
terminated either by a new-line character or using a ';'. A
backslash before a new-line converts the new-line into a space,
to type long commands in multiple lines. After a pipe-line
character, a new-line may be typed and it will be ignored, for
the same purpose.
Command words are separated by runs of white space, unless they
result from constructs (described later) which preserve words as
generated by other commands.
A command can be:
+o A pipe line
+o A block of commands
+o A source command
+o A function definition, terminated with a new-line or a ;
character.
+o A for loop
+o A while loop
+o A cond (conditional) structure
+o An assignment.
In all cases, optional redirections for input and output can
follow. An optional & can be added at the end if ql should not
wait for the command to terminate before prompting for another
command. This is called a background command. The & operator can
be followed by a name to tag the command. The wait builtin waits
for background commands and can be given tags as arguments to
wait just for those commands. Without arguments, wait waits for
all outstanding background commands.
A pipe-line is a series of simple commands separated by ''
characters, perhaps a single one, or an empty one. Here, the in
channel of a command is the out channel of the preceding one. The
syntax '|[err]', (where err can be any channel name) connects the
err channel of the preceding command to the in channel of the
following one. The syntax '|[x:y]' connects the y channel of the
preceding command to the x channel of the following one. The
general syntax permits arbitrary networks of channels and has the
form '|[x:y,z;p:q,r...]'
The first name is a list of names used as a command is understood
as the command name. If it matches the name of a function, the
function is executed as a command. If it matches the name of a
built-in, the built-in is executed as a command. If the name
starts with '/', './', or '../', it is uses as a relative path to
the file for the command. Otherwise, the name is appended to each
of the directories in $path (or $PATH if the former is not
defined) and the first file found with execute permissions is run
as a command. The type builtin may be given one or more names and
prints the type of name (function, builtin, etc.).
When a command terminates, $sts contains the exit status for the
command, which is empty for success.
A block of commands is a series of commands encondes in '{' and
'}' characters.
A source command has the form
< file
and executes the text in file as commands. This can be used to
include input for the shell from another file.
Functions may be defined line in
func name { cmds }
Once defined, the function name may be used as a command.
Arguments supplied are available in $argv within the function.
The name of the function is in $argv0. The status of the last
command in the function is used as the status of the function.
The for control structure has the form
for name val... { cmds }
and sets $name to each one of the names that follow and runs the
body block for each value.
When using the form
for name { cmds }
the loop iterates over the messages received from the standard
input and not over the names given in the command line.
The while control structure has the form
while cmd { cmds }
and executes the body block while the command used as a condition
terminates with success.
The cond control structure is the only conditional and has the
form
cond {
cmd1
cmd2
...
cmdn
}
With optional or branches added, like in:
cond {
...
} or {
...
} or {
...
} ...
Each one of the or branches (perhaps a single one if no or is
used) executes in order until one succeeds. An or branch executes
the commands in its block in order until one fails or until the
last command runs. If the last command runs, the or branch
succeeds. In short, the conditional is an or for ands of
commands. You might think of all commands in a block as the
conditions for the last command in that block, which might be
considered as the body of a conventional if construct.
VARIABLES
A name list (as used in a command) may include names starting
with '$' which are replaced by the values of the conrresponding
(environment) variables. Each variable is a list of names, and
the substitution preserves the name boundaries. Variable values
are never parsed as control structures and are expanded just
once, as part of a name list.
Within a name, the characters '=$' are not special and are
considered part of the name, but the '=' character is still
considered the assignment operator within the first name of each
line. This produces the desired results in most cases and avoids
the need to quote the '=' character in predicates and command
arguments.
A variable may be assigned a value using
name=value
or
var←name
where value is, in general, a list of names. For example:
name = (a b c)
The syntax '$name' expands to the series of names in the value of
the variable. The number of elements is retrieved using '$#name'.
The syntax '$^name' can be used to expand the value of the
variable to a single name (with words joined by single spaces).
Each element in the list can be retrieved using '$name[0]',
'$name[1]', etc. The index can be a variable, as in
'$name[$idx]', but using '$$name' is a syntax error. The
assignment
name[n]= value
updates the value of that position in the variable. Even if value
is a list, the variable still retains the same number of
elements. One of the examples further illustrates this.
Variables can be also maps, defined as in
name=([key1 values...] [key2 values...] ...)
The expression '$name' expands to the set of keys for the map.
The expression '$name[key]' expands to the values for that key.
See the example section.
Lists can be concatenated using the '^' operator. If both
arguments have the same number of elements, the result is a list
with the same number of elements and each one is the
concatenation of the same element in both lists. If one of the
lists has one element, that element is concatenated to each one
of the elements of the other argument. Otherwise, it is an error
to try to concatenate the lists. But you might use:
x=($y and other values)
The shift builtin drops the first name in the named variable, or
in argv if no variable name is given.
The following variables are pre-defined or used by the shell:
argv the argument list of scripts and functions argv0 the name of
the script sts the exit status of the last command. For blocks,
the one of their last command path the preferred locations to
search for external commands. The user may assign values to them.
Although not predefined, the NS variable contains the textual
representation of the name space, as shown in [cite: intro(1)],
when name spaces are used.
REDIRECTIONS
Optional edirections can be written at the end of commands. Note
that a redirection.
To redirect standard input from a file, use
cmd... < name
or
cmd... <[in] name
The name in brackets indicates the channel that is to be defined
as the input channel from the named file. Here, _name_ is the
name for a file (tree), including both a path and a predicate,
thus
cat <,-
would print the contents of all the regular files under the
current directory. In this example the name has an implicit '.'
as the path and a '-', which is actually 'type=-', as the
predicate; together it means all the regular files under the
current directory). All those files are streamed through the _in_
channel for the command.
To redirect standard output to a file, use
> file
to create the output file (or truncate it). Or use
>> file
to append to that file. In this case, for safety, no predicates
are accepted; only a file path.
Output channel names may be given after the redirection operator
to redirect output for those channels to the named file, as in:
cmd >[err]/tmp/errors
cmd >[out,err]/tmp/outputanderrors
The syntax
cmd >[out:err]
makes the _out_ channel be that used as the _err_ channel. It is
a _dup_, and channels are named in the same order used in the
assignment, as a remainder of which channel is the old one and
which one is the new one.
The syntax
cmd <{cmd2...}
Takes the output from _cmd2_ and interpolates it in the command
line at that place. This is command substitution. Each message
printed by _cmd2_ is used as a different word in the command
line. There are examples later, but these are usual usages:
cmd <{cmd2... | lines}
cmd <{cmd2... | words}
cmd <{cmd2... | all}
The syntax
cmd <[in2]{cmd2...}
creates the _in2_ channel for _cmd_ as an input channel that will
convey the output for the enclosed _cmd2_, and the whole
construct is replaced by the name of the channel. When Clive
commands convert the arguments to input channels, they notice
that the name is for an input channel and retrieve input from
there. The general construct is '<[in:out1,out2...]{...}' to pipe
arbitrary channels.
The syntax
cmd >[out2]{cmd2...}
is similar, but it creates an output channel to _cmd2_ given as
an argument to _cmd_.
BUILT-IN COMMANDS
The following commands are built into ql: cd [name] Change
current directory to the given one or the home directory if none.
pwd Print the working directory. exit [sts] Terminate the
execution of ql using the given argument, if any, as the exit
status. break Stop the enclosing construct (a for, while, or
cond) and continue executing the next command. wait {tag} Wait
for previous background commands to complete. If no tag is
supplied, it waits for all of them. Otherwise, it waits for the
pipeline with the given tag (an optional name written after the &
in the pipeline). type {name} inform of the type of object known
as name. It may be a builtin, a function, an environment variable
or the path used to execute it as a command. fork {resource}
dups the resource, which can be ns, io, dot, or env. shift [var]
Drop the first element of the given variable (argv by default).
Most other Clive commands are usually linked into the same ql
binary, use type to discover which ones are external and which
ones are not.
EXAMPLES
Variables as lists:
> x=(a b c)
> x[0]=(q w e)
> echo $x
q w e b c
> echo $#x
3
> echo $x[0]
q w e
> x=<{eco $x}
> echo $x
q w e b c
> echo $#x
1
> x=<{eco $x|words}
> echo $#x
5
Concatenation:
> x=(a b)
> echo $x^x
ax bx
> y=($x c d)
> echo $y
a b c d
> echo $#y
4
Variables as maps:
> x=([a b] [x y z])
> echo $x
a x
> y=$x[x]
> echo $y
y z
> echo $#y
2
Command substitution:
> for x <{eco a ; eco b} {
> eco -u $x
> }
a
b
> for x <{eco a b} {
> eco -u $x
> }
a b
Also,
> for line <{lf -g ,- | lines} {
> do something to $line
> }
which can be done also as:
> lf -g ,- | lines | for line {
> do something to $line
> }
> eco -u <[in2]{eco a}
|<in2
> pf <[in2]{eco a} <[in3]{eco b c}
c --------- 0 |<in2
a
c --------- 0 |<in3
b c
Predicates and redirections:
Issue an error to standard error:
eco errors >[out:err]
Show all Go sources under the current directory
pf <,~*.go
Or
lf -g .,name~*.go | pf
List all regular files under the current directory:
lf -u ,-
Long-list them:
lf -u ,- |pf -l
Grep them for foo:
gr -u foo <,-
Define a long-list function:
func ll {
lf $argv | pf -l
}
SOURCE
+o
/zx/sys/src/clive/cmd/ql
SEE ALSO
+o
/zx/sys/src/clive/cmd/ql/example contains examples for all the
syntax understood by the shell.
__________________________________________________
User's manual. Section 1. Copyright © LSUB 2014-2016