This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Pod/newvar2, Next: Pod/objects, Prev: Pod/newvar, Up: Module List Perl predefined variables ************************* NAME ==== perlvar - Perl predefined variables DESCRIPTION =========== Predefined Names ---------------- The following names have special meaning to Perl. Most of the punctuational names have reasonable mnemonics, or analogues in one of the shells. Nevertheless, if you wish to use the long variable names, you just need to say use English; at the top of your program. This will alias all the short names to the long names in the current package. Some of them even have medium names, generally borrowed from *awk*. To go a step further, those variables that depend on the currently selected filehandle may instead be set by calling an object method on the FileHandle object. (Summary lines below for this contain the word HANDLE.) First you must say use FileHandle; after which you may use either method HANDLE EXPR or HANDLE->method(EXPR) Each of the methods returns the old value of the FileHandle attribute. The methods each take an optional EXPR, which if supplied specifies the new value for the FileHandle attribute in question. If not supplied, most of the methods do nothing to the current value, except for autoflush(), which will assume a 1 for you, just to be different. A few of these variables are considered "read-only". This means that if you try to assign to this variable, either directly or indirectly through a reference, you'll raise a run-time exception. $ARG $_ The default input and pattern-searching space. The following pairs are equivalent: while (<>) {...} # only equivalent in while! while ($_ = <>) {...} /^Subject:/ $_ =~ /^Subject:/ tr/a-z/A-Z/ $_ =~ tr/a-z/A-Z/ chop chop($_) (Mnemonic: underline is understood in certain operations.) $ Contains the subpattern from the corresponding set of parentheses in the last pattern matched, not counting patterns matched in nested blocks that have been exited already. (Mnemonic: like \digit.) These variables are all read-only. $MATCH $& The string matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval() enclosed by the current BLOCK). (Mnemonic: like & in some editors.) This variable is read-only. $PREMATCH $` The string preceding whatever was matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval enclosed by the current BLOCK). (Mnemonic: ` often precedes a quoted string.) This variable is read-only. $POSTMATCH $' The string following whatever was matched by the last successful pattern match (not counting any matches hidden within a BLOCK or eval() enclosed by the current BLOCK). (Mnemonic: ' often follows a quoted string.) Example: $_ = 'abcdefghi'; /def/; print "$`:$&:$'\n"; # prints abc:def:ghi This variable is read-only. $LAST_PAREN_MATCH $+ The last bracket matched by the last search pattern. This is useful if you don't know which of a set of alternative patterns matched. For example: /Version: (.*)|Revision: (.*)/ && ($rev = $+); (Mnemonic: be positive and forward looking.) This variable is read-only. $MULTILINE_MATCHING Set to 1 to do multiline matching within a string, 0 to tell Perl that it can assume that strings contain a single line, for the purpose of optimizing pattern matches. Pattern matches on strings containing multiple newlines can produce confusing results when "$*" is 0. Default is 0. (Mnemonic: * matches multiple things.) Note that this variable only influences the interpretation of "^" and "`$'". A literal newline can be searched for even when `$* == 0'. Use of "$*" is deprecated in Perl 5. input_line_number HANDLE EXPR $INPUT_LINE_NUMBER $NR $. The current input line number of the last filehandle that was read. An explicit close on the filehandle resets the line number. Since "`<>'" never does an explicit close, line numbers increase across ARGV files (but see examples under eof()). Localizing $. has the effect of also localizing Perl's notion of "the last read filehandle". (Mnemonic: many programs use "." to mean the current line number.) input_record_separator HANDLE EXPR $INPUT_RECORD_SEPARATOR $RS $/ The input record separator, newline by default. Works like *awk*'s RS variable, including treating blank lines as delimiters if set to the null string. You may set it to a multicharacter string to match a multi-character delimiter. Note that setting it to `"\n\n"' means something slightly different than setting it to "", if the file contains consecutive blank lines. Setting it to "" will treat two or more consecutive blank lines as a single blank line. Setting it to `"\n\n"' will blindly assume that the next input character belongs to the next paragraph, even if it's a newline. (Mnemonic: / is used to delimit line boundaries when quoting poetry.) undef $/; $_ = ; # whole file now here s/\n[ \t]+/ /g; autoflush HANDLE EXPR $OUTPUT_AUTOFLUSH $| If set to nonzero, forces a flush after every write or print on the currently selected output channel. Default is 0. Note that STDOUT will typically be line buffered if output is to the terminal and block buffered otherwise. Setting this variable is useful primarily when you are outputting to a pipe, such as when you are running a Perl script under rsh and want to see the output as it's happening. (Mnemonic: when you want your pipes to be piping hot.) output_field_separator HANDLE EXPR $OUTPUT_FIELD_SEPARATOR $OFS $, The output field separator for the print operator. Ordinarily the print operator simply prints out the comma separated fields you specify. In order to get behavior more like *awk*, set this variable as you would set *awk*'s OFS variable to specify what is printed between fields. (Mnemonic: what is printed when there is a , in your print statement.) output_record_separator HANDLE EXPR $OUTPUT_RECORD_SEPARATOR $ORS $\ The output record separator for the print operator. Ordinarily the print operator simply prints out the comma separated fields you specify, with no trailing newline or record separator assumed. In order to get behavior more like *awk*, set this variable as you would set *awk*'s ORS variable to specify what is printed at the end of the print. (Mnemonic: you set "$\" instead of adding \n at the end of the print. Also, it's just like /, but it's what you get "back" from Perl.) $LIST_SEPARATOR $" This is like "$," except that it applies to array values interpolated into a double-quoted string (or similar interpreted string). Default is a space. (Mnemonic: obvious, I think.) $SUBSCRIPT_SEPARATOR $SUBSEP $; The subscript separator for multi-dimensional array emulation. If you refer to a hash element as $foo{$a,$b,$c} it really means $foo{join($;, $a, $b, $c)} But don't put @foo{$a,$b,$c} # a slice--note the @ which means ($foo{$a},$foo{$b},$foo{$c}) Default is "\034", the same as SUBSEP in *awk*. Note that if your keys contain binary data there might not be any safe value for "$;". (Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon. Yeah, I know, it's pretty lame, but "$," is already taken for something more important.) Consider using "real" multi-dimensional arrays in Perl 5. $OFMT $# The output format for printed numbers. This variable is a half-hearted attempt to emulate *awk*'s OFMT variable. There are times, however, when *awk* and Perl have differing notions of what is in fact numeric. Also, the initial value is %.20g rather than %.6g, so you need to set "$#" explicitly to get *awk*'s value. (Mnemonic: # is the number sign.) Use of "$#" is deprecated in Perl 5. format_page_number HANDLE EXPR $FORMAT_PAGE_NUMBER $% The current page number of the currently selected output channel. (Mnemonic: % is page number in *nroff*.) format_lines_per_page HANDLE EXPR $FORMAT_LINES_PER_PAGE $= The current page length (printable lines) of the currently selected output channel. Default is 60. (Mnemonic: = has horizontal lines.) format_lines_left HANDLE EXPR $FORMAT_LINES_LEFT $- The number of lines left on the page of the currently selected output channel. (Mnemonic: lines_on_page - lines_printed.) format_name HANDLE EXPR $FORMAT_NAME $~ The name of the current report format for the currently selected output channel. Default is name of the filehandle. (Mnemonic: brother to "$^".) format_top_name HANDLE EXPR $FORMAT_TOP_NAME $^ The name of the current top-of-page format for the currently selected output channel. Default is name of the filehandle with _TOP appended. (Mnemonic: points to top of page.) format_line_break_characters HANDLE EXPR $FORMAT_LINE_BREAK_CHARACTERS $: The current set of characters after which a string may be broken to fill continuation fields (starting with ^) in a format. Default is " \n-", to break on whitespace or hyphens. (Mnemonic: a "colon" in poetry is a part of a line.) format_formfeed HANDLE EXPR $FORMAT_FORMFEED $^L What formats output to perform a formfeed. Default is \f. $ACCUMULATOR $^A The current value of the write() accumulator for format() lines. A format contains formline() commands that put their result into $^A. After calling its format, write() prints out the contents of $^A and empties. So you never actually see the contents of $^A unless you call formline() yourself and then look at it. See *Note Perlform: (perl.info)perlform, and `formline()', *Note Perlfunc: (perl.info)perlfunc,. $CHILD_ERROR $? The status returned by the last pipe close, backtick (```') command, or system() operator. Note that this is the status word returned by the wait() system call, so the exit value of the subprocess is actually (`$? >> 8'). Thus on many systems, `$? & 255' gives which signal, if any, the process died from, and whether there was a core dump. (Mnemonic: similar to *sh* and *ksh*.) $OS_ERROR $ERRNO $! If used in a numeric context, yields the current value of errno, with all the usual caveats. (This means that you shouldn't depend on the value of "$!" to be anything in particular unless you've gotten a specific error return indicating a system error.) If used in a string context, yields the corresponding system error string. You can assign to "$!" in order to set errno if, for instance, you want "$!" to return the string for error n, or you want to set the exit value for the die() operator. (Mnemonic: What just went bang?) $EVAL_ERROR $@ The Perl syntax error message from the last eval() command. If null, the last eval() parsed and executed correctly (although the operations you invoked may have failed in the normal fashion). (Mnemonic: Where was the syntax error "at"?) Note that warning messages are not collected in this variable. You can, however, set up a routine to process warnings by setting $SIG{__WARN__} below. $PROCESS_ID $PID $$ The process number of the Perl running this script. (Mnemonic: same as shells.) $REAL_USER_ID $UID $< The real uid of this process. (Mnemonic: it's the uid you came *FROM*, if you're running setuid.) $EFFECTIVE_USER_ID $EUID $> The effective uid of this process. Example: $< = $>; # set real to effective uid ($<,$>) = ($>,$<); # swap real and effective uid (Mnemonic: it's the uid you went TO, if you're running setuid.) Note: "`$<'" and "`$>'" can only be swapped on machines supporting setreuid(). $REAL_GROUP_ID $GID $( The real gid of this process. If you are on a machine that supports membership in multiple groups simultaneously, gives a space separated list of groups you are in. The first number is the one returned by getgid(), and the subsequent ones by getgroups(), one of which may be the same as the first number. (Mnemonic: parentheses are used to *GROUP* things. The real gid is the group you *LEFT*, if you're running setgid.) $EFFECTIVE_GROUP_ID $EGID $) The effective gid of this process. If you are on a machine that supports membership in multiple groups simultaneously, gives a space separated list of groups you are in. The first number is the one returned by getegid(), and the subsequent ones by getgroups(), one of which may be the same as the first number. (Mnemonic: parentheses are used to *GROUP* things. The effective gid is the group that's *RIGHT* for you, if you're running setgid.) Note: "`$<'", "`$>'", "$(" and "$)" can only be set on machines that support the corresponding *set[re][ug]id()* routine. "$(" and "$)" can only be swapped on machines supporting setregid(). $PROGRAM_NAME $0 Contains the name of the file containing the Perl script being executed. Assigning to "$0" modifies the argument area that the ps(1) program sees. This is more useful as a way of indicating the current program state than it is for hiding the program you're running. (Mnemonic: same as *sh* and *ksh*.) $[ The index of the first element in an array, and of the first character in a substring. Default is 0, but you could set it to 1 to make Perl behave more like *awk* (or Fortran) when subscripting and when evaluating the index() and substr() functions. (Mnemonic: [ begins subscripts.) As of Perl 5, assignment to "$[" is treated as a compiler directive, and cannot influence the behavior of any other file. Its use is discouraged. $PERL_VERSION $] The string printed out when you say `perl -v'. It can be used to determine at the beginning of a script whether the perl interpreter executing the script is in the right range of versions. If used in a numeric context, returns the version + patchlevel / 1000. Example: # see if getc is available ($version,$patchlevel) = $] =~ /(\d+\.\d+).*\nPatch level: (\d+)/; print STDERR "(No filename completion available.)\n" if $version * 1000 + $patchlevel < 2016; or, used numerically, warn "No checksumming!\n" if $] < 3.019; (Mnemonic: Is this version of perl in the right bracket?) $DEBUGGING $^D The current value of the debugging flags. (Mnemonic: value of -D switch.) $SYSTEM_FD_MAX $^F The maximum system file descriptor, ordinarily 2. System file descriptors are passed to exec()ed processes, while higher file descriptors are not. Also, during an open(), system file descriptors are preserved even if the open() fails. (Ordinary file descriptors are closed before the open() is attempted.) Note that the close-on-exec status of a file descriptor will be decided according to the value of $^F at the time of the open, not the time of the exec. $INPLACE_EDIT $^I The current value of the inplace-edit extension. Use undef to disable inplace editing. (Mnemonic: value of -i switch.) $PERLDB $^P The internal flag that the debugger clears so that it doesn't debug itself. You could conceivable disable debugging yourself by clearing it. $BASETIME $^T The time at which the script began running, in seconds since the epoch (beginning of 1970). The values returned by the -M, -A and -C filetests are based on this value. $WARNING $^W The current value of the warning switch, either TRUE or FALSE. (Mnemonic: related to the -w switch.) $EXECUTABLE_NAME $^X The name that the Perl binary itself was executed as, from C's `argv[0]'. $ARGV contains the name of the current file when reading from <>. @ARGV The array @ARGV contains the command line arguments intended for the script. Note that `$#ARGV' is the generally number of arguments minus one, since `$ARGV[0]' is the first argument, *NOT* the command name. See "$0" for the command name. @INC The array @INC contains the list of places to look for Perl scripts to be evaluated by the `do EXPR', require, or use constructs. It initially consists of the arguments to any -I command line switches, followed by the default Perl library, probably "/usr/local/lib/perl", followed by ".", to represent the current directory. %INC The hash %INC contains entries for each filename that has been included via do or require. The key is the filename you specified, and the value is the location of the file actually found. The require command uses this array to determine whether a given file has already been included. $ENV{expr} The hash %ENV contains your current environment. Setting a value in ENV changes the environment for child processes. $SIG{expr} The hash %SIG is used to set signal handlers for various signals. Example: sub handler { # 1st argument is signal name local($sig) = @_; print "Caught a SIG$sig--shutting down\n"; close(LOG); exit(0); } $SIG{'INT'} = 'handler'; $SIG{'QUIT'} = 'handler'; ... $SIG{'INT'} = 'DEFAULT'; # restore default action $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT The %SIG array only contains values for the signals actually set within the Perl script. Here are some other examples: $SIG{PIPE} = Plumber; # SCARY!! $SIG{"PIPE"} = "Plumber"; # just fine, assumes main::Plumber $SIG{"PIPE"} = \&Plumber; # just fine; assume current Plumber $SIG{"PIPE"} = Plumber(); # oops, what did Plumber() return?? The one marked scary is problematic because it's a bareword, which means sometimes it's a string representing the function, and sometimes it's going to call the subroutine call right then and there! Best to be sure and quote it or take a reference to it. *Plumber works too. See `perlsubs' in this node. Certain internal hooks can be also set using the %SIG hash. The routine indicated by $SIG{__WARN__} is called when a warning message is about to be printed. The warning message is passed as the first argument. The presence of a __WARN__ hook causes the ordinary printing of warnings to STDERR to be suppressed. You can use this to save warnings in a variable, or turn warnings into fatal errors, like this: local $SIG{__WARN__} = sub { die $_[0] }; eval $proggie; The routine indicated by $SIG{__DIE__} is called when a fatal exception is about to be thrown. The error message is passed as the first argument. When a __DIE__ hook routine returns, the exception processing continues as it would have in the absence of the hook, unless the hook routine itself exits via a goto, a loop exit, or a die.  File: pm.info, Node: Pod/objects, Next: Pod/test, Prev: Pod/newvar2, Up: Module List package with objects for representing POD documents *************************************************** NAME ==== Pod::objects - package with objects for representing POD documents SYNOPSIS ======== require Pod::objects; my $root = Pod::root->new; DESCRIPTION =========== The following section describes the objects returned by `Pod::Compiler|Pod::Compiler' in this node and their methods. These objects all inherit from `Tree::DAG_Node|Tree::DAG_Node' in this node, so all methods described there are valid as well. The set/retrieve methods all work in the following way: If no argument is specified, the corresponding value is returned. Otherwise the object's value is set to the given argument and returned. Common methods -------------- The following methods are common for all the classes: class->new( @parameters ) Create a new object instance of class. See the individual classes for valid parameters. $obj->line( $num ) Store/retrieve the line number where this object occurred in the source file. Sets and returns the new value if $num is defined and simply returns the value otherwise. $obj->*as_pod*() This method returns the object in POD syntax, including its child objects. Basically this gives you the same code as in the input file. $obj->*contents_as_pod*() Return this object's children in POD format. $obj->as_text() This method returns the object as simple text in ISO-8859-1 encoding. All POD markup is discarded. $obj->*contents_as_text*() Return this object's children as simple text in ISO-8859-1 encoding. This strips all POD markup. Pod::root --------- This object represents the root of the POD document and thus serves mainly as a storage for the following classes. It inherits from `Storable|Storable' in this node, so that it can easily be stored to and retrived from the file system. Pod::root->new( %params ) The creation method takes an optional argument `-linelength => num'. If this is set to a non-zero value, the *as_pod* method of Pod::paragraph will reformat the POD to use as much of each line up to num characters. $root->store( $file ) $root->*store_fd*( $filehandle ) Store the object (and all its contents) to the given file name/handle using `Storable|Storable' in this node for subsequent retrieval. Pod::root->read( $file ) Pod::root->*read_fd*( $filehandle ) Read the given file/handle into a Pod::root object. $file must contain a Pod::root object stored by `Storable|Storable' in this node, otherwise a fatal error is raised. $root->*nodes*() Retrieves this POD's node collection, which is maintained as a Pod::node::collection object. $root->errors() Returns the number of errors occured during parsing. $root->warnings() Returns the number of warnings occured during parsing. $root->links() Returns all Pod::link objects within the parsed document. Pod::perlcode ------------- If the *-perlcode* option was true for *Pod::Compiler*, then these objects represent Perl code blocks in the parsed file. The as_text method returns the empty string, *as_pod* the contents. Pod::perlcode->new( $text ) The new constructor takes an optional parameter, which is the string representing the code block. This string may contain newlines. $perlcode->*contents*( $string ) This methods sets/retrieves the code block. $perlcode->append( $code ) This methods appends $code to the contents. Pod::paragraph -------------- This represents a simple text paragraph. See Pod::root above for an option that forces the reformatting of the POD code of a paragraph to a certain line length. Forced line breaks, i.e. a newline followed by whitespace is not affected. Pod::verbatim ------------- This represents a verbatim paragraph, i.e. a block that has leading whitespace on its first line. $verbatim->*addline*( $line ) Adds one line to this verbatim paragraph. *$line* should not contain carriage returns nor newlines. $verbatim->content( @lines ) Set this verbatim paragraph's contents to *@lines*. If *@lines* is omitted, this method simply returns the current contents, i.e. an array of strings that reresent the individual lines. The contents can be cleared completely by saying `$verbatim->content( undef )'. Pod::head --------- This class represents `=headX' directives. The new method accepts a single argument which denotes the heading level, default is 1. $head->level( $num ) This sets/retrieves the heading level. Officially supported are only 1 and 2, but higher numbers are not rejected here. $head->node( $node ) This sets/retrieves the heading's node information. $node and the return value are instances of Pod::node or undef. $head->*nodeid*() This retrieves the heading's node id from node above. Just a shortcut for `$head->node->id', and safe in case the node is not defined. Returns the id string or undef. $head->*nodetext*() This retrieves the heading's node text from node above. Just a shortcut for `$head->node->text', and safe in case the node is not defined. Returns the node text or undef. The node text is derived from what comes after =item, stripping * (bullets) and `\d.?' (numbers) as well as all POD markup. The result is what POD links can link to from other documents. Pod::list --------- This stores everything that is enclosed by `=over ... =back'. Note that such a brace may not span `=head's. $list->*autoopen*( $flag ) This sets/retrieves the *autoopen* property. A list gets this property when the parser encounters an =item without a previous =over. The parser then opens a (implicit) list which has the *autoopen* property set to true. $list->indent( $num ) This sets/retrieves the indent level of the list, i.e. the value that follows =over. Default is 4. $list->type( $string ) This sets/retrieves the list type. The parser tries to guess this type from the =items it encounters. The three possible types are bullet, number, and `definition'. In case of doubt, `definition' wins. $list->*has_items*() This retrieves the number of =items in this list. Pod::item --------- This stores a list's =item. $item->prefix( $string ) This sets the item's prefix. A prefix can be either '*' or 'o' in case of a bullet list or a number, optionally followed by a dot for numbered lists. This is stored separately because links to such nodes do not contain the prefix. In case of a numbered list this method returns subsequent numbers for each item independent of what was parsed. $item->node() $item->*nodeid*() $item->*nodetext*() See `"Pod::head"' in this node for the description of these methods. Pod::begin ---------- This stores everything between `=begin ... =end'. It is unclear how POD directives in such a block should be handled. The behaviour is undefined and may change in the future. *as_pod* returns the original contents, as_text returns the empty string. $begin->type( $string ) This set/retrieves the begin/end block type, i.e. the first argument after =begin. $begin->args( $string ) This set/retrieves the begin/end block arguments, i.e. everything the follows the first argument after =begin. $begin->*addchunk*( $string ) This adds a chunk to the begin/end block. A chunk is a paragraph. $begin->*contents*() Return the current contents, i.e. the array of all chunks. Pod::for -------- This stores =for paragraphs. The *as_pod* method return the original contents, as_text returns the empty string. $for->type( $string ) This sets/retrieves the formatter specification of the =for pargraph. $for->args( $string ) This sets/retrieves everything following the formatter specification up to the next newline. $for->content( $string ) This sets/retrieves the =for paragraph's contents, i.e. everything following the first newline after the =for directive. Textual Objects --------------- The following sections describe objects that represent text. They have some common methods: $textobj->nested() Gives a string that contains the interior sequence codes in which this object is nested. A string object XXX inside `B<...I...>' would thus return `BI'. $textobj->*as_pod*() Gives the POD code of this object, including its children. $textobj->as_text() Gives the objects text contents. No POD markup will be returned. Pod::string ----------- This object contains plain ASCII strings. Note that the contents can well include angle brackets (`<>'). When converted into POD code, these are automatically escaped where necesary. The new constructor takes an optional argument: the string. $string->content( $text ) Set/retrieve the string's contents. Pod::bold --------- This class represents the `B<...>' (bold) interior sequence. Pod::italic ----------- This class represents the `I<...>' (italic) interior sequence. Pod::code --------- This class represents the `C<...>' (code/courier) interior sequence. Pod::file --------- This class represents the `F<...>' (file) interior sequence. Pod::nonbreaking ---------------- This class represents the `S<...>' (nonbreaking space) interior sequence. Pod::zero --------- This class represents the `Z<>' (zero width character) interior sequence. Note that this sequence cannot have children. Pod::idx -------- This class represents the `X<...>' (index) interior sequence. The text therein is not printed in the resulting manpage, but is supposed to appear in an index with a hyperlink to the place where it occurred. $idx->node() $idx->*nodeid*() $idx->*nodetext*() See `"Pod::head"' in this node for the description of these methods. Pod::entity ----------- This class represents the `E<...>' (entity) interior sequence. This object has no children, just a value. Entities encountered in the POD source that map to standard ASCII characters (most notably lt, gt, `sol' and `verbar') are not kept as entities, but converted into or appended to the preceding Pod::string, but only if the nesting of this entity permits. Entities may be specified as textual entities (`auml', `szlig', etc.), or a numeric. The usual Perl encodings are valid here: 123 is decimal, `0x3a' is hexadecimal, `0177' is octal. The new constructor takes an optional argument, namely the numeric code of the entity to create. The as_text method returns the corresponding ISO-8859-1 (Latin-1) character. Sorry, no unicode support yet. $entity->decode( $string ) This method can be given any type of entity encoding and sets the entity value to the resulting code. This code is undef if the given string was not recognized. $entity->value( $num ) Sets/retrieves the numeric value of this entity. $entity->*as_pod*() Returns the POD representation of this entity. If a textual encoding like `auml' is known for the value it is used, otherwise decimal encoding. Pod::link --------- This is a class for representation of POD hyperlinks. The code to parse the corresponding POD code is entirely in *Pod::Compiler*. Pod::link->new() The new() method can be passed a set of key/value pairs for one-stop initialization. $link->as_text() This method returns the textual representation of the hyperlink as above, but without markers (read only). Depending on the link type this is one of the following alternatives (links to same or other POD document): page: L the perl manpage item: L the $! entry in the perlvar manpage item: L the DESTOY entry elsewhere in this document head: L the section on OPTIONS in the perldoc manpage head: L<"DESCRIPTION"> the section on DESCRIPTION elsewhere in this document The following are not offical, but are supported: man: L the sed(1) manpage url: L http://www.perl.com (same for ftp: news: mailto:) If an alternative text (`L') was specified, this text (without POD markup) is returned. All POD formatters should use the same text for the different types of links. Clever formatters create two hyperlinks for item or section links to another page: one to the top of the page (the page name) and one to the node within the page (the node name). $link->page() This method sets or returns the POD page this link points to. If empty, the link points to the current document itself. $link->node() As above, but the destination node text (either head or item) of the link. $link->*alttext*() Sets or returns an alternative text specified in the link. $link->type() The node type, either page, man, head or item. As an unofficial type, there is also url, derived from e.g. `L' $link->*mansect*() The node type, either page, man, head or item. As an unofficial type, there is also url, derived from e.g. `L' $link->*as_pod*() Returns the link as `L<...>'. ADDITIONAL CLASSES ================== The following classes to not inherit from any other package and serve as a convenience storage for POD-related data. Pod::node --------- This class stores information about a POD node, i.e. a potential hyperlink destination. This is derived from `=headX', =item and `X<...>' entries. See also `"Pod::node::collection"' in this node. Pod::node->new( %params ) Creates a new instance of Pod::node. Optional parameters are text, id, type. See below. $node->text( $string ) Sets/retrieves the node's text. The text is a plain string without any POD markup in ISO-8859-1 encoding. $node->id( $string ) Sets/retrieves the node's unique id. The id is a string that is unique in the POD document and can be used as a hyperlink anchor. $node->type( $string ) Sets/retrieves the node's type, which is either `headX' (X being a number), item or X, depending on from which POD construct this node was derived. $node->*was_hit*() Increments the number of hits to this node. Should be called whenever a link was resolved to this node. $node->hits() Retrieves the number of hits on this node. Pod::node::collection --------------------- This class is merely an array that holds Pod::nodes. It provides some methods to search in this set of nodes. $ncollection->all() Return an array of all nodes. Nodes are instances of Pod::node. $ncollection->add( @nodes ) Add the given nodes to the collection. A fatal error occurs when trying to add non-Pod::nodes to the collection. Returns true. $ncollection->*get_by_text*( $string ) Returns an array of nodes or the first matching node (depending on context) that exactly matches the node text. The return value should normally be either the empty array or undef for no match and exactly one element that matches, unless several nodes with the same text are in the collection, which should never occur. $ncollection->*get_by_rx*( $regexp ) Same as above, but get the node by matching the given *$regexp* on the node text. A fatal error occurs if the regexp has syntax errors. $ncollection->*get_by_id*( $string ) Same as above, but get the node by its unique id. $ncollection->*get_by_type*( $string ) Same as above, but get the node by its type. The string is treated as a regexp, so you can get all `=head' nodes by specifying `"head"' or all =head1 nodes by giving "head1". $ncollection->ids() Return an array of all node ids. $ncollection->*texts*() Return an array of all node texts. Pod::doc -------- A convenience class for storing POD document information, especially by converters. See also `Pod::doc::collection' in this node. Pod::doc->new( %params ) Create a new instance of Pod::doc, assigning the given optional parameters. See below for the parameter names, they are identical with the accessor methods. $doc->name( $string ) Set/retrieve the canonical name of the POD document, e.g. perldoc or `Pod::Compiler'. $doc->source( $file ) Set/retrieve the source file name of the POD document, e.g. `/usr/local/bin/perldoc' or `/usr/local/lib/perl5/site_perl/Pod/Compiler.pm'. $doc->*temp*( $file ) Set/retrieve the temporary file name of the POD document (to be created by (Pod::root object)->store), e.g. `/tmp/perldoc.tmp' or `/tmp/Pod__Compiler.tmp'. You have to "invent" a method for generating temp filenames yourself, see also *Note File/Temp: File/Temp,. $doc->*destination*( $file ) Set/retrieve the destination file name of the POD document, e.g. `/usr/local/share/perl/html/perldoc.html' or `/usr/local/share/perl/Pod/Compiler.html'. $doc->*nodes*( $nodecollection ) Set/retrieve the this POD document's node collection. When setting, the given argument must be a Pod::node::collection object, otherwise a fatal error occurs. Pod::doc::collection -------------------- This class serves as a container for a set of Pod::doc objects and defines some methods for such a collection. This object is simply a hash with the canonical POD name as key and the corresponding Pod::doc object as value. Pod::doc::collection->new() Create a new collection instance. $dcollection->*all_names*() Return an array of all sorted documents names in the collection. $dcollection->*all_objs*() Return an array of all Pod::docs in the collection. There is no specific sort order. $dcollection->get( $name ) Return the Pod::doc object associated with the name $name or undef if no such name is in the collection. $dcollection->add( $name , $object ) $dcollection->add( $object ) Add the given Pod::doc object to the collection. The two-argument form explicitely sets the name to $name, otherwise the objects name is used. Exceptions occur if arguments are missing or have the wrong type or the name is empty. $dcollection->*resolve_link*( $link , $name ) This method tries to resolve the given link (object of class Pod::link) in the document named $name within the document collection. Returns the Pod::doc and the Pod::node in case of success. If the node was found in the current POD (defined by $name) then the first return value will be the empty string. If a node was found, its hit count is automatically incremented. Example: my ($page,$node) = $dcollection->resolve_link( $link, $myname ); unless(defined $page) { warn "Error: Cannot resolve link.\n"; } elsif(!$page) { # node is in the current POD $myname } else { # link to another POD } SEE ALSO ======== *Note Pod/Compiler: Pod/Compiler,, *Note Pod/Parser: Pod/Parser,, *Note Pod/Find: Pod/Find,, *Note Pod/Checker: Pod/Checker, AUTHOR ====== Marek Rouchal  File: pm.info, Node: Pod/test, Next: Pogo, Prev: Pod/objects, Up: Module List * * bolditalic**bold-italic** X X `a\bc' in this node `$;' in this node Y X<*abc*;abc/def> Back in pod. This is a verbatim paragraph * foo bar bletch This is an item. Back to paragraphs. * foobar bletch.  File: pm.info, Node: Pogo, Next: Pogo.jp, Prev: Pod/test, Up: Module List Perl GOODS interface ******************** NAME ==== Pogo - Perl GOODS interface SYNOPSIS ======== use Pogo; $pogo = new Pogo 'sample.cfg'; # connect to a database $root = $pogo->root_tie; # get a reference to root hash in the database $root->{key1} = "string"; # store a string into the database $value = $root->{key1}; # $value is "string" $root->{key2} = [1,2,3]; # store a array into the database $arrayref = $root->{key1}; # get a reference to array in the database $value = $root->{key2}->[0]; # $value is 1 $root->{key3} = {a=>1,b=>2}; # store a hash into the database $hashref = $root->{key3}; # get a reference to hash in the database $value = $root->{key3}->{b}; # $value is 2 $root->{key4} = new Pogo::Btree;# make a B-tree hash $hashref = $root->{key5}; # B-tree is accessed as hash $root->{key5} = new Pogo::Htree;# make a H-tree(see below) hash $hashref = $root->{key6}; # H-tree is accessed as hash $root->{key6} = new Aclass; # store a object into the database $obj = $root->{key4}; # $obj is a Aclass object in the database DESCRIPTION =========== Basic feature ------------- Pogo is a Perl interface of GOODS (Generic Object Oriented Database System). Pogo maps Perl's scalars, arrays, hashes and objects directly to the database objects. Pogo has the data types as follows. - scalar - array - hash - H-tree (hash that hash entry table is placed as B-tree) - B-tree The value of a scalar data or an element of a collection type data is a string or a reference to another data. Pogo uses Perl's tieing mechanism and provide transparent accessibility to persistent data in the database. Each data in the database can have class name string internally, so Perl objects (i.e. reference which is blessed by a class name) can be stored in the database. GOODS server ------------ GOODS which is the base of Pogo is a client-server type database. A Pogo application needs a running GOODS server process in the same machine or another machine which is connected with TCP/IP network. The GOODS server program is 'goodsrv' which is installed in /usr/local/goods/bin/. The Pogo application and the corresponding goodsrv must use the same TCP port to communicate with each other, so both use the same configuration file which specifies goodsrv's hostname and TCP port number. The configuration file must have a filename extension '.cfg'. Typical configuration file for a local goodsrv as follows. 1 0: localhost:6100 The '1' at the first line means that this database uses one goodsrv (two or more goodsrv's are available but Pogo uses always one). The '0: localhost:6100' at the second line means that first goodsrv is at localhost and uses port number 6100. If this configuration file is saved as 'test.cfg', goodsrv can be executed as follows. goodsrv test And the goodsrv creates a set of database files as follows. You must NOT delete or edit directly these database files. test.his test.idx test.log test.map test.odb The running goodsrv waits commands from your console while providing database services through the specified TCP port. You can see the database statistics or backup the database by sending commands to the running goodsrv. See readme.htm of GOODS. For practical use, goodsrv will be executed as a background process. Pogo has two utility scripts for starting goodsrv at the background and sending commands to the goodsrv. To start goodsrv with test.cfg, type: startgoodsrv test & This goodsrv's outputs are saved in test.goodsrv.log. And to terminate goodsrv, type: cmdgoodsrv test exit Tie interface ------------- Connect First of all, connect to a running GOODS server. $pogo = new Pogo $cfgfilename; The $cfgfilename is a configuration filename which specifies GOODS server. The gotten Pogo object will be used after. *Get root* Then, get a hash reference to the root B-tree data in the database. $root = $pogo->root_tie; NOTE: A persistent data in a GOODS database must be refered by another persistent data. If a data is not refered by another persistent data, it will be recovered by the GOODS garbage collection system. It means that at least one absolutely persistent data is necessary in each database. Such data is called 'root'. Pogo database's root is a B-tree data. The root_tie method returns a hash reference to the root B-tree data in the database. *String and number* To store a data into the database, simply assign a perl data through $root. Note that $root is a hash reference. $root->{key} = "value"; $root->{pi} = 3.14; NOTE: Data value strings in the Pogo database can include null character ("\x00"). But hash key strings in the Pogo database cannot include null character. NOTE: The number 3.14 is stored as string "3.14" in the database. (This data conversion is an overhead. In the future revision of Pogo, it will be stored as number.) Now, you can get the values of the data in the database. $value = $root->{key}; # $value is "value" $pi = $root->{pi}; # $pi is "3.14" *Array and hash* To store an array or a hash, assign its reference. $root->{key1} = \@array; $root->{key2} = [1,2,3]; $root->{key3} = \%hash; $root->{key4} = {a=>1,b=>2,c=>3}; $root->{key5} = {a=>[1,2],b=>{c=>3,d=>4}}; Note that these assignments cause storing the contents of the array or hash into the database, not only the reference. Because a persistent data in a database cannot refer to a non persitent (i.e. only on memory) data. That is to say, the array or hash is copied into the database and its reference is assigned. In the above example, changing @array or %hash after assignment does not change the array of $root->{key1} or the hash of $root->{key3}. To fetch the value, normally use ->,[],{}'s. $value = $root->{key5}->{a}->[1]; # $value is 2 $value = $root->{key5}{a}[1]; # -> between {} or [] can be omitted If the specfied value is a reference to another data in the database, an appropriate type reference is returned. You can use such references to store into and fetch from the database. $hashref = $root->{key4}; # get a hash reference in the database $hashref->{d} = 4; # store a data $value = $hashref->{c}; # $value is 3 NOTE: A CODE or IO reference cannot be stored into the database. *Array size* Pogo's array is automatically enlarged when needed. But the enlargement causes reassignment of the data in the database. When an array reference is assigned, the array size in the database is set to the size of the assigned array. If you can estimate the maximum array size, setting the array size beforehand is recommended. To make a specified size array, use Pogo::Array::new method. $root->{sqrt} = new Pogo::Array 1000; for(0..999) { $root->{sqrt}->[$_] = sqrt $_; } *Hash size* Pogo's hash has a static size hash entry table and cannot resize it. Note that the hash entry table size does not limit numbers of stored keys. But if too many keys against the hash entry table size are stored into a Pogo's hash, it will slow down. So choose appropriate hash entry table size for your purpose of using hash. (In the future revision of Pogo, automatic hash resizing will be supported.) When a hash reference is assigned, the hash entry table size in the database is set to it of the assigned hash. To make a hash of specified hash entry table size, use Pogo::Hash::new method. $root->{smallhash} = new Pogo::Hash 8; $root->{largehash} = new Pogo::Hash 1024; If the size defaults, 256 is used. *H-tree* A hash entry table of Pogo's hash is a static size of array, so too large table size is not useful. If you want to use very large hash, use H-tree. A hash entry table of H-tree is placed as B-tree, so huge size table is available. To make a H-tree hash of specified hash entry table size, use Pogo::Htree::new method. $root->{hugehash} = new Pogo::Htree 131072; If the size defaults, 65536 is used. *B-tree* Another way to make huge hash is to use B-tree. In B-tree, a hash key itself is used as B-tree key. So hash keys are sorted automatically. And B-tree has no hash entry table size problem. On the other hand, the key indexes of Pogo's B-tree is made by the first 8 bytes of the hash key string. So if many keys have same first 8 bytes, searching such keys slows down. To make a B-tree hash, use Pogo::Btree::new method. $root->{btree} = new Pogo::Btree; Note that no size is required. By the tie interface of Pogo, you cannot search key that partially matches the specified string. You can do it by Pogo::tied_object function and Pogo::Btree::find_key method. $foundkey = Pogo::tied_object($root->{btree})->find_key($string); Pogo::tied_object returns the behind object which is tied to the specified data's referent. If $root->{btree} is a B-tree, Pogo::tied_object($root->{btree}) returns a Pogo::Btree object. And Pogo::Btree::find_key method returns a key string that matches front-partially to the specified string. *N-tree* By B-tree, key string is sorted as character string. So '10' is smaller than '2'. By N-tree, key string is sorted as long integer. So '2' is smaller than '10'. Except this feature, N-tree is same as B-tree. $root->{ntree} = new Pogo::Ntree; Object A Perl object which uses only SCALAR/ARRAY/HASH references can be stored into the database. sub Foo::new { bless {name => $_[1]}, $_[0]; } sub Foo::name { $_[0]->{name}; } $root->{obj} = new Foo "bar"; $obj = $root->{obj}; # $obj is a Foo object $name = $obj->name; # $name is "bar" If you want to set hash entry table size or use H-tree or B-tree for a object, use Pogo::Hash::new_tie, Pogo::Htree::new_tie or Pogo::Btree::new_tie method. sub Bar::new { my($class, $name) = @_; my $self = new_tie Pogo::Htree 10000; $self->{name} = $name; bless $self, $class; } Note that a class using Pogo::*::new_tie is only for using with Pogo database. Transaction Pogo has a transaction mechanism. If there is a sequence of operations with a database and you want to make it atomic, use transaction mechanism. The term 'atomic' means that the sequence of operations are all done successfully or nothing is done. It means also that another database client cannot interrupt the sequence. To make a per database transaction, use Pogo::begin_transaction, Pogo::abort_transaction and Pogo::end_transaction methods. $root->{key} = 1; $pogo->begin_transaction; $root->{key} = 2; $pogo->abort_transaction; # abort: cancel above assignment $value = $root->{key}; # $value is 1 $pogo->begin_transaction; $root->{key} = 3; $pogo->end_transaction; # end: above assignment is valid $value = $root->{key}; # $value is 3 Note that these methods must be called through a concrete Pogo object. Calling as class method is not available. This transaction locks a whole database. So a long time transaction lowers concurrent database access performance. To make a per data transaction, use Pogo::atomic_call method. $root->{key} = \@array; Pogo::atomic_call(\&sortarray, $root->{key}); sub sortarray { my $aref = shift; @$aref = sort @$aref; } While calling sortarray, $root->{key} is locked. So another databse client cannot disturb the sorting. And the sorting is done without halfway fail. An abortion by the user is not supported for a per data transaction. *Passive action* If you need a script which watches a data in the database and does some jobs when the data is modified by another database client, use Pogo::wait_modification function. $result = Pogo::wait_modification($root->{key}, 5); When this sentence is executed, execution stops until the data $root->{key} is modified by another database client or 5 seconds passes. $result is 1 by data modification, 0 by timeout. If the timeout seconds defaults, it waits forever. Database browser ---------------- Pogo has a database browsing script 'browse'. To browse the database of test.cfg, type: browse test Then browse displays as follows and wait for your command. test.cfg opened root=(HASH(Btree)(10000))> Type 'ls' to list the root B-tree hash contents. It displays as follows for example. For a reference to another data, it displays class name, data type and object id. {aobj} = Aclass(HASH(Hash)(1012d)) {index} = (HASH(Btree)(10282)) {list} = (ARRAY(10036)) {name} = "test" Type 'cd index' to change current data to $root->{index}. Then the prompt is changed as follows for example. root{index}=(HASH(Btree))> Type 'cd' to return root. Type 'cd ..' to change to parent. And type 'exit' to terminate browse. Methods ------- All but indicated as 'class method' are object methods. The symbol [] means optional argument. $pogo = Pogo->new [config_filename] Class method. This makes and returns a Pogo object. If specified config_filename, connect to the running GOODS server which is specified by config_filename. The corresponding GOODS server must be already running. $pogo->open config_filename If a Pogo object does not connect to the GOODS server yet, this method does it. $pogo->close This disconnects to the GOODS server. You may not use this method, because it is called when the Pogo object is destroyed automatically. $pogo->root This makes and returns a Pogo::Btree object corresponding to the root B-tree. $pogo->root_tie This makes and returns a reference to a hash which is tied to a Pogo::Btree object corresponding to the root B-tree. $pogo->begin_transaction This starts a database global transacion. $pogo->abort_transaction This aborts the transacion which was started by Pogo::begin_transaction. $pogo->end_transaction This ends the transacion which was started by Pogo::begin_transaction. $obj = Pogo::Scalar->new [pogoobj] Class method. Makes and returns a Pogo::Scalar object. If Pogo object pogoobj is specified, the created object is stored the database. $scalarref = Pogo::Scalar->new_tie [pogoobj [,class]] Class method. Makes a Pogo::Scalar object and ties a scalar to it and returns a reference to the tied scalar. If Pogo object pogoobj is specified, the created object is stored the database. If class name class is specified, the reference is blessed by the class. $obj = Pogo::Array->new [size [,pogoobj]] Class method. Makes and returns a Pogo::Array object of specified size. If size defaults, 1 is used. If Pogo object pogoobj is specified, the created object is stored the database. $arrayref = Pogo::Array->new_tie [size [,pogoobj [,class]]] Class method. Makes a Pogo::Array object of specified size and ties a array to it and returns a reference to the tied array. If size defaults, 1 is used. If Pogo object pogoobj is specified, the created object is stored the database. If class name class is specified, the reference is blessed by the class. $obj = Pogo::Hash->new [size [,pogoobj]] Class method. Makes and returns a Pogo::Hash object of specified hash entry table size. If size defaults, 256 is used. If Pogo object pogoobj is specified, the created object is stored the database. $hashref = Pogo::Hash->new_tie [size [,pogoobj [,class]]] Class method. Makes a Pogo::Hash object of specified hash entry table size and ties a hash to it and returns a reference to the tied hash. If size defaults, 256 is used. If Pogo object pogoobj is specified, the created object is stored the database. If class name class is specified, the reference is blessed by the class. $obj = Pogo::Htree->new [size [,pogoobj]] Class method. Makes and returns a Pogo::Htree object of specified hash entry table size. If size defaults, 65536 is used. If Pogo object pogoobj is specified, the created object is stored the database. $hashref = Pogo::Htree->new_tie [size [,pogoobj [,class]]] Class method. Makes a Pogo::Htree object of specified hash entry table size and ties a hash to it and returns a reference to the tied hash. If size defaults, 65536 is used. If Pogo object pogoobj is specified, the created object is stored the database. If class name class is specified, the reference is blessed by the class. $obj = Pogo::Btree->new [pogoobj] Class method. Makes and returns a Pogo::Btree object. If Pogo object pogoobj is specified, the created object is stored the database. $hashref = Pogo::Btree->new_tie [pogoobj [,class]] Class method. Makes a Pogo::Btree object and ties a hash to it and returns a reference to the tied hash. If Pogo object pogoobj is specified, the created object is stored the database. If class name class is specified, the reference is blessed by the class. $obj = Pogo::Ntree->new [pogoobj] Class method. Makes and returns a Pogo::Ntree object. If Pogo object pogoobj is specified, the created object is stored the database. $hashref = Pogo::Ntree->new_tie [pogoobj [,class]] Class method. Makes a Pogo::Ntree object and ties a hash to it and returns a reference to the tied hash. If Pogo object pogoobj is specified, the created object is stored the database. If class name class is specified, the reference is blessed by the class. NOTE: An object created by these Pogo::*::new and Pogo::*::new_tie is on the memory unless Pogo object is specified as an argument, not yet persistent. When it is assigned into a existing persistent data in a database, it becomes persistent. When Pogo object is specified as an argument, the gotten object is stored in the database, but it is not yet persistent too. When it is refered by a existing persitent data in the database, it becomes persistent. Utility functions ----------------- Pogo::type_of This returns an array of reference type, class name, tied class name of the specfied data. ($reftype, $class, $tiedclass) = Pogo::type_of($root->{key}); Typical return values are: () : not a reference ('ARRAY', '', 'Pogo::Array') : an array ('HASH', '', 'Pogo::Btree') : a B-tree hash ('HASH', 'Aclass', 'Pogo::Hash') : an Aclass object Pogo::tied_object This returns a Pogo::* object which is tied to the referent of the specified Pogo data. Pogo::equal This requires two arguments of Pogo data and returns 1 if its datatabase objects are same, 0 if different. Pogo::object_id This returns a database object id of the specified Pogo data. Pogo::atomic_call This calls the specified function atomicly and returns its return value. $result = Pogo::atomic_call(\&func, $data, @args); The first argument \&func is a reference to a subroutine. The second argument $data is a Pogo data. This data is locked between calling. This is same as below exept the locking. $result = func($data, @args); The func is called in a scalar context, and returned value is convert to a integer number. Pogo::wait_modification This waits the modification of the specified data by another database client until the specified seconds passes. And returns 1 by data modification, 0 by timeout. $result = Pogo::wait_modification($data, $sec); If the timeout seconds defaults, it waits forever. Raw methods ----------- These methods below are used by the tie interaface internally. Pogo::Var Pogo::Var is a abstract base class of all Pogo::* classes below. No Pogo::Var object is available. Pogo::Var::get_class Pogo::Var::set_class Pogo::Var::begin_transaction Pogo::Var::abort_transaction Pogo::Var::end_transaction Pogo::Var::call Pogo::Var::equal Pogo::Var::wait_modification Pogo::Var::object_id Pogo::Scalar Pogo::Scalar::get Pogo::Scalar::set Pogo::Array Pogo::Array::get Pogo::Array::set Pogo::Array::get_size Pogo::Array::set_size Pogo::Array::clear Pogo::Array::push Pogo::Array::pop Pogo::Array::insert Pogo::Array::remove Pogo::Hash Pogo::Hash::get Pogo::Hash::set Pogo::Hash::exists Pogo::Hash::remove Pogo::Hash::clear Pogo::Hash::first_key Pogo::Hash::next_key Pogo::Htree Pogo::Htree::get Pogo::Htree::set Pogo::Htree::exists Pogo::Htree::remove Pogo::Htree::clear Pogo::Htree::first_key Pogo::Htree::next_key Pogo::Btree Pogo::Btree::get Pogo::Btree::set Pogo::Btree::exists Pogo::Btree::remove Pogo::Btree::clear Pogo::Btree::first_key Pogo::Btree::last_key Pogo::Btree::next_key Pogo::Btree::prev_key Pogo::Btree::find_key AUTHOR ====== Sey Nakajima SEE ALSO ======== readme.htm of GOODS