Changeset 2539

Timestamp:

Nov 30, 2004, 12:27:21 PM (22 years ago)

Author:

jhoblitt

Message:

add subroutine prototypes and Params::Validate

File:

• trunk/doc/misc/perlCodeConventions.tex (modified) (3 diffs)

trunk/doc/misc/perlCodeConventions.tex

@@ -1 @@
-%%% $Id: perlCodeConventions.tex,v 1.38 2004-11-25 03:39:17 jhoblitt Exp $
+%%% $Id: perlCodeConventions.tex,v 1.39 2004-11-30 22:27:21 jhoblitt Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -1180 +1180 @@
 \end{verbatim}
 
+\subsubsection{Subroutine Prototypes}
+
+Do not use subroutine prototypes.  If you need to validate subroutine
+parameters see \code{Params::Validate} (\S\ref{Params::Validate}).
+
+\begin{verbatim}
+    sub myopen (*;$)                    # AVOID!
+\end{verbatim}
+
+
 %------------------------------------------------------------------------------
 \appendix                               %Begin Appendices
@@ -1211 +1221 @@
 \verbatiminput{.perltidyrc}
 
+\section{Params::Validate}
+\label{Params::Validate} 
+
+\code{Params::Validate}\footnote{Params::Validate -
+http://search.cpan.org/~drolsky/Params-Validate/} is a Perl module that allows
+you to perform rigorous subroutine parameter validation.  It is highly
+configurable and validation may be deactivated at runtime
+
+The basic premise is that a validation specification is passed to one of
+several ``validating'' subroutines along with the parameters the subroutine was
+called with.
+
+An example \code{Params::Validate} named parameters validation spec taken from
+the \code{DateTime} module.
+
+\begin{verbatim}
+    my $BasicValidate =
+        { year   => { type => SCALAR },
+          month  => { type => SCALAR, default => 1,
+                      callbacks =>
+                      { 'is between 1 and 12' =>
+                        sub { $_[0] >= 1 && $_[0] <= 12 }
+                      },
+                    },
+          day    => { type => SCALAR, default => 1,
+                      callbacks =>
+                      { 'is a possible valid day of month' =>
+                        sub { $_[0] >= 1 && $_[0] <= 31 }
+                      },
+                    },
+          hour   => { type => SCALAR, default => 0,
+                      callbacks =>
+                      { 'is between 0 and 23' =>
+                        sub { $_[0] >= 0 && $_[0] <= 23 },
+                      },
+                    },
+          minute => { type => SCALAR, default => 0,
+                      callbacks =>
+                      { 'is between 0 and 59' =>
+                        sub { $_[0] >= 0 && $_[0] <= 59 },
+                      },
+                    },
+          second => { type => SCALAR, default => 0,
+                      callbacks =>
+                      { 'is between 0 and 61' =>
+                        sub { $_[0] >= 0 && $_[0] <= 61 },
+                      },
+                    },
+          nanosecond => { type => SCALAR, default => 0,
+                          callbacks =>
+                          { 'cannot be negative' =>
+                            sub { $_[0] >= 0 },
+                          }
+                        },
+          locale    => { type => SCALAR | OBJECT,
+                         default => undef },
+          language  => { type => SCALAR | OBJECT,
+                         optional => 1 },
+        };
+\end{verbatim}
+
+An example of how a validation spec is used in the \code{DateTime} module.
+
+\begin{verbatim}
+    use Params::Validate qw( validate validate_pos SCALAR BOOLEAN HASHREF OBJECT );
+    .
+    .
+
+    sub new
+        {
+            my $class = shift;
+            my %p = validate( @_, $NewValidate );
+    .
+    .
+\end{verbatim}
+
+Please see the \code{Params::Validate} Pod\footnote{Params::Validate Pod -
+http://search.cpan.org/~drolsky/Params-Validate/lib/Params/Validate.pm} for
+further details.
+
 \bibliographystyle{plain}
 \bibliography{panstarrs}