=pod

=head1 Syntax guide for Zoidberg

Since the syntax of the Zoidberg shell is completely configable
we can only comment on the syntax as defined by the default
config files.

The general structure will be mostly the same for any configuration
but any markup or sign can be changed till the syntax is completely
un recognizable.

All this config can be found in the C<{grammar}> hash,
which is by default stored in the F<grammar.pd> file.

=head2 Default syntax parsing

The zoidberg syntax consists of three levels of grouping:

=over 4

=item B<Logical grouping>

First the syntax is split into blocks with logical/script delimitters

This can be signs:

C< [block] && [block] || [block] ; [block] >

Or words:

C< [block] AND [block] OR [block] EOS [block] >

These are exactly the same

=item B<Pipes and redirections>

Once the string is cut into logical blocks each
of these blocks is split in sub_blocks by pipes
and redirections

I<For now one can only use _copies_ of the zoidberg object tree in pipelines -- we hope to use threads for this in the future.>

C< [sub_block] | [sub_block] E<gt> [sub_block] >

=item B<context blocks>

At last for each sub_block the parsing rules in the grammar
decide a context like 'ZOID', 'PERL', 'SYSTEM' or 'SQL'

Now the parsing of each sub_block is handed to a suitable
subroutine.

Aliases are handled on this level but before deciding the
context - so it is possible to alias to context mark_up.

=back

=head2 examples

Some system binary -- context SYSTEM

C<zoidE<gt> mplayer -vo sdl -ao sdl my_favorite_movie.avi>

Perl code between brackets -- context PERL

C<zoidE<gt> { print "This is perl code."; }>

A subroutine call to a object loaded in zoidberg

C<zoidE<gt> -E<gt>Help-E<gt>help>
 -or-
C<zoidE<gt> -E<gt>Help-E<gt>help('objects')>

A zoidberg command preceded by an underscore

C<zoidE<gt> _cd /usr/local>
C<zoidE<gt> _back>

And as described above all of these can be combined:

C<zoidE<gt> _cd /usr/local AND { print "This is perl code."; } | less || sql{SELECT * FROM users WHERE clue E<gt> 0}>

This will first execute C<_cd /usr/local>
on sucess followed by C<{ print "This is perl code."; } | less>
If one of these failes we got to see the result of C<sql{SELECT * FROM users WHERE clue E<gt> 0}>

The hierarchy is thus: I< ( ( 1 && ( 2 | 3 ) ) || 4 )>
Where 1 = C<_cd /usr/local>, 2 = C<{ print "This is perl code."; }>, 3 = C<less>
and 4 = C<sql{SELECT * FROM users WHERE clue E<gt> 0}>

=cut