/ 
Zoidberg-0.42
River stage zero No dependents
/ zoiddevel

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

class diagram

Zoidberg::Shell
      /|\            Zoidberg::Contractor
       |                 /|\   /|\
       |__________________|     |
            |                   |
            |            Zoidberg::Job
         Zoidberg              /|\
                                |
                                |
                         Zoidberg::Job::Builtin

All other classes stand on their own (except perhaps for some internal helper classes).

Zoidberg::Shell is an interface class to be used in perl scripts like zoidrc. Zoidberg inheriting from it in order to make this interface also available through the $shell object in the eval scope.

The Zoidberg::Contractor class contains the code to manage Jobs. Because the Job class also inherits from it sub-jobs are possible.

object structure

main object  class Zoidberg
  |
  |___ {eval}          Zoidberg::Eval object
  |___ {stringparser}  Zoidberg::StringParser object
  |
  |___ {jobs}          Array with Job objects
  |      |_ items of class Zoidberg::Job
  |
  |___ {settings}      Settings and config hashes
  |___ {objects}       Plugin objects       - tied Zoidberg::PluginHash
  |___ {contexts}      Custom contexts      - tied Zoidberg::DispatchTable
  |___ {events}        Event code refs      - tied Zoidberg::DispatchTable
  |___ {commands}      Command code refs    - tied Zoidberg::DispatchTable
  |___ {aliases}       Alias definitions

FIXME explanation

State diagram

TODO

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 split into words and parsed completely (although still expected to be one block). A block that is an array reference will be considered to be completely parsed if the first element is a hash reference and the context defined, else it is considered a word list, possibly with meta data defined in the first element.

# for example "ls -al | perl{ while (<STDIN>) { print $_ }  }abc && echo done"
# can be executed by calling :
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.

Settings

These are advanced settings only needed for development. Common settings can be found in zoiduser.

_no_redirection

Disable builtin parsing for redirections. Probably needed if you want to do this yourself.

_no_env

Disable builtin parsing for local environment settings. Probably needed if you want to do this yourself.

_no_hardcoded_context

Disable hard-coded contexts like PERL, SH and CMD. This might be useful to make for example a restricted shell.

debug

Turn on _all_ debug messages.

Events

The hash called 'events' in the main object is a tied hash of the class Zoidberg::DispatchTable. This hash contains code refs to be called when certain events happen, thus providing a hook mechanism.

Events of two types are used, first there is the 'broadcast' type in which case all code refs on the stack are called; second there is the 'call' type, in this case only the ref on top of the stack is called and it's return value is passed on to the caller.

broadcast events

FIXME more events

precmd

This event is called from the main loop just before respawning the input buffer. It can be used to update routines.

postcmd

This event is called after the spawning of every job. Like 'precmd' it can be used for update routines; since 'postcmd' is called much more often then 'precmd' use 'precmd' if it makes no difference, 'postcmd' should only be used for atomic stuff like updating $ENV{PATH}.

exit

Called just before round_up(), used as replacement for .bash_logout.

call events

Events of the 'call' type used by Zoidberg include:

get_input ($event, $broken)

This method is used to get (interactive) input, by default this event would be set by the Buffer plugin or an alternative input plugin. The boolean $broken signifies that the previous input wasn't complete and thus more input is requested.

FIXME where to find doc on input plugins with more details ?

PluginConf

A plugin configuration file can use the following keys:

module

The class to bless the plugin object in.

load_on_init

Boolean to force the plugin to be loaded during shell initialisation. By default plugins are loaded on first use to keep initialisation as fast as possible.

config

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

commands

Hash linking command names to subroutines. See Zoidberg::DispatchTable for the string format used in this hash.

export

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

events

Like commands but used for events.

import

Like export but used for events.

Custom contexts

Typically you'll want to set a custom context from a plugin. To do this you set the "load_on_init" setting in the "PluginConf" and then setup the context parser and handlers routines from the plugin's init() routine, using the add_context() method in Zoidberg::Fish.

A context config hash can contain the following routines:

wordlist BLOCK

FIXME

On wantarray should return a list of possible completions for the word in $$block[1]; else it should check whether the word is his and return true on success. In both cases it is also allowed to return a block ref, this is for the more advanced options.

intel BLOCK

FIXME

handler BLOCK

FIXME

filter BLOCK

FIXME

Be aware that the a block might be filtered twice with the same meta hash, the second time should reset any meta fields set by the first time.

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

1 POD Error

The following errors were encountered while parsing the POD:

Around line 321:

You forgot a '=back' before '=head1'