zoiduser - Extended user documentation for zoid
The location of config and data files can be installation specific. You can check the location where zoid looks for them with the command zoid --config.
zoid --config
By default zoid uses two run control files: /etc/zoidrc and ~/.zoidrc or ~/.zoid/zoidrc, these are ordinary perl scripts that can interface with zoid. In general data files are found in ~/.zoid/, /usr/local/share/zoid/ or /usr/share/zoid/ these are called 'data_dirs'.
Of the data dirs the sub dir data contains some hashes with general config values, here the most important is the settings file because this is the first file read, it is evaluated before anything else, even before the run scripts. The hash defined by this file is the settings hash which contains all your run time configuration.
The sub dir plugins can contains config files for various plugins or directories with all files belonging to a plugin. The following plugins are included in the standard distribution:
Ships a collection of standard builtin commands that one would expects to have in a shell.
Keeps a history of your doings.
Takes care of tab expansion.
Tries to load a module from the Term::ReadLine family of modules.
In theory you should be able to remove or replace any of these plugins, but you better not try this till a more stable version of zoid.
Key bindings depend on the ReadLine module that is loaded. See for example Term::ReadLine::Zoid.
The following settings supported by (some) Zoidberg modules. They are housed in the hash ->{settings}. Also the builtin set command acts on this hash.
->{settings}
set
( FIXME link to doc on set command )
More advanced settings can be found in zoiddevel.
It allows to have wildcard patterns that expand into an empty list. The default behavior is to leave the pattern unchanged when it is syntactically incorrect, or when the list of matching pathnames is empty.
Disable path expansion for shell-like syntax.
Hide all object methods and data structures which have a name starting with an '_' unless they are asked for explicitly.
Hide all filesystem nodes which have a name starting with a '.' unless they are asked for explicitly.
When this setting is in effect a ^D char, also known as EOF or EOT, won't exit the shell.
Don't hide the root object behind clothes for things like tab completion and the single arrow operator, but show it in full glory.
Asynchronous notification, don't wait for the respawning of a prompt before notifying the user about background jobs that have finished.
This option should be named 'notify_async' for clearity, but 'notify' is the proper name according to POSIX.
When you stop a job the shell will show all jobs instead of just notifying just of the one you stopped; makes the behaviour more tcsh(1) like.
Since the syntax of the Zoidberg shell is completely configurable we can only comment on the syntax as defined by the default config files. The general structure will be the same for most user defined configuration but any markup or token could be changed to render the syntax completely unrecognizable.
The Zoidberg syntax consists of three levels of grouping:
First the syntax is split into blocks with logical/script delimiters
[block] && [block] || [block] ; [block]
Once the string is cut into logical blocks each of these blocks is split in sub blocks by pipes and.
[sub_block] | [sub_block] | [sub_block]
At last for each of these sub-blocks a context is decided like:
SH - sh like syntax (only very basic statements) CMD - builtin commands PERL - blocks of perl code
Each is executed differently by a suitable subroutine or application, and all are glued together to form a pipeline.
The contexts named below are hardcoded, others can be added by plugins. To disable hardcoded contexts see the _no_hardcoded_context setting.
Perl is the default context if the whole block is between curly brackets, when the first non-whitespace char of the block matches $,@ or % , when the first word seems to be a subroutine because it has parenthis or when the first word is a perl keyword like 'if', 'while', 'for' etc. These keywords can be configured with the array in ->{settings}{perl_keywords}
->{settings}{perl_keywords}
# perl because of reserved word zoid> for (0..3) { sleep 1; print $_ . "\n" } # perl because of dollar sign zoid> $self->{settings}{naked_zoid}++ # perl because of parentheses zoid> ls(qw/-al/) # perl because of curlies zoid> { open TEST, '<test.dat' }
Perl code can have modifiers after the last curly. Currently supported are :
n: enclose the expression in a "while STDIN" loop p: like 'n' but also print $_ at the end of each loop g: grep lines from STDIN that make the expression return non-zero z: use strict, no strict is the default # example zoid> ls -al | { s/^(d)\S+/DIR:/ }g
Zoidberg applies a bit of source filtering is applied to the perl code. This renders a lonesome dereference operator -> into $self->.
->
$self->
# Thus zoid> ->kill('1230') # is the same as zoid> $self->kill('1230')
Also variables in all capitals get translated to environment variables, arrays in all capitals cause a tied array to be imported from Env.
# Thus zoid> print $PATH # is the same as zoid> print $ENV{PATH} # and this also works zoid> push @PATH, '/usr/X11R6/bin/'
To avoid this source filtering you can use the perl{ ... } syntax. ( Although once a tied array is imported, it's there. )
perl{ ... }
Non-existent sub routines are AUTOLOAD'ed to be built-in or system commands, alias- and other expansions apply.
# Thus zoid> ls('*') # is perl, but does exactly the same as zoid> ls *
When such a AUTOLOAD'ed routine is used in scalar or list context it's output will be captured and returned as scalar or list.
# examples zoid> ls($_) for cat('MANIFEST') zoid> mplayer( locate('blinkenlights.mpg') )
For this "capturing mode" the record separator ($/) can be set by using $ENV{RS}.
$/
$ENV{RS}
This context is intended to make the Zoidberg shell a little friendlier to people used to shells like bash(1). Also this syntax requires less chars to execute a system command. Only the most basic stuff is implemented, you should use perl for things like flow control. Since the default syntax for pipelines and logic lists is also the same as in "sh like" shells a lot of simple constructs will work as expected.
# this does what it would in /.*sh/ zoid> ls -al | grep -v CVS | grep ^d > dirs.txt
Be aware redirections ain't fully supported
Currently only the following operators are defined for redirections : '>', '<' and '>>'.
Quoting does not entirely work like in "sh like" shells. Most importantly, you can't start a quoted block in the middle of a word, if you use quotes you need to quote an entire word.
All words, are subject to parameter- and path-expansion unless they are quoted. For double quoted words only parameter expansion is performed, for single quoted words no expansion is performed at all. Parameter expansion interpolates environment variables. (Path expansion is sometimes also called 'glob expansion')
All parameters can be used as arrays, the colon ':' will be used as element separator. To get one element the form $VAR[$i] is recognized by the parameter expansion, where $i is a null-based integer. The form @VAR is a special case that will be expanded to a word list of all the array elements. To avoid conflicts with things like the 'user@host' format used by many applications this special case can only be used as a separate unquoted word.
$VAR[$i]
$i
@VAR
zoid> echo $PATH /bin:/usr/bin/:/usr/local/bin zoid> echo $PATH[2] /usr/local/bin zoid> echo @PATH /bin /usr/bin/ /usr/local/bin
This context is not really distinguishable from the SH context, but it is used for builtin commands (perl subs that fake to be a system command). There was need for a separate context for this so built-ins won't have to fork (unless used in a pipeline) and thus can alter the parent environment. Commands are housed in the hash ->{commands} and plugins can add to these very easily.
->{commands}
FIXME comment on custom defined contexts
FIXME comment on aliases
Some system binary, context SH
zoid> mplayer -vo sdl -ao sdl my_favorite_movie.avi
Perl code between brackets, context PERL
zoid> { print "This is perl code." }
A subroutine call to an object loaded in Zoidberg, context PERL but with a little source filtering applied.
zoid> ->Help->help -or- zoid> ->Help->help('objects')
A builtin command faking to be executable, context CMD
zoid> cd ..
A custom syntax (SQL) enforced on a block:
zoid> sql{ SELECT * FROM users WHERE clue > 0 }
And as said all of these can be combined:
zoid> cd /usr/local && { print "This is perl code." } | less || sql{SELECT * FROM users WHERE clue > 0}
This will first execute cd /usr/local, on succes followed by { print "This is perl code." } | less and if one of these failed we get to see the result of sql{SELECT * FROM users WHERE clue > 0}
cd /usr/local
{ print "This is perl code." } | less
sql{SELECT * FROM users WHERE clue > 0}
This makes the precedence of this example as follows.
( ( 1 and ( 2 pipe 3 ) ) or 4 ) 1 = cd /usr/local 2 = { print "This is perl code." } 3 = less 4 = sql{SELECT * FROM users WHERE clue > 0}
(random notes that probably belong elsewhere in this document)
Files starting with a '-' are ignored in globs unless the glob starts with a '-', this is to prevent globs from accidentally adding switches to a command.
perl(1), zoiddevel(1), zoidfaq(1), http://zoidberg.sourceforge.net
To install Zoidberg, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Zoidberg
CPAN shell
perl -MCPAN -e shell install Zoidberg
For more information on module installation, please visit the detailed CPAN module installation guide.