NAME

zoiddevel - Development documentation for zoid

DESCRIPTION

Debugging

If you switch on the global debug bit and the verbose bit both your input and debug information are echoed to STERR. Thus by piping both STDOUT and STDERR to a file you get a detailed log of what is happening.

To set both bits type:

 zoid> set debug
 zoid> set verbose

or start zoid with:

 $ zoid -vD

You can also get debug information from just one module by setting a global variable $DEBUG in the module's namespace.

If you set the debug variable to a number higher than 1, you get a stack trace of that number of frames for each exception thrown using the error() method.

Structure

On the website can be found a PDF document with a more detailed overview.

                 Zoidberg::Contractor ----- Zoidberg::Job::*
                     |
                     |
                  Zoidberg::Parser ----- Zoidberg::StringParser
                     | 
                     |  _____________ Zoidberg::Shell
                     | |
 zoid       ____  Zoidberg _____ Zoidberg::Eval
 executable       Engine
                     |
                     |
                     |___ {objects}  Plugins
                     |___ {contexts} Plugin defined contexts
                     |___ {settings} Options and config hashes
                     |___ {events}   DispatchTable with events
                     |___ {commands} DispatchTable with commands
                     |___ {aliases}  Alias definitions

FIXME some text explaning the desing in more details

Parse tree

This part describes the form of a parse tree as used between the various Zoidberg objects.

Example

 # Commandline input:
 
 $ ls -al | perl{ while (<STDIN>) { print $_ }  }abc && echo done
 
 # Would be parsed to:
 
 [ 
        [{context => 'SH'}, qw/ls -al/],
        [{context => 'PERL', opts => 'abc'}, q{ while (<STDIN>) { print $_ } } ],
        'AND',
        [{context => 'SH'}, qw/echo done/]
 ]
 
 
 
 # Commandline input:
 
 $ cd .. && ls -al ; cp dus ~/tmp/ &
 
 # Would be parsed to:
 
 [
        [{context => 'CMD'}, qw/cd ../],
        'AND',
        [{context => 'SH'}, qw/ls -al/],
        'EOS',  # End Of Statement
        [{context => 'SH'}, qw{cp dus ~/tmp/}],
        'BGS'   # BackGround Statement
 ]
  
 # FIXME an example with redirections

Basics

A parse tree is an array consisting of blocks and tokens. A block can be any kind of code and is stored in a nested array. Blocks directly following each other are supposed to be a pipeline. A token is a delimiter between blocks.

The first field of a block is a hash which contains information about the block, all other field in a block make up the content. The most important information about a block is the context, which tells the parser how to execute the block. You are free to store all kinds of specific information in this first field, but some key names are reserved.

FIXME reserved meta fields

Pseudo parse trees

These are forms that can be used with the shell() function provided by Zoidberg::Shell. Just as by the real parse tree blocks of code are references and tokens are plain scalars. A block that is a scalar reference will be parsed completely (although expected to be one block). A block that is a array referenc will be considered completely parsed if the first element is a hash reference, else it is considered a word list.

        # for example ls -al | perl{ while (<STDIN>) { print $_ }  }abc && echo done
        # can executed as :
        
        shell(
                [qw/ls -al/], 
                \'perl{ while (<STDIN>) { print $_ }  }abc', 
                'AND'
                [{context => 'SH'}, qw/echo done/]
        );

Using this kind of pseudo trees only makes sense if you are lazy or you don't know exactly what the command is but you have some clues.

FIXME explain which kind of (pseudo) parse tree fits in each of the Parser and Contractor routines

PluginConf

A plugin configuration file can use the following keys:

module

The class to bless the plugin object in.

config

Hash with plugin specific config stuff. For plugins that inherit from Zoidberg::Fish this will automaticly become the {config} attribute.

commands

Hash linking command names to subroutines.

FIXME link to dispatch string format

export

Array with commands automaticly linking to a subroutine of the same name in the plugin object.

events

Like commands but specifying events the plugin wants to have.

import

Like export but used for events.

ENVIRONMENT

The following environment variables are used be Zoidberg.

ZOIDPID

Contains the process id of the above zoid, intended to be used for an IPC mechanism.

ZOIDREF

This variable should contain a reference to the Zoidberg object currently in charge. This is mainly used for obtaining settings from the parent object behind non-OO interfaces (like builtin shell commands).

In (non-forked) child processes this variable contains a stringyfied version. The parent process will has a global hash %Zoidberg::Objects which uses these strings as keys to the original references. It is intended that an IPC mechanism should use this hash to convert strings back to references.

SEE ALSO

perl(1), http://zoidberg.sourceforge.net

cpanm Zoidberg

perl -MCPAN -e shell
install Zoidberg