ZOIDUSER(1)           User Contributed Perl Documentation          ZOIDUSER(1)



NAME
       zoiduser - Extended user documentation for zoid

DESCRIPTION
   Configuration
       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".

       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'.

       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:

       FIXME tell which builtins are provided by each plugin FIXME tell
       commands provided by Zoidberg.pm

       Commands
           Ships a collection of standard builtin commands that one would
           expects to have in a shell.

           Provides: cd, pwd, exec, eval, source, true, false, newgrp, umask,
           read, wait, fg, bg, kill, jobs, set, export, setenv, unsetenv,
           alias, unalias, dirs, popd, pushd and symbols

       Log Keeps a history of your doings.

       Intel
           Takes care of tab expansion.

           Provides: complete

       ReadLine
           Tries to load a module from the Term::ReadLine family of modules.

           Provides: readline, readmore and select

       CPAN
           Adds a 'CPAN mode' which uses CPAN::Shell.

       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
       Key bindings depend on the ReadLine module that is loaded. See for
       example Term::ReadLine::Zoid.

   Settings
       The following settings supported by (some) Zoidberg modules.  They are
       housed in the hash "->{settings}".  Also the builtin "set" command acts
       on this hash.

       ( FIXME link to doc on set command )

       More advanced settings can be found in zoiddevel.

       noglob
           Disable path expansion for shell-like syntax.

       nocaseglob
           When set makes globs case insensitive.

       nullglob
           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.

       voidbraces
           Do brace expansion posix compliant instead of bash compatible. This
           means that braces will be removed even if there is just one word
           between them.

       hide_private_method
           Hide all object methods and data structures which have a name
           starting with an '_' unless they are asked for explicitly.

       hide_hidden_files
           Hide all filesystem nodes which have a name starting with a '.'
           unless they are asked for explicitly.

       ignoreeof
           When this setting is in effect a ^D char, also known as EOF or EOT,
           won't exit the shell.

       naked_zoid
           Don't hide the root object behind clothes for things like tab
           completion and the single arrow operator, but show it in full
           glory.

       notify
           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.

       notify_verbose
           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.

   Syntax
       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:

       Logical grouping
           First the syntax is split into blocks with logical/script
           delimiters

                   [block] && [block] || [block] ; [block]

       Pipes and redirections
           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]

           The exit status of a pipeline is the exit status of the last
           command in the pipeline.

       Context blocks
           At last for each of these sub-blocks a context is decided like:

                   CMD     - commands sytax (like sh syntax)
                   PERL    - blocks of perl code

           Each is executed differently by a suitable subroutine or
           application, and all are glued together to form a pipeline.

   Contexts
       The contexts named below are hardcoded, others can be added by plugins.
       To disable hardcoded contexts see the _no_hardcoded_context setting.

       PERL
           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 parenthesis 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}"

                   # 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 parenthesis
                   zoid$ ls(qw/-al/)

                   # perl because of curlies
                   zoid$ { open TEST, '<test.dat' }

           Perl code can have modifiers after the last curly. The default can
           be set with "->{settings}{perl}{opts}". 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
                   Z: no strict, 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->".

                   # Thus
                   zoid$ ->kill('1230')

                   # is the same as
                   zoid$ $self->kill('1230')

           Variables in that match the name of an environment variable get
           translated to the environment varriable, arrays cause a tied array
           to be imported from Env. You can manipulate the existence of an
           environment variable with the 'export' builtin.

                   # Thus
                   zoid$ print $PATH

                   # is (if $ENV{PATH} exists) the same as
                   zoid$ print $ENV{PATH}

                   # and this also works
                   zoid$ push @PATH, '/usr/X11R6/bin/'

           To avoid source filtering use the 'z' option.  ( Although once a
           tied array is imported, it's there. )

           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}.

       CMD 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 or built-in 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

           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. (The
           exception to this rule is syntax like "export var='val'".)  Also be
           aware that within single quotes the backslash is still recognised
           as an escape, but only for the quote itself, the same way perl
           does.

           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.

                   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

           If the command matches an entry in the $$shell{commands} hash, it
           is taken to be a built-in command and the job is not forked to a
           seperate process.

       FIXME

       FIXME comment on custom defined contexts

       FIXME comment on aliases

       variables

       Like most shells zoid mixes the use of it's own variables with the use
       of environment variables. You can use the "export" builtin to move
       variables from the perl namespace to the environment.

       mode

       While in normal use zoid tries to determine which context a statement
       belongs to automaticly there are also situations in which you want to
       force one context for all commands. In these cases you can set the
       'mode' of the shell. The "mode" builtin is provided to do this a little
       more intelligent.

       For example the CPAN plugin provides an interactive interface to the
       CPAN::Shell module.

               # enter cpan mode
               zoid$ mode cpan
               zoid$ i /Zoidberg/
               # use a "normal" shell command
               zoid$ !df -h /
               zoid$ install Bundle::Zoidberg
               # return to the "normal" mode
               zoid$ mode -

       Modes can be either the name of a custom context (probably defined by a
       plugin), or the name of a perl module (matching a '::').  If the mode
       is a module name all commands are mapped to methods in that namespace;
       in this case you can postfix the module name with '->' if the module
       expects the class name as first argument to all calls.

               # set mode the hard way
               zoid$ mode CPAN::Shell->
               zoid$ i /Zoidberg/
               zoid$ mode -

       Examples

       Some system command:

               zoid$ mplayer -vo sdl -ao sdl my_favorite_movie.avi

       Perl code between brackets:

               zoid$ { print "This is perl code." }

       A subroutine call to an object loaded in Zoidberg, perl code with a
       little source filtering:

               zoid$ ->Help->help
                -or-
               zoid$ ->Help->help('objects')

       A builtin command:

               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}"

       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}

   Notes
       (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.

ENVIRONMENT
       The variables $PWD, $HOME and $USER are set to default values if not
       yet set by the parent process.

       The variable $ZOID will point to the location of the zoid executable,
       it is similar to $SHELL for POSIX compliant shells. zoid uses a differ-
       ent variable because some programs seem to expect $SHELL to point to a
       POSIX compliant shell.

       To switch off ansi colours on the terminal set $CLICOLOR to 0 (null).

       The variable $RS (record seperator) is used to split lines when
       capturing ouput from a command in list context.  It defaults to the
       newline character.

       The variable $IFS (input field seperators) is used to split words after
       several expansions. It defaults to "<space><tab><return>".

       This list probably isn't complete.

FILES
       Zoidberg uses rc files, data files and plugin files, use the --config
       switch to check the search paths used.

       Which rcfiles are loaded is controlled be the 'rcfiles' and 'norc' set-
       tings, try "zoid -o norc" to skip all rcfiles or "zoid -o
       rcfiles=file1:file2:file3" to use files other then the default.

       The runtime search path for plugins etc. can be controlled with the
       'data_dirs' setting, try "zoid -o data_dirs=dir1:dir2:dir3".

SEE ALSO
       zoidbuiltins(1), zoiddevel(1), zoidfaq(1), perl(1),
       <http://zoidberg.sourceforge.net>



perl v5.12.2                      2006-02-11                       ZOIDUSER(1)
