package Text::Wigwam::Library::System;

    use strict;
    use warnings;
    our $VERSION = '0.01';

    use base q/Exporter/;

    use Text::Wigwam::Const qw/ STRING ARRAY /;

    our %EXPORT_TAGS = (
        all => [
          qw/
            _proto_escape_var  _escape_var
            _proto_get_options _get_options
            _proto_module      _module
            _proto_plugin      _plugin
          /
        ],
        escape_var   => [ qw/ _proto_escape_var  _escape_var / ],
        get_options  => [ qw/ _proto_get_options _get_options / ],
        module       => [ qw/ _proto_module      _module / ],
        plugin       => [ qw/ _proto_plugin      _plugin / ],
    );
    our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
    our @EXPORT = qw( );

=head1 Name

Text::Wigwam::Library::System - A Wigwam directive library.

=head1 Description

This library provides directives which are useful for performing system
related functions.

=head1 Usage

The directives within this library can be imported into specific branches of
the directive tree (which transcends from  C<Text::Wigwam::Directives>) via
plug-ins or modules using one of the following techniques.

 package Text::Wigwam::Directives::some::arbitrary::branch;
 # import everything
 use Text::Wigwam::Library::System qw/:all/;

 package Text::Wigwam::Directives::another::arbitrary::branch;
 # import selectively
 use Text::Wigwam::Library::System qw / :escape_var :get_options :module /;

=head1 Directives

=cut

sub _proto_module { [ ARRAY ] }
sub _module {
    my $err = $_[0]->load_modules( @{$_[0]->get_arg} );
    $_[0]->exception( $err ) if $err;
    return;
}

=head2 #module I<list>

Loads a list of modules specified by I<string>, or throws an exception if any
of the specified modules fail to load. The recommended method for loading
modules is via the L<configuration tag|Text::Wigwam#configuration_tag>,
however this directive is provided for those instances where modules are to be
loaded conditionally.

 [!!
  /* Find and load modules Foo and Bar from within the module path */
  #if foobar {
   #try #module ( 'Foo' 'Bar' )
   #catch #throw "Failed to load required modules" /* custom error msg */
  }
 !!]

=cut

sub _proto_plugin { [ ARRAY ] }
sub _plugin {
    my $err = $_[0]->load_plugins( @{$_[0]->get_arg} );
    $_[0]->exception( $err ) if $err;
    return;
}


sub _proto_get_options { [ ] }
sub _get_options { return { $_[0]->get_options } }

=head2 #get_options

Returns a copy of the configuration options hash.

 [!!
  #define options #get_options
  "The current parsing engine is: " options.engine
 !!]

=cut

sub _proto_escape_var { [ STRING|ARRAY ] }
sub _escape_var {
    my ($Api) = @_;
    my $arg = $Api->get_arg;
    return $Api->escape_var( $arg )
      if $Api->is_string( $arg );
    my $arr = [];
    push( @$arr, $Api->escape_var($_) ) for (@$arg);
    return $arr;
}

=head2 #escape_var I<var>

Returns a copy of I<var> with any meta characters escaped so that it may be
used to access variables that contain meta characters. This is typically used
when dealing with hash keys which are then used to look up values.

 [!!
  #define hashvar %(  'silly.key' 'silly' '[wacky]key' 'wacky!' )
  #foreach key #keys hashvar {
   #define ekey #escape_var key
  !!>
   Pair: [!! key !!] = [!! hashvar.[ekey] !!]
  <!~
  }
  /* output:
   Pair: silly.key = silly
   Pair: [wacky]key = wacky!
  */
 !!]

=cut

1;
