NAME

substarter - Starts a sub from a usage statement formatted from a template.

VERSION

This document refers to substarter version v1.0.2

USAGE

substarter [<options>] [<file>] ...
substarter --usage|help|version|man

REQUIRED ARGUMENTS

(none)

OPTIONS

--commandline: Read the usage statements from command line, one per argument.
--displays=<template>: Display the sub's in the template. This option may be repeat for more than one template. Default is 'sub' template.
--templatefiles=<file>: Read the templates from the file. This option may be repeat for more than one file. Templates in the files that appear first, override those in later files. The default template files are still read. See Templates for details.
--usage: Print a brief usage message.
--help: Print usage, required arguments, and options.
--version: Print the version number.
--man: Print the manual page.

DESCRIPTION

This script creates the skeleton of a Perl sub from a usage statement, formatted from a template.

A usage statement is not valid Perl code. This is because it is difficult to distinguish a scalar and a reference. Instead, parameters and returns that are references are written with the take-a-reference-to notation. For example, a reference to an array is written as \@array. See EXAMPLES for details.

Templates

Templates are read from templates files. First, any template files given via the command-line option, --templatefiles are scanned. Then, the file ~/.substarterrc is scanned, if it exists. Then, the file /etc/substarterrc is scanned, if it exists. Then, internal templates are scanned.

Templates that appear first in the scan order override those that appear later.

The internal templates are for usage, sub, and pod.

See Sub::Starter for details on how to write a template.

REQUIREMENTS

Sub::Starter

FILES

/etc/substarterrc: System-wide template file used for overriding the internal templates. See Sub::Starter for details on how to write a template.
~/.substarterrc: Personal template file used for overriding the system-wide templates and internal templates. See Sub::Starter for details on how to write a template.

EXAMPLES

trim()

usage

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

sub

# --------------------------------------
#       Name: trim
#      Usage: $text | @text = trim( @text );
#    Purpose: TBD
# Parameters: @text -- TBD
#    Returns: $text -- TBD
#             @text -- TBD
#
sub trim {
  my @text = @_;
  my $text = '';

  return wantarray ? @text : $text;
}

pod

=head2 trim

=head3 Usage

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

=head3 Parameters

=over 4

=item @text

TBD

=back

=head3 Returns

=over 4

=item $text

TBD

=item @text

TBD

=back

$object->get_options()

usage

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

sub

# --------------------------------------
#       Name: get_options
#      Usage: \%options = $object->get_options( ; @option_names );
#    Purpose: TBD
# Parameters: @option_names -- TBD
#    Returns:     \%options -- TBD
#
sub get_options {
  my $self         = shift @_;
  my @option_names = @_;
  my $options      = {};

  return $options;
}

pod

=head2 get_options

=head3 Usage

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

=head3 Parameters

=over 4

=item @option_names

TBD

=back

=head3 Returns

=over 4

=item \%options

TBD

=back

baselines()

usage

@y_values = baselines( $height, $size; $spacing, $bottom );

sub

# --------------------------------------
#       Name: baselines
#      Usage: @y_values = baselines( $height, $size; $spacing, $bottom );
#    Purpose: TBD
# Parameters:   $height -- TBD
#                 $size -- TBD
#              $spacing -- TBD
#               $bottom -- TBD
#    Returns: @y_values -- TBD
#
sub baselines {
  my $height   = shift @_;
  my $size     = shift @_;
  my $spacing  = shift @_ || '';
  my $bottom   = shift @_ || '';
  my @y_values = ();

  return @y_values;
}

pod

=head2 baselines

=head3 Usage

  @y_values = baselines( $height, $size; $spacing, $bottom );

=head3 Parameters

=over 4

=item $height

TBD

=item $size

TBD

=item $spacing

TBD

=item $bottom

TBD

=back

=head3 Returns

=over 4

=item @y_values

TBD

=back

column_blocks()

usage

\@blocks = column_blocks( \@block, $columns; $gap );

sub

# --------------------------------------
#       Name: column_blocks
#      Usage: \@blocks = column_blocks( \@block, $columns; $gap );
#    Purpose: TBD
# Parameters:  \@block -- TBD
#             $columns -- TBD
#                 $gap -- TBD
#    Returns: \@blocks -- TBD
#
sub column_blocks {
  my $block   = shift @_;
  my $columns = shift @_;
  my $gap     = shift @_ || '';
  my $blocks  = [];

  return $blocks;
}

pod

=head2 column_blocks

=head3 Usage

  \@blocks = column_blocks( \@block, $columns; $gap );

=head3 Parameters

=over 4

=item \@block

TBD

=item $columns

TBD

=item $gap

TBD

=back

=head3 Returns

=over 4

=item \@blocks

TBD

=back

format_paragraph()

usage

( \@lines, \@mut ) = format_paragraph( \%paragraph_options, @mut );

sub

# --------------------------------------
#       Name: format_paragraph
#      Usage: ( \@lines, \@mut ) = format_paragraph( \%paragraph_options, @mut );
#    Purpose: TBD
# Parameters: \%paragraph_options -- TBD
#                            @mut -- TBD
#    Returns:             \@lines -- TBD
#                           \@mut -- TBD
#
sub format_paragraph {
  my $paragraph_options = shift @_;
  my @mut               = @_;
  my $lines             = [];
  my $mut               = [];

  return ( $lines, $mut );
}

pod

=head2 format_paragraph

=head3 Usage

  ( \@lines, \@mut ) = format_paragraph( \%paragraph_options, @mut );

=head3 Parameters

=over 4

=item \%paragraph_options

TBD

=item @mut

TBD

=back

=head3 Returns

=over 4

=item \@lines

TBD

=item \@mut

TBD

=back

print_lines()

usage

( \@y_values, \@lines ) = print_lines( $left, \@y_values, \@lines );

sub

# --------------------------------------
#       Name: print_lines
#      Usage: ( \@y_values, \@lines ) = print_lines( $left, \@y_values, \@lines );
#    Purpose: TBD
# Parameters:      $left -- TBD
#             \@y_values -- TBD
#                \@lines -- TBD
#    Returns: \@y_values -- TBD
#                \@lines -- TBD
#
sub print_lines {
  my $left     = shift @_;
  my $y_values = shift @_;
  my $lines    = shift @_;

  return ( $y_values, $lines );
}

pod

=head2 print_lines

=head3 Usage

  ( \@y_values, \@lines ) = print_lines( $left, \@y_values, \@lines );

=head3 Parameters

=over 4

=item $left

TBD

=item \@y_values

TBD

=item \@lines

TBD

=back

=head3 Returns

=over 4

=item \@y_values

TBD

=item \@lines

TBD

=back

print_paragraph()

usage

( $bottom, \@mut ) = print_paragraph( \%print_options, \%paragraph_options, @mut );

sub

# --------------------------------------
#       Name: print_paragraph
#      Usage: ( $bottom, \@mut ) = print_paragraph( \%print_options, \%paragraph_options, @mut );
#    Purpose: TBD
# Parameters:     \%print_options -- TBD
#             \%paragraph_options -- TBD
#                            @mut -- TBD
#    Returns:             $bottom -- TBD
#                           \@mut -- TBD
#
sub print_paragraph {
  my $print_options     = shift @_;
  my $paragraph_options = shift @_;
  my @mut               = @_;
  my $bottom            = '';
  my $mut               = [];

  return ( $bottom, $mut );
}

pod

=head2 print_paragraph

=head3 Usage

  ( $bottom, \@mut ) = print_paragraph( \%print_options, \%paragraph_options, @mut );

=head3 Parameters

=over 4

=item \%print_options

TBD

=item \%paragraph_options

TBD

=item @mut

TBD

=back

=head3 Returns

=over 4

=item $bottom

TBD

=item \@mut

TBD

=back

DIAGNOSTICS

(none)

CONFIGURATION AND ENVIRONMENT

(none)

INCOMPATIBILITIES

(none)

BUGS AND LIMITATIONS

(none known)

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

Andy Lester for suggesting module-starter aka Module::Starter.

The PerlMonks http://perlmonks.org/ for brainstroming the 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

USAGE

REQUIRED ARGUMENTS

OPTIONS

DESCRIPTION

Templates

REQUIREMENTS

FILES

EXAMPLES

trim()

$object->get_options()

baselines()

column_blocks()

format_paragraph()

print_lines()

print_paragraph()

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

INCOMPATIBILITIES

BUGS AND LIMITATIONS

SEE ALSO

ORIGINAL AUTHOR

Contributing Authors

ACKNOWLEDGEMENTS

COPYRIGHT & LICENCES

Software Licence

Document Licence

Module Install Instructions