This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Register, Next: Register/Generic, Prev: Regexp/Shellish, Up: Module List simple implementation of the Win32 registry in Unix *************************************************** NAME ==== Register - simple implementation of the Win32 registry in Unix SYNOPSIS ======== use Register; DESCRIPTION =========== Register is simply the main package to run registry option you can see : * Register::System AUTHOR ====== Vecchio Fabrizio SEE ALSO ======== *Note Register/System: Register/System,,*Note DBD/CSV: DBD/CSV,,`DBI' in this node  File: pm.info, Node: Register/Generic, Next: Register/System, Prev: Register, Up: Module List Implementation of the windows ini like structure ************************************************ NAME ==== Register::Generic - Implementation of the windows ini like structure SYNOPSIS ======== use Register; $genreg=new Register::Generic ( 'regpath' => "/home/myprog", 'regname' => "INITFILE" ); $genreg->savesettings("SECTION","KEY","VALUE"); $value=$genreg->getsettings("SECTION","KEY"); $sections=$genreg->getsections; $genreg->deletesettings(,"SECTION","KEY"); $genreg->deletesection("SECTION"); DESCRIPTION =========== The Register::Generic module permit to create an ini file like Windows for save generic information about your program. With the use of CSV dbd , the file created is readable by DBI without problem. Here CSV table specifics: FIELD_NAME FIELD_TYPE ---------------------------------- R_SECTION CHAR R_KEY CHAR R_VALUE CHAR FUNCTIONS ========= Function -------------- The statament create the Register::Generic object and return the reference to him. $genreg=new Register::System ( 'regpath' => "/home/myprog", 'regname' => "INIFILE" ); Parameter : regpath specify the path where new statament search for file. regname specify the name of the file to use. Finaly if regpath don't exist the program return an error message at compile time, if the register don't exist it is maked. Function ----------------------- The savesettings function , save the value argument in the key of the section of the program. $genreg->savesettings("SECTION","KEY","VALUE"); If the key don't exist it make (it make also section without specify befor), else if key already exist and value is different from previous it update value. Function ---------------------- The getsettings function retrieve the value of the specified key. $value=$genreg->getsettings("SECTION","KEY"); Function ---------------------- The getsections function retrieve the section in the ini file and return an array. @sections=$genreg->getsections; Function ------------------------- The deletesettings function delete the entry key specified. $genreg->deletesettings("SECTION","KEY"); Function ------------------------ The deletesection function delete the entry section specified. $genreg->deletesection("SECTION"); AUTHOR ====== Vecchio Fabrizio SEE ALSO ======== *Note Register: Register,,*Note DBD/CSV: DBD/CSV,,`DBI' in this node  File: pm.info, Node: Register/System, Next: Religion, Prev: Register/Generic, Up: Module List Implementation of the Win32 registry in Unix ******************************************** NAME ==== Register::System - Implementation of the Win32 registry in Unix SYNOPSIS ======== use Register; $sysreg=new Register::System ( 'regpath' => "/etc", 'regname' => "SYSREG" ); $sysreg->savesettings("APPLICATION","SECTION","KEY","VALUE"); $value=$sysreg->getsettings("APPLICATION","SECTION","KEY"); $sysreg->deletesettings("APPLICATION","SECTION","KEY"); $sysreg->deletesection("APPLICATION","SECTION"); DESCRIPTION =========== The Register::System module permit to create a registry file like Windows for save global information about your program. With the use of CSV dbd , the file created is readable by DBI without problem. Here CSV table specifics: FIELD_NAME FIELD_TYPE ---------------------------------- R_APPLICATION CHAR R_SECTION CHAR R_KEY CHAR R_VALUE CHAR FUNCTIONS ========= Function -------------- The statament create the Register::System object and return the reference to him. $sysreg=new Register::System ( 'regpath' => "/etc", 'regname' => "SYSREG" ); Parameter : regpath specify the path where new statament search for registers. regname specify the name of the register to use. Finaly if regpath don't exist the program return an error message at compile time, if the register don't exist it is maked. Function ----------------------- The savesettings function , save the value argument in the key of the section of the program. $sysreg->savesettings("APPLICATION","SECTION","KEY","VALUE"); If the key don't exist it make (it make also application and section without specify befor), else if key already exist and value is different from previous it update value. Function ---------------------- The getsettings function retrieve the value of the specified key. $value=$sysreg->getsettings("APPLICATION","SECTION","KEY"); Function ------------------------- The deletesettings function delete the entry key specified. $sysreg->deletesettings("APPLICATION","SECTION","KEY"); Function ------------------------ The deletesection function delete the entry section specified. $sysreg->deletesection("APPLICATION","SECTION"); AUTHOR ====== Vecchio Fabrizio SEE ALSO ======== *Note Register: Register,,*Note DBD/CSV: DBD/CSV,,`DBI' in this node  File: pm.info, Node: Religion, Next: Remedy/Ar, Prev: Register/System, Up: Module List Generate tracebacks and create and install die() and warn() handlers. ********************************************************************** NAME ==== Religion - Generate tracebacks and create and install die() and warn() handlers. DESCRIPTION =========== This is a second go at a module to simplify installing die() and warn() handlers, and to make such handlers easier to write and control. For most people, this just means that if use `use Religion;' then you'll get noticably better error reporting from warn() and die(). This is especially useful if you are using eval(). Religion provides four classes, WarnHandler, DieHandler, WarnPreHandler, and DiePreHandler, that when you construct them return closures that can be stored in variables that in turn get invoked by $SIG{__DIE__} and $SIG{__WARN__}. Note that if Religion is in use, you should not modify $SIG{__DIE__} or $SIG{__WARN__}, unless you are careful about invoking chaining to the old handler. Religion also provides a TraceBack function, which is used by a DieHandler after you `die()' to give a better handle on the current scope of your situation, and provide information about where you were, which might influence where you want to go next, either returning back to where you were, or going on to the very last. [Sorry - Ed.] See below for usage and examples. USAGE ===== DieHandler SUB Invoke like this: $Die::Handler = new DieHandler sub { #... }; where `#...' contains your handler code. Your handler will receive the following arguments: $message, $full_message, $level, $eval, $iline, $ifile, $oline, $ofile, $oscope `$message' is the message provided to die(). Note that the default addition of " at FILE line LINE.\n" will have been stripped off if it was present. If you want to add such a message back on, feel free to do so with $iline and $ifile. `$full_message) is the message with a scope message added on if there was no newline at the end of C<$message'. Currently, this is not the original message that die() tacked on, but something along the lines of " at line 3 of the eval at line 4 of Foo.pl\n". `$eval' is non-zero if the die() was invoked inside an eval. The rest of the arguments are explained in the source for Religion::TraceBack. Yes, I need to document these, but not just now, for they are a pain to explain. Whenever you install a DieHandler, it will automatically store the current value of $Die::Handler so it can chain to it. If you want to install a handler only temporarily, use local(). If your handler returns data using return or by falling off the end, then the items returns will be used to fill back in the argument list, and the next handler in the chain, if any, will be invoked. *Don't fall off the end if you don't want to change the error message.* If your handler exits using last, then no further handlers will be invoked, and the program will die immediatly. If your handler exits using next, then the next handler in the chain will be invoked directly, without giving you a chance to change its arguments as you could if you used return. If your handler invokes die(), then die() will proceed as if no handlers were installed. If you are inside an eval, then it will exit to the scope enclosing the eval, otherwise it will exit the program. WarnHandler SUB Invoke like this: $Warn::Handler = new WarnHandler sub { #... }; For the rest of its explanation, see DieHandler, and subsitute warn() for die(). Note that once the last DieHandler completes (or C is invoked) then execution will return to the code that invoked warn(). DiePreHandler SUB Invoke like this: $Die::PreHandler = new DiePreHandler sub { #... }; This works identically to $Die::Handler, except that it forms a separate chain that is invoked I the DieHandler chain. Since you can use C to abort all the handlers and die immediately, or change the messages or scope details, this can be useful for modifying data that all future handlers will see, or to dispose of some messages from further handling. This is even more useful in $Warn::PreHandler, since you can just throw away warnings that you *know* aren't needed. WarnPreHandler SUB Invoke like this: $Warn::PreHandler = new WarnPreHandler sub { #... }; This works identically to $Warn::Handler, except that it forms a separate chain that is invoked I the WarnHandler chain. Since you can use C to abort all the handlers and return to the program, or change the messages or scope details, this can be useful for modifying data that all future handlers will see, or to dispose of some messages. This is very useful, since you can just throw away warnings that you *know* aren't needed. EXAMPLES ======== A dialog error message: $Die::Handler = new DieHandler sub { my($msg,$fmsg,$level,$eval) = @_; if($eval) { # if we are in an eval, skip to the next handler next; } else { # show a message box describing the error. print "ShowMessageBox $fmsg"; # force the program to exit exit 0; next; } }; A handler that changes die() messages back to the original format local($Die::Handler) = new DieHandler sub { my($msg,$fmsg,$level,@trace) = @_; $fmsg = $msg . ((substr($msg,-1,1) ne "\n") ? " at $trace[2] line $trace[1].\n" : ""); return ($msg,$fmsg); }; A warn handler that does nothing. $Warn::Handler = new WarnHandler sub {next;}; A warn prehandler that throws away a warning. $Warn::PreHandler = new WarnPreHandler sub { my($msg,$fmsg,$level,$eval) = @_; if($msg =~ /Use of uninitialized/) { last; } next; };  File: pm.info, Node: Remedy/Ar, Next: RenderMan, Prev: Religion, Up: Module List Interface to Remedy's Action Request (Version 1.2) ************************************************** NAME ==== Remedy::Ar - Interface to Remedy's Action Request (Version 1.2) DESCRIPTION =========== Terminology ----------- Action Request uses terminology which may not be familiar to some people. Action Request can be viewed as graphical interface to a RDB (although flat files can also be used at the backend). A schema is roughly equivalent to a table in other database terminology. In the graphical interface only fields from one schema can be present (although it is possible to fill some fields from other schema. An entry is equivalent to a record. Data structures --------------- $control This is a private tag which is used to keep track of multiple connections. The newcontrol() returns a new $control tag, which can then be used for all other operations. $schema The name of a schema to operate on. $server The name of a server to connect to. $entryId A unique string representing an individual entry. Once you have an $entryId, you can use it with GetEntry to retrieve detailed information about the record. $fieldList A $fieldList is a reference to an associative array containing field name/contents pairs. The field name used is the label displayed for the schema, using the default display tag. Entry Operations ---------------- $entryId = CreateEntry($control, $schema, $fieldList) Adds a new entry to the specified schema. (Not Yet Implemented) DeleteEntry($control, $schema, $entryId) Removes an entry from the specified schema. This action requires administrator access. (Not Yet Implemented) $fieldList = GetEntry($control, $schema, $entryId) Returns all fields from the entry associated with $entryId in $schema. SetEntry (Not Yet Implemented) GetListEntry($control, $schema, $qualifier, $maxRetrieve) MergeEntry (Not Yet Implemented) Schema Operations ----------------- CreateSchema (Not Yet Implemented) DeleteSchema (Not Yet Implemented) GetSchema(control, schema) SetSchema (Not Yet Implemented) GetListSchema(control, changedSince) Field Operations ---------------- CreateField (Not Yet Implemented) DeleteField (Not Yet Implemented) GetField(control, schema, fieldId) SetField (Not Yet Implemented) GetListField(control, schema, changedSince) Menu Operations --------------- CreateCharMenu (Not Yet Implemented) DeleteCharMenu (Not Yet Implemented) ExpandCharMenu (Not Yet Implemented) GetCharMenu (Not Yet Implemented) SetCharMenu (Not Yet Implemented) GetListCharMenu (Not Yet Implemented) Filter Operations ----------------- CreateFilter (Not Yet Implemented) DeleteFilter (Not Yet Implemented) GetFilter (Not Yet Implemented) SetFilter (Not Yet Implemented) GetListFilter (Not Yet Implemented) Active Link Operations ---------------------- CreateActiveLink (Not Yet Implemented) DeleteActiveLink (Not Yet Implemented) GetActiveLink (Not Yet Implemented) SetActiveLink (Not Yet Implemented) GetListActiveLink (Not Yet Implemented) AdminExt Operations ------------------- CreateAdminExt (Not Yet Implemented) DeleteAdminExt (Not Yet Implemented) GetAdminExt (Not Yet Implemented) SetAdminExt (Not Yet Implemented) GetListAdminExt (Not Yet Implemented) ExecuteAdminExt (Not Yet Implemented) Miscellaneous Operations ------------------------ VerifyUser(control) GetListServer() Export (Not Yet Implemented) Import (Not Yet Implemented) GetListGroup(control) GetServerInfo (Not Yet Implemented) SetServerInfo (Not Yet Implemented) DecodeStatusHistory (Not Yet Implemented) DecodeDiary (Not Yet Implemented) LoadARQualifierStruct(control, schema, qualString) Miscellaneous Support Functions (Not part of the AR API) -------------------------------------------------------- newcontrol() printcontrol(control) setuser(control, user, password) setlanguage(control, language) setserver(control, server) AUTHOR ====== Copyright (c) 1995 Rik Harris (*rik.harris@fulcrum.com.au*). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The Ar perl extension, and this documentation were derived from the information found in the Action Request include files, and the Action Request System Programmer's Guide (Remedy Part Number: AXA-120-DA4-01). Action Request System and AR System are tracemarks of Remedy Corporation.  File: pm.info, Node: RenderMan, Next: Resources, Prev: Remedy/Ar, Up: Module List A RenderMan binding as a Perl 5.6 module **************************************** NAME ==== RenderMan - A RenderMan binding as a Perl 5.6 module SYNOPSIS ======== use RenderMan; DESCRIPTION =========== This RenderMan module implements a Perl 5.6 binding for the BMRT client library (libribout). It fully supports the client library. Therefore, this module has the following limitations: Error Handling callbacks are not implemented, Filter function callbacks are not implemented, and the TransformPoints function does nothing. Also, Blobby is not yet supported by BMRT 2.5.0.8. The full RenderMan specification is way beyond the scope of this man page. Please refer to the documents below for more information about RenderMan. The Perl binding is identical to the C binding except a few minor points: All "parameterlist"s are passed as a reference to a hash (i.e. \%params). Anywhere that a function's arguments can be terminated by RI_NULL, you can simply choose to not include that RI_NULL argument, which is incredibly nice. All array, matrix, and basis types are single-dimension arrays of doubles in this Perl binding. The order for 2-dimension types is first-row followed by second-row, etc. You will typically want to run your RenderMan Perl script and pipe the results into any RenderMan-compliant renderer, such as "rgl", "rendribv", or "rendrib", which all come with the excellent BMRT backage by Larry Gritz. If using the WinNT version of BMRT, you can specify a filename, "rgl" or "rendrib" as the argument to Begin(); and the output will be sent to a file or automatically piped to "rgl" or "rendrib" since the piping mechanism (and general functionality) of WinNT's command line parser is, uh, limited. AUTHOR ====== Glenn M. Lewis, mailto:glenn@gmlewis.com, http://www.gmlewis.com/ SEE ALSO ======== Blue Moon Rendering Toolkit (BMRT) by Larry Gritz. http://www.bmrt.org/ The RenderMan Companion: A Programmer's Guide to Realistic Computer Graphics by Steve Upstill, published by Addison Wesley. ISBN 0-201-50868-0. Advanced RenderMan: Creating CGI for Motion Pictures by Anthony A. Apodaca and Larry Gritz, published by Morgan Kaufmann Publishers ISBN 1-55860-618-1 The RenderMan Interface Specification, Version 3.2, July 2000, Pixar. http://www.pixar.com/products/rendermandocs/toolkit/Toolkit/ RenderMan is a registered trademark of Pixar. http://www.pixar.com/  File: pm.info, Node: Resources, Next: RevML/Doctype, Prev: RenderMan, Up: Module List handling application defaults in Perl. ************************************** NAME ==== Resources - handling application defaults in Perl. SYNOPSIS ======== use Resources; $res = new Resources; $res = new Resources "resfile"; DESCRIPTION =========== Resources are a way to specify information of interest to program or packages. Applications use resource files to specify and document the values of quantities or attributes of interest. Resources can be loaded from or saved to resource files. Methods are provided to search, modify and create resources. Packages use resources to hardwire in their code the default values for their attributes, along with documentation for the attibutes themselves. Packages inherit resources when subclassed, and the resource names are updated dynamically to reflect a class hierarchy. Methods are provided for interactive resource inspection and editing. 1. Resource inheritance ----------------------- Package attributes are inherited from base and member classes, their names are dynamically updated to reflect the inheritance, and values specified in derived/container classes override those inherited from base/member classes. More precisely, there a few rules governing the inheritance of resource names and values, and they will be explained by way of examples. As far as resource names, the rules are: Base class If Vehicle has a "speed" property, then it can use a resource named "vehicle.speed" to specify its default value. Derived class If Car *is a* Vehicle, then Car has a "car.speed" resource automagically defined by inheritance from the base class. Container class If Car *has a* member object called Tire, and Tire has a "tire.pressure" resource, then Car inherits a "car.tire.pressure" resource from the member class. Application class All resources of Car objects used by a program named "race" have the prefix "race." prepended to their names, e.g. "race.car.speed", "race.car.tire.pressure", etc. With regard to assigning values to resources, the rules are: Specification in a file Resources specified in a resource file always override hardcoded resources (with the exception of "hidden" resources, see below). Inheritance Resources defined in a derived class (like Car) override those specified in a base class. Likewise, resources defined in a container class override those specified in the members. In the above example, a default value for "car.speed" in Car overrides the value of "vehicle.speed" in any Car object, otherwise "car.speed" assumes the value of "vehicle.speed". Same for "car.tire.pressure". 2. Resource Files. ------------------ A resource specification in a (text) resource file is a line of the form: sequence: value There may be any number of whitespaces between the name and the colon character, and between the colon and the value. sequence can have four forms: (1) word A word not containing whitespaces, colons (':'), dots ('.') or asterisks ('*'), nor starting with an underscore ('_'). Or, recursively: (2) word.sequence (3) word*sequence (4) *sequence The asterisks in a resource name act as wildcards, matching any sequence of characters. For cases (3) or (4) the word must be or match the current application class, otherwise the resource specification is silently ignored (this means that an applications loads from a file only its own resources, and those whose application class is a wildcard). No distinction is made between uppercase and lowercase letters. value can be: An unadorned word or a quoted sequence of whitespace-separated words. Both single (' ') and double quotes quotes (" ") are allowed, and they must be paired. Any constant scalar constructor in Perl, including anon references to constant arrays or hashes. The special words *yes*, *true*, no, false (case insensitive) are treated as boolean resources and converted 1 and 0, unless they are quoted. Examples of valid resource specifications: car*brand : Ferrari # A word. car.price : 200K # Another word car.name : '312 BB' # A quoted sentence car*runs*alot : yes # A boolean, converted to 1. car*noise*lotsa : 'yes' # yes, taken verbatim car.size : [1, [2, 3]] # An anon array. car.lett : {"P"=>1, "Q"=>[2, 3]} # An anon hash. Examples of illegal resource names: car pedal # Whitespace in the name. .carpedal # Leading dot in name. car._pedal # Leading underscore in _dog. carpedal* # Trailing asterisk. carpedal. # Trailing dot. A resource file may contain comments: anything from a hash ('#') character to the end of a line is ignored, unless the hash character appears inside a quoted value string. Resource specifications may be split across successive lines, by terminating the split lines with a backslash, as per cpp(1). 3. The Resources hash --------------------- A non-my hash named %Resources can be used to specify the default values for the attributes of a package in its source code, along with documentation for the attributes themselves. The documentation itself is "dynamical" (as opposed to the static, pod-like variety) in that it follows a class hyerarchy and is suitable for interactive display and editing. The %Resources hash is just a hash of $Name => [$Value, $Doc] things. Each hash key *$Name* is a resource name in the above sequence form. Each hash value is a reference to an anon array *[$Value, $Doc]*, with *$Doc* being an optional resource documentation. The resource $Name *cannot* contain wildcard ('*') or colon (':') characters, nor start or end with a dot ('.'). Also, it must not be prefixed with the package name (since this is automatically prepended by the merge method, see below). Names starting with an underscore ('_') character are special in that they define "hidden" resources. These may not be specified in resource files, nor dynamically viewed/edited: they come handy to specify global parameters when you do not want to use global application-wide variables, and/or want to take advantage of the inheritance mechanism. The resource $Value can be any constant scalar Perl constructor, including references to arrays and/or hashes of constants (or references thereof). Boolean values must be specified as 1 or 0. The resource documentation is a just string of any length: it will be appropriately broken into lines for visualization purposes. It can also be missing, in which case an inherited documentation is used (if any exists, see the merge method below). The content of a resource hash is registered in a global Resource object using the merge method. Here is an example of deafults specification for a package. package Car; @ISA = qw( Vehicle ); use vars qw( %Resources ); %Resources = ( brand => ["FIAT", "The carmaker"], noise => ["Ashtmatic", "Auditory feeling"], sucks => [1, "Is it any good?"], nuts => [ { on => 2, off => [3, 5] }, "Spares"], '_ghost' => [0, "Hidden. Mr. Invisible"] 'tire.flat' => [0], ); The last line overrides a default in member class Tire. The corresponding doc string is supposedly in the source of that class. The last two hash keys are quoted because of the non alphanumeric characters in them. 4. Objects and resources ------------------------ The recommended way to use resources with Perl objects is to pass a Resource object to the "new" method of a package. The method itself will merge the passed resources with the package defaults, and the passed resource will override the defaults where needed. Resource inheritance via subclassing is then easily achieved via the merge method, as shown in the EXAMPLES section. 5. Methods in class Resources ----------------------------- 5.1. Creation and initialization -------------------------------- *new Resources ($resfile);* Creates a new resource database, initialized with the defaults for class Resources (see below for a list of them). If a nonempty file name is specified in $resfile, it initializes the object with the content of the so named resource file. For safe (non overwriting) loading, see the load method below. If the special file name "_RES_NODEFAULTS" is specified, the object is created completely empty, with not even the Resources class defaults in it. Returns the new object, or undef in case of error. *load($resfile, $nonew);* Loads resources from a file named $resfile into a resource database. The $nonew argument controls whether loading of non already defined resurces is allowed. If it is true, safe loading is performed: attempting to load non-wildcarded resource names that do not match those already present in the database causes an error. This can be useful if you want to make sure that only pre-defined resources (for which you presumably have hardwired defaults) are loaded. It can be a safety net against typos in a resource file. Use is made of *Safe::reval* to parse values specified through Perl constructors (only constants, anon hashes and anon arrays are allowed). Returns 1 if ok, 0 if error. *merge($class, @memberclasses);* Merges the %Resources hash of the package defining $class with those of its @memberclasses, writing the result in the resource database. The merging reflects the resource inheritance explained above: the %Resources of all base classes and member classes of $class are inherited along the way. Eventually all these resources have their names prefixed with the name of the package in which $class is defined (lowercased and stripped of all foo::bar:: prefixes), and with the application class as well. In the above example, the defaults of a Car object will be renamed, after merging as: car.brand, car.noise, ..., car.tire.flat and for a Civic object, where Civic is a (i.e. ISA) Car, they will be translated instead as civic.brand, civic.noise, ..., civic.tire.flat Finally, the application name ($0, a.k.a $PROGRAM_NAME in English) is prepended to all resource names, so, if the above Civic package is used by a Perl script named "ilove.pl", the final names after merging are ilove.civic.brand, ilove.civic.noise, ..., ilove.civic.tire.flat The new names are the ones to use when accessing these resources by name. The resource values are inherited accoring to the rules previously indicated, hence with resource files having priority over hardcoded defaults, nnd derived or container classes over base or member classes. Returns 1 if for success, otherwise 0. 5.2. Looking up resources ------------------------- The values and documentation strings stored in a Resource object can be accessed by specifying their names in three basic ways: directly ("byname" methods) As in "my.nice.cosy.couch" . by a pattern ("bypattern" methods) As in "m??nice.*" . hierarchically ("byclass" methods) If class Nice *is a* Cosy, then asking for "couch" in package Cosy gets you the value/doc of "my.couch". If, instead, Nice *has a* Cosy member, that the method gets you "my.nice.cosy.couch". This behaviour is essential for the proper initialization of subclassed and member packages, as explained in detail below. It is also possible to retrieve the whole content of a resource database ("names" and "each" methods) Note that all the resource lookup methods return named (non "wildcarded") resources only. Wildcarded resources (i.e. those specified in resource files, and whose names contain one or more '*') are best thought as placeholders, to be used when the value of an actual named resource is set. For example, a line in a resource file like *background : yellow fixes to yellow the color of all resources whose name ends with "background". However, your actual packages will never worry about unless they really need a background. In this case they either have a "background" resource in their defaults hash, or subclass a package that has one. valbyname($name); Retrieves the value of a named resource from a Resource database. The $name argument is a string containing a resource name with no wildcards. Returns the undefined value if no such resource is defined. docbyname($name); Retrieves the documentation string of a named resource from a Resource database. The $name argument is a string containing a resource name with no wildcards. Returns the undefined value if no such resource is defined. bypattern($pattern); Retrieves the full names, values and documentation strings of all the named (non wildcarded) resources whose name matches the given $pattern. The pattern itself is string containing a Perl regular expression, not enclosed in slashes. Returns a new Resource object containing only the matching resources, or the undefined value if no matches are found. valbypattern($pattern); Retrieves the full names and values of all named (non wildcarded) resources whose name matches the given pattern. Returns a new Resource object containing only names and values of the matching resources (i.e. with undefined doc strings), or the undefined value if no matches are found. docbypattern($pattern); Retrieves the full names and documentation strings of all named (non wildcarded) resources whose name matches the given pattern. Returns a new Resource object containing only names and docs of the matching resources (i.e. with undefined resource values), or the undefined value if no matches are found. *byclass($object, $suffix);* To properly initialize the attributes of a package via resources we need a way to know whether the package defaults (contained in its %Resources hash) have been overridden by a derived or container class. For example, to set a field like $dog->{Weight} in a Dog object, we must know if this $dog is being subclassed by Poodle or Bulldog, or if it is a member of Family, since all these other classes might override whatever "weight" default is defined in the %Resources hash of Dog.pm. This information must of course be gathered at runtime: if you tried to name explicitly a resource like "family.dog.weight" inside Dog.pm all the OOP crowd would start booing at you. Your object would not be reusable anymore, being explicitly tied to a particular container class. After all we do use objects mainly because we want to easily reuse code... Enter the "by class" resource lookup methods: *byclass*, *valbyclass* and *docbyclass*. Given an $object and a resource $suffix (i.e. a resource name stripped of all container and derived class prefixes), the *byclass* method returns a 3 element list containing the name/value/doc of that resource in $object. The returned name will be fully qualified with all derived/container classes, up to the application class. For example, in a program called "bark", the statements $dog = new Dog ($res); # $res is a Resources database ($name,$value,$doc) = $res->byclass($dog, "weight"); will set $name, $value and $doc equal to those of the "bark.poodle.weight" resource, if this Dog is subclassed by Poodle, and to those of "bark.family.dog.weight", if it is a member of Family instead. The passed name suffix must not contain wildcards nor dots. Be careful not to confuse the "byclass" with the "byname" and "bypattern" retrieval methods: they are used for two radically different goals. See the EXAMPLES section for more. Returns the empty list if no resources are found for the given suffix, or if the suffix is incorrect. *namebyclass($obj, $suffix);* As the *byclass* method above, but returns just the resource name (i.e. the suffix with all the subclasses prepended). *valbyclass($obj, $suffix);* As the *byclass* method above, but returns just the resource value. docbyclass($suffix); As the *byclass* method above, but returns just the resource documentation. each; Returns the next name/[value,doc] pair of the named (non wildcarded) resources in a resource database, exactly as the each Perl routine. names; Returns a list of the names of all named (non-wildcarded) resources in a resource database, or undef if the databasee is empty. 5.3. Assigning and removing Resources ------------------------------------- *put($name, $value, $doc);* Writes the value and doc of a resource in the database. It is possible to specify an empty documentation string, but name and value must be defined. Wildcards ('*' characters) are allowed in the $name, but the $doc is ignored in this case (documentation is intended for single resources, not for sets of them). The value is written unchanged unless the resource database already contains a wildcarded resource whose name includes $name (foo*bar includes foo.bar, foo.baz.bar, etc.). In this case the value of the wildcarded resource overrides the passed $value. Returns 1 if ok, 0 if error. removebyname($name); Removes the named (non wildcarded) resources from the database. Returns 1 if OK, 0 if the resource is not found in the database. removebypattern($name); Removes from the database all resources (both named and wildcarded) whose name mathes $pattern. An exactly matching name must be specified for wildcarded resources (foo*bar to remove foo*bar). Returns the number of removed resources. 5.6. Viewing and editing resources. ----------------------------------- view; Outputs the current content of a Resource object by piping to a pager program. The environment variable $ENV{RESPAGER}, the resource "resources.pager" and the environment variable $ENV{PAGER} are looked up, in this very order, to find the pager program. Defaults to */bin/more* if none of them is found. The output format is the same of a resource file, with the resource names alphabetically ordered, and the resource documentation strings written as comments. Returns 1 if ok, 0 if error. edit($nonew); Provides dynamical resource editing of a Resource object via an external editor program. Only resource names and values can be edited (anyway, what is the point of editing a resource comment on the fly?). The environment variables $ENV{RESEDITOR} and the resource "resouces.editor", are looked up, in this very order, to find the editor program. Defaults to */bin/vi* if none is found. The editor buffer is initialized in the same format of a resource file, with the resource names alphabetically ordered, and the resource documentation strings written as comments. The temporary file specified by the "resources.tmpfil" resource is used to initialize the editor, or '/tmp/resedit' if that resource is undefined. When the editor is exited (after saving the buffer) the method attempts to reload the edited resources. If an error is found the initial object is left unchanged, a warning with the first offending line in the file is printed, and the method returns with undef. Controlled resource loading is obtained by specifying a true value for the $nonew argument (see load). If the loading is successful, a new (edited) resource object is returned, which can be assigned to the old one for replacement. After a successful edit, the value of the resource "resources.updates" (which is always defined to 0 whenever a new resource is created) is increased by one. This is meant to notify program the and/or packages of the resource change, so they can proceed accordingly if they wish. 5.5. Miscellaneous methods -------------------------- write($filename); Outputs all resources of a resource database into a resource file (overwriting it). The resource documentation strings are normally written as comments, so the file itself is immediately available for resource loading. However, if the boolean resource "resources.writepod" is true, then the (non wildcarded) resources are output in POD format for your documentational pleasure. As usual in Perl, the filename can allo be of the form "|command", in which case the output is piped into "comma1nd". For resources whose value is a reference to an anon array or hash, it produces the appropriate constant Perl contructor by reverse parsing. The parser itself is available as a separate method named _parse (see package source for documentation). Returns 1 if ok, 0 if error. 5. Resources of Resources ------------------------- As you may have guessed at this point, the default configuration of this package itself is defined by resources. The resource class is, of course, "resources" (meaning that all the names have a leading "resources."). To prevent chaos, however, these resources cannot be subclassed. This should not be a problem in normal applications, since the Resource package itself is not meant to be subclassed, but to help building a hierarchy of classes instead. The currently recognized resources, and their default values, are: resources.appclass : "$PROGRAM_NAME" The application name of this Resource object. resources.editor : /bin/vi Resource editor. resources.mergeclass : true Boolean. True to merge with class inheritance. resources.pager : /bin/more Resource pager. resources.separator : ':' Pattern separating names from values in resource files. resources.tmpfil : " Editor temporary file. resources.updates : 0 Number of resource updates. resources.verbosity : 1 True to print warnings. resources.viewcols : 78 Width of view/edit window. resources.writepod : false Boolean. True if the write method should output in POD format. EXAMPLES ======== Here is an example of resource inheritance. HotDog is a subclass of Food, and has a member Wiener whichi happens to be a Food as well. The subclass has defaults for two resources defined by the base classes ("edible" and "wiener.mustard"), and their values will override the base class defaults. Remember that after merging all resources names are prefixed with the current class name. use Resources; package Food; %Resources = ( edible => [1, "Can it be eaten."], tasty => ["sort_of", "D'ya like it?"], ); sub new { my ($type, $res) = @_; $res || $res = new Resources || (return undef); $res->merge($type) || die ("can't merge defaults"); my $food= bless({}, type); $food->{Edible} = $res->valbyclass("edible"); $food->{Tasty} = $res->valbyclass("tasty"); # Use valbyclass so a subclass like HotDog can change this by its # defaults. } # A Food method to say if it can be eaten. sub eatok { my $food=shift; return $food->{Edible}; } package Wiener; @ISA = qw( Food ); %Resources = ( tasty => ["very"], # this overrides a base class default mustard => ["plenty", "How much yellow stuff?"], ); # Nothing else: all methods are inherited from the base class. package HotDog; @ISA = qw( Food ); %Resources = ( edible => [0], tasty => ["yuck!"], 'wiener.mustard' => ["none"], # To override member class default. ); sub new { my ($type, $res) = @_; $res || $res = new Resources || (return undef); $res->merge($type) || die ("can't merge defaults"); my $hd = bless(new Food ($res), $type); $hd->{Wien} = new Wiener ($res); return $hd; } # All tastes of hotdog sub tastes { my $hd = shift; return ($hd->{Tasty}, $hd->{Wien}->{Tasty}); } package main; # Whatever # $res = new Resources("AppDefltFile") || die; $snack = new HotDog($res); $gnam = $snack->eat(); # hotdog.edible overridees food.edible, # so here $gnam equals 0 @slurp = $snack->tastes() # @slurp equals ("yuck!", "very") # the resources were overridden # by a subclass of HotDog , or # differently specified in # "AppDefltFile" SEE ALSO ======== Safe(3). BUGS ==== The underlying idea is to use a centralized resource database for the whole application. This ensures uniformity of behaviour across kin objects, but allow special characterizations only at the cost of subclassing. AUTHOR ====== Francesco Callari Artifical Perception Laboratory, Center for Intelligent Machines, McGill University. WWW: http://www.cim.mcgill.ca/~franco/Home.html COPYRIGHT ========= Copyright 1996 Francesco Callari, McGill University Permission to use, copy, modify, and distribute this software and its documentation for any purpose without fee is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of McGill not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. McGill makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. MCGILL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL MCGILL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.  File: pm.info, Node: RevML/Doctype, Next: RevML/Writer, Prev: Resources, Up: Module List A subclass of XML::Doctype ************************** NAME ==== RevML::Doctype - A subclass of XML::Doctype SYNOPSIS ======== use RevML::Doctype ; ## To use the highest RevML::Doctype module (e.g. RevML::Doctype::v0_22) $rmldt = RevML::Doctype->new ; ## To parse a .dtd file: $rmldt = RevML::Doctype->new( 'revml.dtd' ); $rmldt = RevML::Doctype->new( DTD_FILE => 'revml.dtd' ); ## To load a preparsed .pm file $rmldt = RevML::Doctype->new( 1.1 ) ; $rmldt = RevML::Doctype->new( VERSION => 1.1 ) ; DESCRIPTION =========== METHODS ======= new Creates an instance. save_as_pm $doctype->save_as_pm ; $doctype->save_as_pm( $out_spec ) ; Outspec is a module name. 'RevML::Doctype::vNNN' is assumed if no outspec is provided. Use '-' to emit to STDOUT. Saves the Doctype object in a perl module. Tries to save in lib/RevML/Doctype/ if that directory exists, then in ./ if not. import use ## To extablish a default RevML::Doctype for the current package: use RevML::Doctype 'DEFAULT' ; use RevML::Doctype DTD_FILE => 'revml.dtd' ; SUBCLASSING =========== This class uses the fields pragma, so you'll need to use base and possibly fields in any subclasses. COPYRIGHT ========= Copyright 2000, Perforce Software, Inc. All Rights Reserved. This will be licensed under a suitable license at a future date. Until then, you may only use this for evaluation purposes. Besides which, it's in an early alpha state, so you shouldn't depend on it anyway. AUTHOR ====== Barrie Slaymaker  File: pm.info, Node: RevML/Writer, Next: Run, Prev: RevML/Doctype, Up: Module List Write RevML files using the RevML DTD ************************************* NAME ==== RevML::Writer - Write RevML files using the RevML DTD SYNOPSIS ======== use RevML::Doctype::v1_1 ; use RevML::Writer ; DESCRIPTION =========== This class provides facilities to write out the tags and content of RevML documents. See XML::AutoWriter for all the details on this writer's API. AUTHOR ====== Barrie Slaymaker COPYRIGHT ========= This module is Copyright 2000, Perforce Software, Inc. All rights reserved. This will be licensed under a suitable license at a future date. Until then, you may only use this for evaluation purposes. Besides which, it's in an early alpha state, so you shouldn't depend on it anyway.  File: pm.info, Node: Run, Next: SDBM_File, Prev: RevML/Writer, Up: Module List Perl extension for to start programs in background ************************************************** NAME ==== Run - Perl extension for to start programs in background SYNOPSIS ======== use Run; $pid = spawn 'long_running_task', 'arg1', 'arg2' or die "spawn: $!"; do_something_else(); waitpid($pid,0); DESCRIPTION =========== The subroutine spawn is equivalent to the builtin system (see `system LIST', *Note Perlfunc: (perl.info)perlfunc,) with the exceptions that the program is started in background, and the return the pid of the kid. Returns 0 on failure, $! should contain the reason for the failure. EXPORT ====== Exports spawn by default. AUTHOR ====== Ilya Zakharevich &=FH1"' creates a "naughty" copy of `FH1'. Closing FH will invalidate `FH1'. SEE ALSO ======== perl(1).