NAME

Sub::Starter - Creates a skeletal framework for Perl sub's.

VERSION

This document refers to Sub::Starter version v1.0.3

SYNOPSIS

use Sub::Starter;

DESCRIPTION

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.

Usage Statements

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.

The following variables can be used for the parameters, including the optional ones, and the returns;

$scalar -- a scalar variable
@array -- an array variable or list
%hash -- a hash variable or list
\$scalar -- a reference to a scalar
\@array -- a reference to a array
\%hash -- a reference to a hash
\&code -- a reference to code
\*typeglob -- a reference to a typeglob

Usage statements are:

[ [ returns_alternate '|' ] returns_list assignment ] [ object '->' ] name [ '(' parameter_list [ ';' optional_parameters ] ')'? ] ';'?

The returns_alternate is a scalar.

The assignment is one of: =, .=, or +=

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.

Examples of usage statements

$text | @text = trim( @text );

\%options = $object->get_options( ; @option_names );

Templates

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:

The name directive

The name directive is replaced with the name of the sub. It has no arguments.

The usage directive

The usage directive is replaced with the usage statement. It has no arguments.

The parameters directive

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.

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.

The returns directive

This is used to list the returns. It takes the same arguments as the parameters directive.

In addition, it has the expression argument that creates an expression for a return statement.

The definitions directive

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.

Example of template: sub

# --------------------------------------
#       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;
}

Example of template: pod

=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

METHODS

new()

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.

Usage

$starter_sub = Sub::Starter->new( ; %attributes );

Parameters

%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.

-assignment

This is the value assign to the optional parameters when they are not present in the sub's call.

-max_usage

This is the maximum length of a variable string used in the usage statement.

-max_variable

This is the maximum length of a variable string used internally within the sub.

-name

This is the name of the sub. It should be a valid Perl identifier.

-object

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.

-parameters

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

-usage: the name of the variable as it appears in the usage statement.

-variable: the name of the variable as it appears inside the sub.

-optional: whether the parameter is optional.

-returns_alternate

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.

-returns

This is a list of hashes describing the returns. They are described the same way as the parameters except they cannot be optional.

Returns

$starter_sub: This is the new object blessed to the Sub::Starter class.

configure()

This method can set one or more of the attributes.

Usage

$starter_sub->configure( %attributes );

Parameters

%attributes: Same as in the new() method.

Returns

(none)

get_attributes()

Get tone or more attributes.

Usage

%attributes = $starter_sub->get_attributes( ; @attribute_names );

Parameters

@attribute_names: An optional list of attribute names. If the list is empty, all attributes are returned.

Returns

%attributes: A hash of the requested attributes and their values.

parse_usage()

Parse an usage statement. See "Usage Statements".

Usage

$sub_starter->parse_usage( $usage_statement );

Parameters

$usage_statement: A string showing how the sub is to be used.

Returns

(none)

fill_out()

Fill out a template. See Templates for details on creating one.

Usage

$text = $sub_starter->fill_out( \@template );

Parameters

\@template: The template with one line per element of the array.

Returns

$text: The text created from the template.

DIAGNOSTICS

(none)

CONFIGURATION AND ENVIRONMENT

(none)

INCOMPATIBILITIES

(none)

BUGS AND LIMITATIONS

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.

SUPPORT

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

ORIGINAL AUTHOR

Shawn H Corey <SHCOREY at cpan.org>

Contributing Authors

(Insert your name here if you modified this program or its documentation. Do not remove this comment.)

ACKNOWLEDGEMENTS

jethro at perlmonks.org for brainstroming its name.

COPYRIGHT & LICENCES

Software Licence

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

Document Licence

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

Usage Statements

Examples of usage statements

Templates

Example of template: sub

Example of template: pod

METHODS

new()

Usage

Parameters

Returns

configure()

Usage

Parameters

Returns

get_attributes()

Usage

Parameters

Returns

parse_usage()

Usage

Parameters

Returns

fill_out()

Usage

Parameters

Returns

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

INCOMPATIBILITIES

BUGS AND LIMITATIONS

SUPPORT

SEE ALSO

ORIGINAL AUTHOR

Contributing Authors

ACKNOWLEDGEMENTS

COPYRIGHT & LICENCES

Software Licence

Document Licence

Module Install Instructions