The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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
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
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)

SEE ALSO

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

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

The PerlMonks http://perlmonks.org/ for brainstroming the name.

COPYRIGHT & LICENCES

Copyright 2009 by Shawn H Corey. All rights reserved.

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