Sub::Starter - Creates a skeletal framework for Perl sub's.
This document refers to Sub::Starter version v1.0.6
use Sub::Starter;
This module is for providing a simple and consist way of creating sub's. It provides methods for loading the interface to a sub and, using a template, output its skeleton. This skeleton can then be populate with code.
A usage statement shows how a sub will be used. It is used by the parse_usage() method. It is not valid Perl. It uses the make-a-reference-to notation for references. This is to give a clear indication of what the references is to.
parse_usage()
The following variables can be used for the parameters, including the optional ones, and the returns;
Usage statements are:
[ [ returns_alternate '|' ] returns_list assignment ] [ object '->' ] name [ '(' parameter_list [ ';' optional_parameters ] ')'? ] ';'?
The returns_alternate is a scalar.
returns_alternate
The assignment is one of: =, .=, or +=
assignment
=
.=
+=
The returns_list and the parameters_list must be a list of scalars and references except for the last element, which can be an array or hash. If the optional_parameters list is present, the parameters_list cannot end with an array or hash. Instead, the optional_parameters list can. These lists are variables separated by a comma.
returns_list
parameters_list
optional_parameters
$text | @text = trim( @text ); \%options = $object->get_options( ; @option_names );
Templates are used by the fill_out() method to determine how the output will look. They are array of lines. Each line may contain one, and only one, directive. Lines without directives are copied verbatim to the output. Some directives has arguments. Directive are distinguished by the sequence \e[1m( and ending with )\e[0m where \e means the ASCII ESCAPE character. The directives are:
fill_out()
\e[1m(
)\e[0m
\e
The name directive is replaced with the name of the sub. It has no arguments.
name
The usage directive is replaced with the usage statement. It has no arguments.
usage
This is used to list the parameters. It has one mandatory argument and one optional one. The mandatory argument tells how and how much to display. It can be are, arenot, each, first, rest, or list.
are
arenot
each
first
rest
list
If it is are then the line is outputted if there are some parameters. It can have an optional format argument (see below).
If it is arenot then the line is outputted if there are not any parameters. It can have an optional format argument (see below).
The list argument replaces the directive with a list of the parameters. The optional argument is the list separator. The default separator is a single space.
The each outputs the line for each item in the list. The first outputs the line for the first item in the list. The rest outputs the line for all but the first item in the list. If their list is empty, the line is not outputted. They have an optional argument that formats the variable in the output.
The format argument translate '\s', '\t', and '\n' into space, tab, and newline characters respectively. If it's part of a listing, it can have '%s', '%*s', or '%-*s' to determine how the item will be displayed. The '%s' will simply display it. This is the default. The '%*s' will display it, right-justified in a column wide enough for the widest item. The '%-*s' will display it, left-justified in a column wide enough for the widest item.
This is used to list the returns. It takes the same arguments as the parameters directive.
parameters
In addition, it has the expression argument that creates an expression for a return statement.
expression
The definitions directive will output all the parameters and returns, one per line with a Perl assignment. It has an optional format which may be '%s\s=\s%s', '%*s\s=%s', or '%-*s\s=\s%s'. The first is the default. The second right-justifies the variable. The last left-justifies it.
# -------------------------------------- # Name: \e[1m(name)\e[0m # Usage: \e[1m(usage)\e[0m # Purpose: TBD # Parameters: (none)\e[1m(parameters arenot)\e[0m # Parameters: \e[1m(parameters first %*s)\e[0m -- TBD # \e[1m(parameters rest %*s)\e[0m -- TBD # Returns: (none)\e[1m(returns arenot)\e[0m # Returns: \e[1m(returns first %*s)\e[0m -- TBD # \e[1m(returns rest %*s)\e[0m -- TBD # sub \e[1m(name)\e[0m { my \e[1m(definitions %-*s\s=\s%s)\e[0m; return\e[1m(returns expression)\e[0m; }
=head2 \e[1m(name)\e[0m() TBD =head3 Usage \e[1m(usage)\e[0m =head3 Parameters (none)\e[1m(parameters arenot)\e[0m =over 4\e[1m(parameters are \n)\e[0m =item \e[1m(parameters each %s\n\nTBD\n)\e[0m =back\e[1m(parameters are)\e[0m =head3 Returns (none)\e[1m(returns arenot)\e[0m =over 4\e[1m(returns are \n)\e[0m =item \e[1m(returns each %s\n\nTBD\n)\e[0m =back\e[1m(returns are)\e[0m
Create a new sub starter object. This object is populated with default variables for its attributes. These should be changed before any output is attempted.
$starter_sub = Sub::Starter->new( ; %attributes );
All this module's attributes start with a minus sign or a space. Those that start with a minus sign are part of its API. Those that start with a space are for internal storage and should not be changed.
If the application needs to store information in the object, start the key with an alphanumeric character. If a derived class needs an attribute, start it with two minus signs.
This is the value assign to the optional parameters when they are not present in the sub's call.
This is the maximum length of a variable string used in the usage statement.
This is the maximum length of a variable string used internally within the sub.
This is the name of the sub. It should be a valid Perl identifier.
This is the name of the object for the sub if it's a method. It should be a scalar, as $object, or a module, as Sub::Scalar.
$object
Sub::Scalar
This is a list of hashes describing the parameters. Each has a:
-type: scalar, array, hash, scalar_ref, array_ref, hash_ref, code_ref, or typeglob
-type
scalar
array
hash
scalar_ref
array_ref
hash_ref
code_ref
typeglob
-usage: the name of the variable as it appears in the usage statement.
-usage
-variable: the name of the variable as it appears inside the sub.
-variable
-optional: whether the parameter is optional.
-optional
This is a reference to a hash describing the alternate return. It should be a scalar and is described the same way as the parameters except it cannot be optional. If it is, then this attribute is the null string.
This is a list of hashes describing the returns. They are described the same way as the parameters except they cannot be optional.
This is the new object blessed to the Sub::Starter class.
Sub::Starter
This method can set one or more of the attributes.
$starter_sub->configure( %attributes );
Same as in the new() method.
(none)
Get tone or more attributes.
%attributes = $starter_sub->get_attributes( ; @attribute_names );
An optional list of attribute names. If the list is empty, all attributes are returned.
A hash of the requested attributes and their values.
Parse an usage statement. See "Usage Statements".
$sub_starter->parse_usage( $usage_statement );
A string showing how the sub is to be used.
Fill out a template. See Templates for details on creating one.
$text = $sub_starter->fill_out( \@template );
The template with one line per element of the array.
The text created from the template.
Please report any bugs or feature requests to bug-Sub::Starter at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub::Starter. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-Sub::Starter at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Sub::Starter
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sub-Starter
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Sub-Starter
CPAN Ratings
http://cpanratings.perl.org/d/Sub-Starter
Search CPAN
http://search.cpan.org/dist/Sub-Starter
Shawn H Corey <SHCOREY at cpan.org>
<SHCOREY at cpan.org>
(Insert your name here if you modified this program or its documentation. Do not remove this comment.)
jethro at perlmonks.org for brainstroming its name.
Copyright 2009 by Shawn H Corey. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being ORIGINAL AUTHOR, COPYRIGHT & LICENCES, Software Licence, and Document Licence.
You should have received a copy of the GNU Free Documentation Licence along with this document; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
To install Sub::Starter, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Sub::Starter
CPAN shell
perl -MCPAN -e shell install Sub::Starter
For more information on module installation, please visit the detailed CPAN module installation guide.