This is Info file pm.info, produced by Makeinfo version 1.68 from the
input file bigpm.texi.


File: pm.info,  Node: Parse/iPerl,  Next: Passwd/DB,  Prev: Parse/Yapp,  Up: Module List

engine for bringing any text documents alive with bits of embedded Perl
***********************************************************************

NAME
====

   Text::iPerl - engine for bringing any text documents alive with bits of
embedded Perl

SYNOPSIS
========

     use Text::iPerl;
     include 'documentname';

   or

     perl -MText::iPerl -e include <infile >outfile

   See `iperl' in this node for a far more comfortable command-line variant

DESCRIPTION
===========

   This is the engine of an inverse Perl interpreter, which controls
normal text with macro invocations and specially marked bits of Perl.
This setup of the document is always the same, though details may vary
according to the style in effect.  (See set_style.)  The engine is invoked
with include, or its variants include_filehandle and include_string.  It
treats a given document in two phases, with two or three aspects:

Markup Style
------------

   Bits of Perl to be evaluated have to be specially marked up as such.
How this is done differs greatly depending on the style in effect.  But
apart from different syntaxes there are only two fundamental ways in which
Perl can be embedded: non-printing and printing.  Not all styles provide
both ways.  The difference between these two ways is to be seen as
default-functionality and is not restrictive.  Non-printing Perl may very
well use the print statement, or system-commands to output something via
STDOUT into the output stream.  If system-commands are used you should
first turn on autoflushing (`$| = 1') to ensure that output order is
preserved.

Perl
----

   The whole document is actually reinverted or transformed into a
Perl-programme, where each bit of normal text gets transformed into a
semicolon-terminated Perl-statement.  The markup around bits of
non-printing Perl simply gets removed and a terminating semicolon added,
which almost never hurts.  If you want a bit of non-printing Perl to
control the preceding or following bit of normal text, you can prevent the
semicolon by starting or ending the Perl code with `\;'.  You can delimit
the bit of normal text with a bit of non-printing Perl containing only a
semicolon.

   Printing bits of Perl, on the other hand, get passed as an argument
list to a print statement, or to printf, if it starts with %.  If a
printing bit of Perl is empty, $_ is printed.  If it is a literal integer,
`$_[*n*]' is printed.

   There are several interesting things you can do with syntactically
incomplete bits of Perl.  You can seal the fate of the following bit of
plain text by preceding it with an expression followed by and or or and
terminated with `\;'.  Or you can have dangling curly braces of an
`if-elsif-else'-statement.  They might also be of a loop, which will likely
contain one or more printing bits of Perl.

   Dangling curly braces may even be of a sub, which will then print the
contained plain text when called.  Likewise they may be of an anonymous sub
which could be the second argument to define.

   There are no syntactic extensions to Perl, just a couple of variables
and functions like include or define.

Macros
------

   Normal text gets output as is, unless we have macro-definitions.  If
macros are defined, at runtime every bit of normal text gets repeatedly
scanned for macros, which are expanded until no more macro invocations are
found, i.e. macro expansions occur depth-first.  Macros are functions
returning a string.  If they also print something, that comes in the
output stream before the returned string and is not subject to repeated
scanning.  Scanning starts again where the last macro was found, so if a
macro returns what might be the second part of a macro name together with
the preceding text, that is not found.  (See define, undefine & macro.)

   Macro invocations consist of the macro name, a string of letters,
digits and underscores, optionally usually immediately followed by a
parenthesized Perl parameter list.  Note that even if the macro is
surrounded by a bit of Perl with a my-variable, that variable will not be
visible, since macro invocations are evaluated later, not seen at compile
time.  Depending on the style, macro invocations may be surrounded by
additional syntactic sugar.  (See $macro_start and friends.)

@EXPORT
=======

   Text::iPerl exports the following functions by default:

   include, include_string, include_filehandle, define, undefine, macro

@EXPORT_OK
----------

   Text::iPerl optionally exports the following function and variables:

   set_style, $cache, $comment_level, debug, %debug, $documents,
`@documents', $joiner, $macro_end, $macro_name_end, $macro_start,
$macro_start_dollar1, $max_macro_growth, $max_macro_expansions, $printfer,
%trace

FUNCTIONS
=========

debug WHEN, STRING
debug WHEN, CODEREF
define STRING, EXPR
define STRING
define
     Defines a macro whose value may be interpolated into bits of plain
     text in scalar context.  STRING or $_ should be a string consisting
     of letters, digits and underscores, which is the name of the macro.
     EXPR is the body of the macro.  If it is a reference to a function
     the macro interpolation will call that.  If it is a string-reference
     the macro is an alias to that macro or to that Perl-builtin, which
     doesn't allow a function reference to be taken.  If it is missing,
     the macro is a soft reference to a Perl-function of the same name.

     If the second argument is a string (should be single-quoted), its
     variables will be interpolated at the moment the macro gets called.
     The macro arguments may of course be accessed as `'... $_[0] ...
     $_[1] ...'', but there is a more comfortable possibility.  The first
     argument to define may contain parameter specifications in
     parentheses after the name.  These are a comma separated list of
     scalar variables with optionally a list variable at the end.  Each of
     these variables may be assigned to, giving the named parameter a
     default value.

     For styles like `cpp' which don't allow embedding Perl-expressions
     into the document, you can use any one of the following to get a
     Perl-evaluating macro:

          define PERL => '@_';
          define 'PERL( $eval = $_ )', '$eval';
          define PERL => sub { $_[0] };
          define PERL => sub { print $_[0]; '' };

     The first allows multiple arguments, to be separated by $".  The
     second gives a Perl-typical default argument of $_.  The third simply
     evaluates one argument.  The fourth does the same, but, the value
     being printed, it will not be reparsed for further macro-invocations.

include EXPR, *REPEATCOUNT*, *HUSH*
include EXPR, *REPEATCOUNT*
include EXPR
include
     Includes a document, parsing it as iPerl and merging the result into
     the current output.  EXPR works just like in open.  If no filename is
     given, reads from STDIN.  If filename is not a full path, then if
     called from within a known file, the file is searched in the
     directory of that document, else in the current directory.  If it is
     not found there, the directories in `@opt_I' followed by those in
     `@include' are searched, unless filename starts with `./'.

     The second argument may be an integer (often 1), meaning to include
     the file only if that filename hasn't already been included that many
     times.  Since this can be fooled by multiple links to the same file,
     or if you use chdir, the second argument may also be a reference to
     an integer (e.g. \1).  In that case the physical identity of the file
     is used, rather than the filename.

     The third argument, when true, means to continue silently when the
     file was not found.

     Note that include is simply a Perl function, thus a run-time affair.
     This means that if you define any functions within the included
     document, they are not known within the including one.  You can
     either mark them as such for the compiler (ampersand and/or parens)
     or you can place the include statement within a `BEGIN {}' block.

include_filehandle *FILEHANDLE*
     Likewise, but reads from the *FILEHANDLE*.

          #! /usr/local/bin/perl
          use Text::iPerl;
          include_filehandle DATA;
          __END__
          Self-parsing iPerl document goes here.

include_string EXPR
include_string
     Likewise, but parses EXPR or $_ if none.

macro STRING
macro
     Returns undef or the macro-definition of STRING, either as a
     code-reference, or the name as a string if the macro is a soft
     reference to a Perl function.  Without an argument returns the list
     of defined macro-names.

          if( defined macro 'mymacro' ) { ... }
          foreach( macro ) { ... }

return
     The normal Perl keyword, returns from a document when used at its
     top-level, i.e. outside of functions, macros or macro invocations,
     save for the m4-style pseudo-macros.  This means, that the rest of
     the document is not processed and output.

set_style STRING[, *ARGUMENT* ...]
set_style CODEREF
     Set one of the following iPerl-styles.  The various styles are more
     or less adapted to various document types.  But of course any style
     can be used anywhere.  Sometimes this requires some extra care, for
     example HTML documents may contain the sequence `!<' which can lead
     to startling effects when used with the bang style.

     It can sometimes be useful to have two different styles in a
     document, for example if you want to do some time-consuming offline
     treatment in a document that will nevertheless later be an active
     web-document.

     The macro invocation style is the only one to be immediately
     effective, being a runtime affair.  The styles for embedded bits of
     Perl, being a compiletime affair, only become effective for the next
     iPerl-documents to be included.

     The mnemonic for the variously used `{...}' is a Perl block, though
     here it is simply a stretch of interpolated Perl code, that does not
     define a block.  The mnemonic for `<...>' is a Perl input operator,
     but inverted here, since the document reads from Perl code.  STRING
     may be one of the following:

    'bang'
    'unix'
          Everything on the same line after `#' is deleted depending on
          $comment_level.

          Lines starting with a ! are bits of Perl.  This reminds of
          interactive unix programs which thus allow a shell escape.

          Perl within lines, potentially spanning several lines, is
          enclosed in `!{' and `}!'.  This reminds of Perl blocks, but
          does not delimit a block.  As a special case `!}!' without
          whitespace is equivalent to `!{}}!', i.e. one closing brace.

          Perl values to be printed to the document are enclosed in `!<'
          and `>!'.  This reminds of the Perl read operator, inverted here
          in that the document reads from a Perl expression.

          Macros may be optionally preceded by &, useful to set them off
          from preceding alphanumeric characters.

    'control'
          Lines starting with a `^A' are bits of Perl.  This reminds of
          the beginning of the alphabet, hence of the line.

          Perl within lines, potentially spanning several lines, is
          enclosed in `^B' and `^E'.  This reminds of beginning and end.

          Perl values to be printed to the document are enclosed in `^P'
          and `^E'.  This reminds of print and end.

    'cpp'
          Everything on the same line after `//' or from `/*' upto next
          `*/' is deleted depending on $comment_level.

          Lines starting with a `#' are bits of Perl.  They may be
          continued over several lines, as long as each line ends with a \.

    generic => *COMMENT*, *BEFOREPRINT*, *AFTERPRINT*, *BEFORE*, *AFTER*
          Arguments are 5 regexps, which may not make backreferences via
          parentheses.  This allows you to define your own simple style.
          Anything matching *COMMENT* is simply ignored.  *BEFOREPRINT*
          and *AFTERPRINT* markup a printing bit of Perl.  And *BEFORE*
          and *AFTER* markup a plain bit of Perl.

    'm4'
          Perl within lines, potentially spanning several lines, is
          enclosed in the pseudo-macro `perl({' and `})'.  This reminds of
          Perl blocks, but does not delimit a block.  As a special case
          `perl(})' without whitespace is equivalent to `perl({}})', i.e.
          one closing brace.

          Perl values to be printed to the document are enclosed in the
          pseudo-macro `perl(<' and `>)'.  This reminds of the Perl read
          operator, inverted here in that the document reads from a Perl
          expression.

          Everything from the pseudo-macro `dnl' through end of line is
          deleted.

          The customary m4 macros `decr', define (iPerl semantics), `defn',
          `errprint', eval, `ifdef', `ifelse', include (iPerl semantics),
          `incr', index, len, `maketemp', `m4exit', `sinclude', substr,
          `syscmd', `sysval', `traceoff', `traceon', `translit' (with an
          additional optional 4th argument for the modifiers of tr) and
          undefine are predefined.

          The customary m4 macros `changecom', `changequote', `divert',
          `divnum', `dumpdef', `m4wrap', `popdef', `pushdef', shift and
          `undivert' are not implemented.

          No macro expansion takes place after a `#'.  This could be
          changed with $macro_start and friends, but note that the above
          mentioned pseudo-macros are already expanded at compile-time.
          Changing this within the document would lead to two different
          comment-styles being used.

          Remember that macro arguments are Perl code, not just bits of
          quoted or unquoted string.

    pod => ARG
    'pod'
          This style can do two things with files containing pod (plain old
          documentation).  For one thing, if ARG is true, it can eliminate
          any pod from document.  It then does nothing else.  This allows
          pod to reside in any file.

          For another, if ARG is missing or false, the pod is extracted
          from the file, processed with embedded Perl, allowing pods to be
          dynamic and spread across several files.  The Perl embedded
          within the pod has nothing to do with the programme that
          contains the pod, even if that is a Perl programme.  This is
          because, from a pod-point-of-view, everything that is not pod is
          ignored.

          Paragraphs starting with `=for perl' or multiple paragraphs
          surrounded by `=begin perl' and `=end perl' contain plain Perl
          code that can control the pod.

          Perl within paragraphs, is enclosed in `P<{' and `}>'.  This
          reminds of Perl blocks, but does not delimit a block.  As a
          special case `P<}>' without whitespace is equivalent to `P<{}}>',
          i.e. one closing brace.

          Perl values to be printed to the document are enclosed in `P<'
          and `>'.  This reminds of the Perl read operator, inverted here
          in that the document reads from a Perl expression.

          `M<' and `>' delimit a macro call within a paragraph.

    'xml'
    'sgml'
          Everything from `<!--' upto next `-->' is deleted depending on
          $comment_level.

          Bits of Perl are enclosed in `<script runat=server>' and
          `</script>' or `<server>' and `</server>'.  Attributes, such as
          `language=Perl' are ignored but recomended to prevent
          mistreatment by other parsers.  More general alternate tags are
          `<perl>' and `</perl>'.  As a more convenient (though probably
          not XML or SGML compliant) alternative, closer to the other
          iPerl-styles, bits of Perl may be enclosed in `<{' and `}>'.  As
          a special case `<}>' without whitespace is equivalent to
          `<{}}>', i.e. one closing brace.  The alternatives are likely not
          recognized by WISIWYG-HTML editors, not being proper HTML, and
          even the server tag might be a Netscape feature, which other
          editors cannot handle.  Even the `script' tag can be problematic
          since it may conditionally include one stretch of text or
          another, which cannot be done with Javascript, thus confusing an
          editor which unconditionally sees both stretches of text.

          Perl values to be printed to the document are enclosed in `&<'
          and `>;'.  This reminds of the Perl read operator, inverted here
          in that the document reads from a Perl expression.  Alternately,
          only within `<' and `>' (actually `<' is not checked for, due to
          the forward looking nature of the parser, but should anyway be
          present before any `>'), Perl values to be printed to the
          document are enclosed in a pair of ``'.  When this is not
          followed by a = the result is surrounded with double quotes.

          Entities (iPerl macros) are enclosed in & and `;'.  If the
          enclosed text is not a defined macro, it is left as an XML
          entity.

    CODEREF
          *NOTE: Since the parsing of a document has to be made more
          efficient, the way this CODEREF works will be totally changed in
          the future.*

          Sets a function and returns the old one, which may have been a
          builtin one.

          The function gets four arguments, 0) a string containing the yet
          unparsed rest of the document, 1) a subregexp to match a
          beginning of line, 2) a subregexp to put before a comment
          matcher and 3) a subregexp to put after a comment matcher.  The
          regexps are only relevant if your style cares about beginnings
          of line or comments.  The comment regexps are provided depending
          on $comment_level.  Regexps 1) and 2) also depend on whether the
          last match (optional 5th return value, see below) ended with a
          newline.  Otherwise the beginning of string will not match a
          beginning of line.

          It gets called repeatedly during parsing of a document and
          should return a list of 4 or 5 elements: 0) leading plain text,
          1) printing Perl expr, 2) plain Perl, 3) the rest to be treated
          next time and optionally 4) the matched string or at least its
          last character.  Those elements not matching anything should be
          undef, epsecially 1) since if it is the empty string, $_ will
          get printed at that point.  When it returns undef as the rest,
          it won't get called again for that document.

undefine EXPR
undefine
     Removes the definedness of EXPR or $_.

VARIABLES
=========

@autostyle_by_contents
     Hash-like list of regexps to match against document to determine the
     mode to use when $style starts with `'auto''.  Unlike a hash, this
     list is processed sequentially until a match is found.

@autostyle_by_name
     Hash-like list of regexps to match against filenames (actually against
     `$documents[-1]') to determine the mode to use when $style starts with
     `'auto''.  Unlike a hash, this list is processed sequentially until a
     match is found.

$cache
     Make include cache the compiled form of the document for quick reuse
     when called again for the same file if `true'.

     Due to a Perl-bug with nested closures, source code, rather than byte
     code, is cached when it contains the word sub.

$comment_level
     What to do with comments in a document when compiling it.  Concerns
     comments in the host part (like `/* ... */' in style cpp), not Perl
     comments.  Values are:

     0:  Do not touch comments in document.

     1:  Remove comments in document, when they go exactly from a
     beginning of line to an end of line.

     2:  Like 1, but there may be whitespace before the comment start or
     after the comment end.

     3:  Remove all comments in document.

     This may be hairy, since iPerl has no knowledge of the host
     document's syntax and will remove everything that looks like a
     comment.  In Perl or Korn shell, for example, `#' does not start a
     comment in all syntactic contexts.  Or a C programme might contain
     `/* ... */' within a string.  So this variable defaults to 1, which
     is fairly safe.

%debug
     Perform debugging for all flags associated with a true value:

          c   generated Perl code
          E   show intern evaluations
          F   say current input file fullname
          f   say current input file basename
          i   say calls to include-functions
          L   say location where debugger was called internally
          p   show searching files in @include
          t   trace for all macro calls, not only those in %trace
          V   automatically implies any other letter

     The following flags are only relevant if t is set or for macros in
     %trace:

          a   show actual arguments
          e   show expansion

     You can add any other letter if you intend to use it in your own
     calls to debug.

$documents
     Incremented for each document included.

@documents
     Contains the list of all nested includes currently active, innermost
     last.  Where a filename is not known for the document, contains the
     strings `'<FILEHANDLE>'', `'<STDIN>'' or `'<STRING>''.

@include
     Second list of directories where include searches for files not found
     in the same directory as the file where include was called.  Defaults
     to `/usr/include' followed by the contents of `@INC'.

$joiner
     Regexp (defaults to `\;') to match what must be at the beginning or
     end of a bit of Perl to suppress the semicolon at that point.

$macro_end
$macro_name_end
$macro_start

$macro_start_dollar1
     $macro_start, $macro_name_end and $macro_end are regexps describing
     the syntactic sugar which is eliminated around macro invocations.
     If, as in style m4, $macro_start has to look backwards, it should
     contain one paren-pair matching the portion of text not to discard,
     and $macro_start_dollar1 should then be true.  These change every
     time a set_style is called explicitly or implicitly.

     If $macro_start and $macro_name_end don't contain the regexp `\b',
     macros will be found in the middle of words.  Or you can use the
     latter variable to allow whitespace before the argument list, or
     prevent it alltogether with a negative lookahead for a parenthesis.

$max_macro_growth
     One bit of plain text may grow by no more than this factor through
     macro expansions.

$max_macro_expansions
     In one bit of plain text no more than this many macro expansions may
     occur.

@opt_I
     First list of directories where include searches for files not found
     in the same directory as the file where include was called.  This is
     not set by `Text::iPerl' but is used if set outside.  The strange
     name comes from the fact that `iperl' like the various invokers of
     the C preprocessor and some m4 implementations use the -I option for
     this.

$preoutput_handler
     *Not yet implemented.*

     Coderef called and reset every time iPerl wants to output a bit of
     plain text.  Will normally be set by programmes to offer some
     initialization that can be overridden by the beginning of a document.

$printfer
     Regexp (defaults to %) to match what must be at the beginning of a
     printing bit of Perl to use printf instead of print.

$style
     This is the name of the style currently in effect.  If this starts
     with `'auto'', the style used for an included document is determined
     in three steps as follows.  This variable is then set to `auto:
     *style*'.

    Style specified in the file
          This is identical to Emacs' local variables specification inside
          a file. There are two possibilities (here shown for style bang):
          On the first line, or on the second if the first line is a
          shebang magic number (`#! *interpreter*'), with possibly other
          semicolon separated variables for use by Emacs:

               -*- iPerl-style: "bang" -*-

          Or, within the last 3000 characters of the document and not
          followed by a page break (`^L'), `/*' and `*/' being examples of
          optional comment delimiters, which, if present, must however be
          identical on all lines, with possibly other specification-lines
          only used by Emacs:

               /* Local Variables: */
               /* iPerl-style: "bang" */
               /* End: */
               

          The style must be given as a double-quoted literal string.  This
          can appear anywhere, i.e. in a bit of Perl as a comment or
          string or in the host document.  If neither of these appear the
          next step is tried.

    Document-name matched against `@autostyle_by_name'
          If no match is found, the next step is tried.

    Document-contents matched against `@autostyle_by_contents'
          If no match is found, the style of the including document is
          maintained.  If there is none, we die.

@_Text_iPerl
     Closure needed for internal purposes visible within your document.
     The effects of changing this variable are not defined.

%trace
     Debug macro operations for all macros who's name is associated with a
     true value, irrespective of the flags in %debug.

SEE ALSO
========

   `iperl' in this node, `web-iPerl' in this node, `iPerl.el' in this
node, *Note Perl: (perl.info)perl,, http://beam.to/iPerl/


File: pm.info,  Node: Passwd/DB,  Next: Passwd/Linux,  Prev: Parse/iPerl,  Up: Module List

Perl module for manipulating a password file stored in a BerkeleyDB hash
************************************************************************

NAME
====

   Passwd::DB - Perl module for manipulating a password file stored in a
BerkeleyDB hash

SYNOPSIS
========

     use Passwd::DB;

     $db = Passwd::DB->new("/usr/local/databases/db_ftp_users");
     $db = Passwd::DB->new("/usr/local/databases/db_ftp_users", 'create');
     @info = $db->getpwnam('bob');
     @info = $db->getpwuid('100');
     @minfo = $db->mgetpwnam('bob');
     $err = $db->modpwinfo(@minfo);
     $err = $db->setpwinfo(@minfo);
     $err = $db->rmpwnam('bob');

     use Passwd::DB qw(init_db getpwnam getpwuid mgetpwnam modpwinfo setpwinfo rmpwnam);

     Passwd::DB->init_db("/usr/local/databases/db_ftp_users");
     Passwd::DB->init_db("/usr/local/databases/db_ftp_users", 1);
     init_db("/usr/local/db_bob",1);
     @info = getpwnam('bob');
     @info = getpwuid('100');
     @minfo = mgetpwnam('bob');
     $err = modpwinfo(@minfo);
     $err = setpwinfo(@minfo);
     $err = rmpwnam('bob');

DESCRIPTION
===========

   Passwd::DB provides basic password routines.  It augments getpwnam and
getpwuid functions with setpwinfo, modpwinfo, rmpwnam, mgetpwnam.  The
routines can be used both in object context or straight.  When used in
non-object context a call to init_db is required to initialize the global
data base structure.  This does mean that you can have only one active
database when used in non-object context.

   new and init_db can be called with an optional second argument.  If it
is set to 1 or 'create' the database will be created if it doesn't already
exist.

   getpwnam and getpwuid are the same as their respective core
counterparts.

   setpwinfo and modpwinfo are called with arrays containing (in order):
name, crypted_password, uid, gid, gecos, home_directory, shell

   rmpwnam is called with a scalar containing the login name.

   mgetpwnam returns the same array that getpwnam returns without the
'unused' age or comment fields.

   setpwinfo does a create/modify of the user.  modpwinfo only does a
modify, it will return an error if the user doesn't exist.

   rmpwnam removes the user with the given login.  It returns an error if
the user doesn't exist.

   Right now all functions croak when they can't open the database.  This
will change if the majority of people don't like this behavior.

   Error return values:   < 0   system error occurred, error value should
be in $!      0   no error     1   operation failed     2   operation
failed because user does not exist

Exported functions on the OK basis
==================================

     getpwnam
     getpwuid
     mgetpwnam
     modpwinfo
     setpwinfo
     rmpwnam
     init_db

AUTHOR
======

   Eric Estabrooks, eric@urbanrage.com

SEE ALSO
========

   perl(1).


File: pm.info,  Node: Passwd/Linux,  Next: Passwd/Solaris,  Prev: Passwd/DB,  Up: Module List

Perl module for manipulating the passwd and shadow files
********************************************************

NAME
====

   Passwd::Linux - Perl module for manipulating the passwd and shadow files

SYNOPSIS
========

     use Passwd::Linux qw(modpwinfo setpwinfo rmpwnam mgetpwnam);

     $err = modpwinfo(@info);
     $err = setpwinfo(@info);
     $err = rmpwnam($name);
     @info = mgetpwnam($name);

DESCRIPTION
===========

   Passwd::Linux provides additional password routines.  It augments the
getpw* functions with setpwinfo, modpwinfo, rmpwnam, mgetpwnam.  You need
to run most of the functions as root or as someone who has permission to
modify the shadow file.

   setpwinfo and modpwinfo are called with arrays containing (in order):
name, crypted_password, uid, gid, gecos, home_directory, shell

   rmpwnam is called with a scalar containing the login name

   mgetpwnam returns the same array that getpwnam returns without the
'unused' age or comment fields it also returns the crypted password if run
with root permissions.

   setpwinfo does a create/modify of the user.  modpwinfo only does a
modify, it will return an error if the user doesn't exist.

   rmpwnam removes the user with the given login from both the password
and shadow files.  It returns an error if the user doesn't exist.

   This module does call syslog in the C portion, but it doesn't call
openlog.  If you wish to see the error output of the syslog you must do an
openlog in your perl script.

   You must be running as root in order to use this module. If it
successfully completes an operation and you are not root then you have a
huge security problem on your box.

   This module as distributed does not allow operations to occur on uid 0
files

   Return values:   < 0	system error occurred, error value should be in $!
   0   no error     1   operation attempt on uid 0     2   user does not
exist

Exported functions on the OK basis
==================================

     modpwinfo
     setpwinfo
     rmpwnam
     mgetpwnam

AUTHOR
======

   Eric Estabrooks,  eric@urbanrage.com

SEE ALSO
========

   perl(1).


File: pm.info,  Node: Passwd/Solaris,  Next: Paw,  Prev: Passwd/Linux,  Up: Module List

Perl module for manipulating the passwd and shadow files
********************************************************

NAME
====

   Passwd::Solaris - Perl module for manipulating the passwd and shadow
files

SYNOPSIS
========

     use Passwd::Solaris qw(modpwinfo setpwinfo rmpwnam mgetpwnam);

     $err = modpwinfo(@info);
     $err = setpwinfo(@info);
     $err = rmpwnam($name);
     @info = mgetpwnam($name);

DESCRIPTION
===========

   Passwd::Solaris provides additional password routines.  It augments the
getpw* functions with setpwinfo, modpwinfo, rmpwnam, mgetpwnam.  You need
to run most of the functions as root or as someone who has permission to
modify the shadow file.

   setpwinfo and modpwinfo are called with arrays containing (in order):
name, crypted_password, uid, gid, gecos, home_directory, shell

   rmpwnam is called with a scalar containing the login name

   mgetpwnam returns the same array that getpwnam returns without the
'unused' age or comment fields it also returns the crypted password if run
with root permissions.

   setpwinfo does a create/modify of the user.  modpwinfo only does a
modify, it will return an error if the user doesn't exist.

   rmpwnam removes the user with the given login from both the password
and shadow files.  It returns an error if the user doesn't exist.

   This module does call syslog in the C portion, but it doesn't call
openlog.  If you wish to see the error output of the syslog you must do an
openlog in your perl script.

   You must be running as root in order to use this module. If it
successfully completes an operation and you are not root then you have a
huge security problem on your box.

   This module as distributed does not allow operations to occur on uid 0
files

   Return values:   < 0	system error occurred, error value should be in $!
   0   no error     1   operation attempt on uid 0     2   user does not
exist

Exported functions on the OK basis
==================================

     modpwinfo
     setpwinfo
     rmpwnam
     mgetpwnam

AUTHOR
======

   Eric Estabrooks,  eric@urbanrage.com

SEE ALSO
========

   perl(1).


File: pm.info,  Node: Paw,  Next: Paw/Box,  Prev: Passwd/Solaris,  Up: Module List

General
=======

   Apart from this documentation there are also some commentated examples
of some Widgets, as well as a complete example for the GUI of a
Setup-program (app2.pl).

using widgets
-------------

   A new Widget is always created by

     $WIDGET_REFERENCE=Paw::WIDGETNAME->new(PARAMETERNAME=>VALUE).

   The PARAMETERs must be passed as HASH (PARAMETERNAME=>VALUE) to the
widget, even if there is only one parameter for the widget.  The methods
of a widget are used by

     $WIDGET_REFERENCE->METHOD(PARAMETER)
     $WIDGET_REFERENCE->METHOD(PARAMETER1=>VALUE1, PARAMETER2=>VALUE2)

   If the method permits only one or zero parameters, it's not necessary
to designate the parameter in a HASH, for example

     $window->put($widget).

   If more than 1 parameter is possible, then each parameter must be
designated by it's name, for example

     $window->abs_move_curs(new_x=>5, new_y=>6) #is okay,

   while

     $window->abs_move_curs(5) # is not okay
     $window->put_dir("h")     # is quite permitted.

Initialisation
--------------

   Every program that uses this modul looks the same in the first lines of
code.

     #!/usr/bin/perl
     use Curses;
     use widget;
     ($columns, $rows)=Paw::init_widgetset();

   $columns and $rows contains the terminal width and height.  This values
can be used to calculate the size or position of other windows, for example

     $main_win=Paw::Window->new(abs_x=>1, abs_y=>1,
                               height=$rows-3, width=>$columns-2,
                               color=>1, statusbar=>1);

Colors
------

   While the initialisation of the widgetset, some colorpairs are set.

     init_pair(1, COLOR_WHITE, COLOR_BLUE);   #default colors
     init_pair(31, COLOR_BLACK, COLOR_BLACK); #shadow
     init_pair(30, COLOR_BLACK, COLOR_CYAN);  #pulldown menu
     init_pair(29, COLOR_BLACK, COLOR_BLUE);  #filedialog

   Already defined colors are black, red, green, yellow, blue, magenta,
cyan, and white New colorpairs can be created by :

     init_pair(pair, foreground_color, background_color);

   Further information about the colormodel can be found in the
documentation of the curses lib (man ncurses, perldoc Curses).

Widgetpacker
------------

   There are two ways how to get widgets into a window.  The first one is
to use the put($widget) function of the window, the second way is to use
boxes (recommended).

   without boxes:

     #put the $label2 into the window
     $win2->put($label2);
     #tell to packer to put the next widget horizontally to the $label2
     $win2->put_dir("h");   # horizontal packen
     #keep on putting widgets ...
     $win2->put($butt1);    # Button for Faktor 2
     $win2->put($label3);   # Faktor 3
     $win2->put($butt2);    # Button for Faktor 3
     $win2->put($label4);   # Faktor 4
     $win2->put($butt3);    # Button for Faktor 4
     #switch the packer to vertikal-mode...
     $win2->put_dir("v");
     #...to get the label under the other widgets.
     $win2->put($label5);   # "Ergebnis : ..."

   We will get

     $label2 $butt1 $label3 $butt2 $label4 $butt3
     $label5

   or

     Faktor 2 [ ] Faktor 3 [ ] Faktor 4 [ ]
     Ergebnis : 200

   This type of widget-packing is nice for smaller GUIs and surely a fast
solution but you will come very fast to the boundaries of your
possibilities.  Then the boxes seems to be the better solution.

   A box takes up several widgets and puts them always either horizontal
or vertically.  The Clou at a box is that it can also take up other boxes.
It is possible that a horizontal box is to be packed into a vertical box
and this in any depth.  If you  know the widgetpacker of GTK or TK, you
know this widgetpacker too.

     ###########################################
     # 7 Buttons building an H
     ###########################################

     $vbox0->put($b1);

     $hbox1->put($b2);
     $hbox1->put($b3);

     $vbox0->put($hbox1);
     $vbox0->put($b4);

     $hbox0->put($vbox0);

     $vbox1->put($b5);
     $vbox1->put($b6);
     $vbox1->put($b7);

     $hbox0->put($vbox1);

     $win->put($hbox0);

   We will get:

     [1]   [5]
     [2][3][6]
     [4]   [7]

SEE ALSO
========

   Paw::Box          container for other Widgets

   Paw::Button       simple Button (optionally with label)

   Paw::Filedialog   filedialog Widget

   Paw::Label        simple text label

   Paw::Line         h/v line (seperator for menus)

   Paw::Listbox      box with selectable lines

   Paw::Menu         pulldown menus

   Paw::Popup        popup window with text and buttons

   Paw::Progressbar  a progressbar

   Paw::Radiobutton  a group of buttons but only one can be selected

   Paw::Scrollbar    scrollbar for other widgets (listbox...) no mouse
support

   Paw::Statusbar    bottomline for windows

   Paw::Text_entry   enter one line of text

   Paw::Textbox      box with more lines of text (buggy !!!)

   Paw::Window       container for other widgets

COPYRIGHT
=========

   Copyright (c) 1999 SuSE GmbH, Nuernberg, Germany. All rights reserved.


File: pm.info,  Node: Paw/Box,  Next: Paw/Box-de,  Prev: Paw,  Up: Module List

Box Widget
==========

   *$box=Paw::Box-*new($direction, [$name], [$title], [$color],
[$orientation])>;

   Parameter

     $direction   => Direction in that the widgets will be packed
                     "v"ertically or "h"orizontally

     $color       => The colorpair must be generated with
                     Curses::init_pair(pair_nr, COLOR_fg, COLOR_bg)
                     [optionally]

     $name        => Name of the box [optionally]

     $orientation => "topleft", "topright", "bottomleft", "bottomright",
                     "center" and "grow" are the possible parameters.
                     They indicate how the box will behave on
                     modifications of the terminal size.
                     Either it keeps it's distance to the indicated
                     terminal side, it remains centered or it
                     grows/shrinks with the new terminal size
                     (default is the orientation of the parent-widget)
                     [ optionally ].'
     B<Example>

     $box=Paw::Box->new(direction=>"v",title=>"Start",color=>1);

put($widget)
------------

   put the widget into the box.

   Example

     $box->put($button0);

set_border(["shade"])
---------------------

   activate the border of the box optionally also with shadows.

   Example

     $box->set_border("shade"); or $win->set_border();

abs_move_curs($new_x, $new_y);
------------------------------

   Sets the packer to the absolute position in the box (negative values
lay outside of the box).

   Example

     $box->abs_move_curs(new_x=>1);

rel_move_curs($new_x, $new_y);
------------------------------

   Sets the packer relative to the current position in the box (also
negative values are possible).

   Example

     $box->rel_move_curs(new_y=>3, new_x=>-2);


File: pm.info,  Node: Paw/Box-de,  Next: Paw/Button,  Prev: Paw/Box,  Up: Module List

Box Widget
==========

   *$box=Paw::Box::new($direction, [$name], [$title], [$color],
[$orientation])*;

   Parameter

     $direction   => Richtung in welche die Widgets gepackt werden sollen
                     "v"ertikal oder "h"orizont

     $color       => Das Farbpaar (colorpair) muss mit
                     Curses::init_pair(pair_nr, COLOR_fg, COLOR_bg)
                     erzeugt werden[optional]

     $name        => Name der Box [optional]

     $orientation => "topleft", "topright", "bottomleft", "bottomright",
                     "center" und "grow" sind die moeglichen Parameter.
                     Sie geben an wie sich die Box bei Änderung der
                     Terminalgroesse verhaelt. Entweder behaelt es seinen
                     Abstand zu der angegebenen Seite bei, es bleibt
                     zentriert oder es waechst bzw. schrumpft mit dem
                     Terminal.
                     (default ist die "Orientation" des Elternwidgets)
                     [optional]

   *Beispiel*

     $box=Paw::Box::new(direction=>"v",title=>"Start",color=>1);

put($widget)
------------

   pack das Widget in die Box

   *Beispiel*

     $box->put($button0);

set_border(["shade"])
---------------------

   aktiviert den Rahmen der Box optional auch mit Schatten.

   *Beispiel*

     $box->set_border("shade"); oder $win->set_border();

abs_move_curs($new_x, $new_y);
------------------------------

   Setzt den Packer an die absolute Position in der Box (negative Werte
liegen ausserhalb der Box).

   *Beispiel*

     $box->abs_move_curs(new_x=>1);

rel_move_curs($new_x, $new_y);
------------------------------

   Setzt den Packer relativ zur momentanen Position in der Box (auch
negative Werte moeglich).

   *Beispiel*

     $box->rel_move_curs(new_y=>3, new_x=>-2);


File: pm.info,  Node: Paw/Button,  Next: Paw/Button-de,  Prev: Paw/Box-de,  Up: Module List

Button Widget
=============

   *$button=Paw::Button-*new([$color], [$name], [\&callback], [$label]);>

   Parameter

     color    => the colorpair must be generated with
                 Curses::init_pair(pair_nr, COLOR_fg, COLOR_bg)
                 [optionally]

     name     => name of the button [optionally]

     callback => reference to the function which will be called
                 when pushing the button. [optionally]

     label    => text in the button. If the button contains text,
                 it is not possible to see if it is pushed or not.
                 [optionally]

   Example

     $button=Paw::Button->new(callback=>\&button_callback);

   Callback

     sub button_callback {
         my $this = shift;             # Referenz to the button
     
         $data = $edit->get_text();
         $box->add_row($data);
         return;
     }

set_button()
------------

   Sets the button into the status " pressed "

   Example

     $button->set_button();      # [x]

release_button()
----------------

   Sets the button into the status "not pressed"

   Example

     $button->release_button();      # [ ]

push_button()
-------------

   the button changes it status.

   Example

     $button->push_button();      # [x]->[ ], [ ]->[x]

abs_move_widget($new_x, $new_y)
-------------------------------

   the widget moves to the new absolute screen position.  if you set only
one of the two parameters, the other one keeps the old value.

   Example

     $button->abs_move_widget( new_x=>5 );      #y-pos is the same

get_widget_pos()
----------------

   returns an array of two values, the x-position and the y-position of
the widget.

   Example

     ($xpos,$ypos)=$button->get_widget_pos();

set_color($color_pair)
----------------------

   Set a new color_pair for the widget.

   Example

     $button->set_color(3);

set_border(["shade"])
---------------------

   activates the border of the widget (optionally also with shadows).

   Example

     $widget->set_border("shade"); or $widget->set_border();


File: pm.info,  Node: Paw/Button-de,  Next: Paw/Filedialog,  Prev: Paw/Button,  Up: Module List

Button Widget
=============

   *$button=Paw::Button::new([$color], [$name], [\&callback], [$label]);*

   Parameter

     $color   => Das Farbpaar (colorpair) muss mit
                 Curses::init_pair(pair_nr, COLOR_fg, COLOR_bg)
                 erzeugt werden[optional]

     name     => Name des button [optional]

     callback => Reference auf die Function die beim druecken des
                 Button aufgerufen wird. [optional]

     label    => Text in dem Button. Wenn der Button einen Text
                 enthaelt, ist optisch nicht mehr feststellbar,
                 ob der Button gedrueckt ist. [optional]

   *Beispiel*

     $button=Paw::Button::new(callback=>\&button_callback);

   Callback

   Wird der Button betaetigt, so wird die Callback-Funktion angesprungen.

     sub button_callback {
         my $this = shift;             # Referenz to the button
     
         $data = $edit->get_text();
         $box->add_row($data);
         return;
     }

set_button()
------------

   Setzt den Button in den definierten Zustand "gedrueckt".

   *Beispiel*

     $button->set_button();      # [x]

release_button()
----------------

   Setzt den Button in den definierten Zustand "nicht gedrueckt"

   *Beispiel*

     $button->release_button();      # [ ]

push_button()
-------------

   Der Button wechselt seinen Zustand.

   *Beispiel*

     $button->push_button();      # [x]->[ ], [ ]->[x]

abs_move_widget($new_x, $new_y)
-------------------------------

   Das Widget verschiebt sich auf die neue absolute Schirm Position.  Wird
nur einer der Parameter angegeben, so behaelt der andere seinen Wert bei.

   *Beispiel*

     $button->abs_move_widget( new_x=>5 );      #y-pos bleibt wie sie ist

get_widget_pos()
----------------

   Gibt ein Array mit den beiden Wertde (x-Position, y-Position) zurueck.

   *Beispiel*

     ($xpos,$ypos)=$button->get_widget_pos();

set_color($color_pair)
----------------------

   Setzt ein neues color_pair.

   *Beispiel*

     $button->set_color(3);

set_border(["shade"])
---------------------

   aktiviert den Rahmen der Box. Optional auch mit Schatten.

   *Beispiel*

     $box->set_border("shade"); or $win->set_border();


File: pm.info,  Node: Paw/Filedialog,  Next: Paw/Filedialog-de,  Prev: Paw/Button-de,  Up: Module List

Filedialog
==========

   *$fd=Paw::Filedialog-*new([$height], [$width], [$name], [$dir])>;

   Parameter

     $height    => number of rows [optionally]

     $width     => number of columns [optionally]

     $name      => name of the widget [optionally]

     $dir       => the directory in which the filedialog
                   will be started ("." default) [optionally]

   When the filedialogbox is closed by the "ok"-button, it returns an
array of all marked filenames (without path)

   Example

     $fd=Paw::Filedialog->new(dir=>"/etc");

set_dir($path)
--------------

   Set the directory where the filedialog will begin.

   Example

     $fd->set_dir();       # start in "."
     $fd->set_dir("/etc"); # start in "/etc"

get_dir($scalar)
----------------

   Returns the path of the filedialogbox.

   Example

     $path=$fd->get_dir();  #$path = "/etc" (for example).

draw()
------

   Raises the filedialog. If the box is closed by the "ok-button", it
returns an array of all marked filenames (without path). If the box is
closed by the "cancel-button", no return of the marked files takes place.

   Example

     @files=$fd->draw();

set_border(["shade"])
---------------------

   activates the border of the widget (optionally also with shadows).

   Example

     $widget->set_border("shade"); or $widget->set_border();


File: pm.info,  Node: Paw/Filedialog-de,  Next: Paw/Label,  Prev: Paw/Filedialog,  Up: Module List

Filedialog
==========

   *$fd=Paw::Filedialog::new([$height], [$width], [$name], [$dir])*;

   Parameter

     $height    => Anzahl der Reihen [optional]

     $width     => Anzahl der Spalten [optional]

     $name      => Name des Widgets [optional]

     $dir       => Das Verzeichnis in dem der Filedialog starten soll
                   ("." default) [optional]

   Wen der Filedialog mit dem "Ok-Button" verlassen wird, so gibt er ein
Array aller markierten Filenamen zurueck.

   *Beispiel*

     $fd=Paw::Filedialog::new(dir=>"/etc");

set_dir($path)
--------------

   Setzt das Verzeichnis in dem der Filedialog starten soll

   *Beisiel*

     $fd->set_dir();       # start in "."
     $fd->set_dir("/etc"); # start in "/etc"

get_dir($scalar)
----------------

   Gibt den Pfad zurueck in dem sich die Filedialogbox befindet.

   *Beispiel*

     $path=$fd->get_dir();  #$path = "/etc" (for example).

draw()
------

   Stellt die Filedialogbox am Schirm da. Wenn die Box ueber "Ok"
geschlossen wird, so gibt sie ein Array aller markierten Filenamen (ohne
Pfad) zurueck. Wird die Box ueber "Cancel" verlassen, erfolgt keine
Rueckgabe der marktierten Files.

   *Beispiel*

     @files=$fd->draw();

set_border(["shade"])
---------------------

   aktiviert den Rahmen der Box. Optional auch mit Schatten.

   *Beispiel*

     $box->set_border("shade"); or $win->set_border();


File: pm.info,  Node: Paw/Label,  Next: Paw/Label-de,  Prev: Paw/Filedialog-de,  Up: Module List

Label Widget
============

   *$label=Paw::Label-*new($text, [$color], [$name]);>

   Example

     $label=Paw::Label->new(text=>"Text", color=>3, name=>"Linux_Label");

   Parameter

     text  => Text of the label

     color => The colorpair must be generated with
              Curses::init_pair(pair_nr, COLOR_fg, COLOR_bg)
              [optionally]

     name  => Name of the widget [optionally]

set_text($text)
---------------

   Change the text of the label to the string $text.

   Example

     $label->set_text("changed label text");

get_text();
-----------

   returns the label-text.

   Example

     $text=$label->get_text();

abs_move_widget($new_x, $new_y)
-------------------------------

   the widget moves to the new absolute screen position.  if you set only
one of the two parameters, the other one keeps the old value.

   Example

     $label->abs_move_widget( new_x=>5 );      #y-pos is the same

get_widget_pos()
----------------

   returns an array of two values, the x-position and the y-position of
the widget.

   Example

     ($xpos,$ypos)=$label->get_widget_pos();

set_color($color_pair)
----------------------

   Set a new color_pair for the widget.

   Example

     $box->set_color(3);

set_border(["shade"])
---------------------

   activates the border of the widget (optionally also with shadows).

   Example

     $widget->set_border("shade"); or $widget->set_border();