##
## This is the basic shell of a compatible engine. It attempts to demonstrate
## the manner in which the Wigwam common interface (Wigwam.pm) interacts with
## a compatible engine.
## 

# This is an example of what a compatible engine class might look like.

package Text::Wigwam::Engine::Shell;

use strict;
our $VERSION = '0.01';


# All compliant Wigwam engines are required inherit from the
# Text::Wigwam::Engine class. This allows for clean and generic engine
# detection and allows the common interface to handle alot of the common
# tasks such as data type detection, etc.

    our @ISA=qw(Text::Wigwam::Engine);

# Import Wigwam constants
use Text::Wigwam::Const qw(:all);

sub name { return 'Shell'; } # Returns the name of the engine

sub curr_addr{ return 0; }   # Returns a unique identifer for the current token (i.e. its address)
sub root_expr{ return $_[0]->{root_expr}; }     # Returns the current expression object (used by the debugger).

## The Engine base class does most of the work for us, including constructing
## an engine object.
##
## By the time the engine's init method is invoked, the template file has
## already been loaded and its configuration tag has already been parsed,
## converted into a hash, and removed from the template text.
##

sub init { # Creates an executable template object (root EXPR)
    my ($self, $template) = @_;
     # Do something with $template...while considering the config info stored in
     # $self->config->get qw/options/, $self->config->get qw/aliases/, etc...
    return Text::Wigwam::Engine::Shell::Expression->new();
}

# The following methods are also required by all engines.

sub get_arg { }   #    Executes the next argument
sub kill_arg { }  #    Skips the next argument

# All Wigwam engines must be able to detect the expressions of all other
# Wigwam engines, therefore it's most convenient to invoke the generalized
# versions of the following routines via the Engine base class as opposed to risking
# incompatibilities by overriding them with custom written versions.

#     $self->is_expr( $thing )
#     $self->is_list( $thing )
#     $self->is_hash( $thing )
#     $self->is_string( $thing ) 
#     $self->is_scalar( $thing )
#     $self->is_num( $string )


# The following is an example of what a compatible expression class might look like.

package Text::Wigwam::Engine::Shell::Expression;

# All compliant engines must generate expressions that inherit from the
# Text::Wigwam::Expression class. This allows for a clean and generic is_expr
# function.
    our @ISA=qw(Text::Wigwam::Expression);

# There are no restrictions or requirements pertaining to the expression
# constructor. It's presumed that the engine itself uses this constructor
# to generate expressions.
#
# ex. Text::Wigwam::Engine::Shell::Expression->new( $engine->doc, $size, %engine_specific_expression_data );

    sub new {
        my ($class, $doc, $size) = @_;
        return bless {
            doc => $doc,
            size => $size,
        }, $class;
    }

# The following method is the only one required by all compliant engine expressions.

     # Executes the expression and returns the result.
    sub execute {
        my $expr = shift;
         # insert expr execution code here.
    }

# Support for the following standard (semi-optional) methods brings us closer
# to a unified beautifier and show_me template. If any of the following are missing,
# the base class will handle them for you in some generic fashion.

     # Returns the name of the engine that generated the expression
    sub engine { return 'Shell'; }

     # Returns the number of tokens within the expression.
    sub size { return $_[0]->{size} }

     # Returns the template document where the expression was declared.
    sub doc { return $_[0]->{doc} }

     # Returns a beautified version of the expression's code. (optional)
    sub beautify {
        my $expr = shift;
         # Use the default beautifier defined in Wigwam.pm if none is passed in.
        my $beautifier = shift || Text::Wigwam::Beautify->new();
         # insert expr beautififcation code here.
    }

# The following represents an example for storing and retrieving comments while the expression's
# beautification data structure is being generated by the engine itself. These comments are later to be
# passed to the standard debugger's beautifier via its comment method.

    sub _add_comment{
        my ($expr, $err, $addr) = @_;
         # Note: addr is optional, in this example
        $expr->{comments}->{$addr || Text::Wigwam::Engine::Shell->curr_addr } = $err;
    }

     # This method is used by the engine itself to retrieve the comments
     # and pass them to the beautifier's 'comment' method just before
     # beautification process begins.

    sub _get_comments { return $_[0]->{comments} }

# Returning a code reference, rather than simply "1;", allows you to set default configuration settings,
# and run initialization code (if needed). It's executed whenever any template is initialized for use with
# this particular engine. The code reference is expected to return a hash reference upon execution, which
# should contain suggested default configuration settings.

return sub {
    return {
        shell_setting1 => 'x',
        shell_setting2 => 'y',
    }
};
