view release on metacpan or  search on metacpan

lib/Fry/Shell.pm  view on Meta::CPAN

	$sh->shell(@ARGV);

	####end of example, start of other possible methods 

	#run shell once
	$sh->once(@ARGV);

	#loads libraries and runs each library's &_initLib 
	$sh->initLibs(@modules);

	$sh->loadFile($file);

	$sh->loadPlugins($myplugin);

	$sh->runCmd($cmd);

=head1 VERSION	

This document describes version 0.15.

=head1 DESCRIPTION 

Fry::Shell is a simple and flexible way to create a shell.  Unlike most other
light-weight shells, this module facilitates (un)loading libraries of
functions and thus encourages creating shells tailored to several modules.
Although the shell is currently only viewable at the commandline, the
framework is flexible enough to support other views (especially a web one :).
This module is mainly serving(will serve) as the model in an MVC framework.

From a user perspective it helps to know that a shell session consists of mainly four shell
components (whose classes are known as core classes) :
libraries (lib), commands (cmd), options (opt) and variables(var). Commands and options are the same
as in any shell environment: a command mapping to a function and an option changing the behavior of
a command ie changing variables within it or calling functions before the command. Variables
store all the configurable data, including data relating to these commands and options. Libraries
are containers for a related group of these components.

=head2 FEATURES

Here's a quick rundown of Fry::Shell's features:

	- Loading/unloading shell components at runtime.
	- Flexible framework for using shell features via plugins.	 
		You can even set up a bare minimum shell needing no external modules! Currently
		plugins exist for dumping data,readline support,reading shell configurations and
		viewing shell output. 
	- Commands and options can be aliased for minimal typing at the commandline.
	- Commands can have help and usage defined. 
	- Commands can have user-defined argument types. 
		One defines argument types by subroutines or tests that they should pass.
		These tests are then applied to a command's defined argument(s).
		With defined argument types, one can also define autocompletion
		routines for a command's arguments.
	- Options can modify variables.
		Since variables exist for almost every aspect of the shell, options
		can change many core shell functions. A handy example is 'parsecmd'
		which names the current parse subroutine for the current line.
		Changing this var would change how the input after the options is
		parsed.
	- Options can have different behaviors defined including the ability to invoke
		subroutines when called or to maintain a value for a specified amount of iterations. 
	- Default options include 'menu' which numbers output and allows the next command to
	reference them by number.
	- Page output with preferred pager.
	- Multiline mode.
	- Comes with a decent default library,Fry::Lib::Default, to dump,list or
		unload any shell component, run system commands,evaluate perl statements
		and execute methods of autoloaded libraries.

=head2 NOTE

Although this code is decently tested and is apparently unbuggy, I
consider it alpha until a few design issues have been solved. 

Oh yeah, some abbreviations I use often in these modules, especially in naming
subroutines:
cmd- command, lib- library,opt- option,var-variable, gen- general, attr- attribute .


=head1 Introduction

=head2 Setup

The two main ways to start a shell are via &shell and &once.
&once only runs once and useful for a noninteractive environment ie a shell script.
To set up &once :

	my $sh = Fry::Shell->new(prompt=>$prompt);
	$sh->once(@ARGV);

To set up &shell:

	my $sh = Fry::Shell->new(prompt=>$prompt);
	$sh->shell(@ARGV);

=head2 SYNOPSIS Explained

What can you do in your shell? Run any subroutines which you define as commands (or even better
commands defined by libraries). Even if your subroutines are not defined
they can still be executed by typing the subroutine's name. In SYNOPSIS above, &evalIt is such a
subroutine.

Looking at &evalIt's innards, you see that the first argument is $cls which is the class that calls
commands. You also see ' $cls->Flag("strict") ' which is a boolean flag to prepend a 'use strict' to
the evaluated code. Since we defined an option as type flag when initializing the shell, we change
the flag's value when we flip the option from the commandline (ie '-n evalIt $ref = "woah"; $foo =
"ref"; print $$foo').

&listStations is a cool example of the menu option. You'll need to have a music player that can
be executed via a system call, most likely a *nix environment, and that can play shoutcast radio stations (ie xmms).
Without any options, this command simply prints a list of stations. If you use the menu option (ie
'-m lS'), the next input line is parsed differently with numbers being substituted with
corresponding positions from the variable lines. For example,'! xmms 2', would call xmms with the 2nd radio
station in the variable lines. The &saveArray call is what passed the list of ip's to the variable lines.

=head2 Using Options

By default, options come before commands. You can change this behavior by redefining &parseLine.
An option begins with a '-'. You can specify an option's alias or full name. To set
an option's value put a '=' and the option value after it ie '-menu=1'.
If no '=' comes after an option name then the option is treated as a flag and set to 1 (ie the