This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Config/Properties, Next: Config/User, Prev: Config/IniFiles, Up: Module List read Java-style properties files ******************************** NAME ==== Config::Properties - read Java-style properties files SYNOPSIS ======== use Config::Properties; my $properties = new Properties(); $properties->load( $fileHandle ); $value = $properties->getProperty( $key ); $properties->setProperty( $key, $value ); $properties->store( $fileHandle, $header ); DESCRIPTION =========== Config::Properties is an near implementation of the java.util.Properties API. It is designed to allow easy reading, writing and manipulation of Java-style property files. The format of a Java-style property file is that of a key-value pair seperated by either whitespace, the colon (:) character, or the equals (=) character. Whitespace before the key and on either side of the seperator is ignored. Lines that begin with either a hash (#) or a bang (!) are considered comment lines and ignored. A backslash (\) at the end of a line signifies a continuation and the next line is counted as part of the current line (minus the backslash, any whitespace after the backslash, the line break, and any whitespace at the beginning of the next line). When a property file is saved it is in the format "key=value" for each line. AUTHOR ====== `Config::Properties' was developed by Randy Jay Yarger.  File: pm.info, Node: Config/User, Next: ConfigReader/Simple, Prev: Config/Properties, Up: Module List API for locating user information regardless of OS ************************************************** NAME ==== User - API for locating user information regardless of OS SYNOPSIS ======== use Config::User; my $cfg = Config::IniFiles->new ( -file => sprintf("%s/%s", Config::User->Home, ".ncfg"), -default => 'Default' ); DESCRIPTION =========== This module is allows applications to retrieve per-user characteristics. At present, it contains only one method, Home(), which is used to return a location that can be expected to be a users "Home" directory on either Windows or Unix. While one way of writing this would be to check for operating system and then check the expected location for an operation system of that type, I chose to do the following: sub Home { return $ENV{HOME} if $ENV{HOME}; return $ENV{USERPROFILE} if $ENV{USERPROFILE}; return ""; } In other words, if $HOME is defined in the user's environment, then that is used. Otherwise $USERPROFILE is used. Otherwise "" is returned. A contribution for Macintosh (or any other number of OS/arch combinations) is greatly solicited. EXPORT ------ None by default. AUTHOR ====== T.M. Brannon, tbone@cpan.org ACKNOWLEDGEMENTS ================ I would like to offer profuse thanks to my fellow perl monk at www.perlmonks.org, the_slycer, who told me where HOME could be found on Windows machines. perl(1).  File: pm.info, Node: ConfigReader/Simple, Next: Conjury, Prev: Config/User, Up: Module List Simple configuration file parser ******************************** NAME ==== ConfigReader::Simple - Simple configuration file parser SYNOPSIS ======== use ConfigReader::Simple; $config = ConfigReader::Simple->new("configrc", [qw(Foo Bar Baz Quux)]); $config->parse(); $config->get("Foo"); DESCRIPTION =========== C reads and parses simple configuration files. It's designed to be smaller and simpler than the C module and is more suited to simple configuration files. CONSTRUCTOR =========== new ( FILENAME, DIRECTIVES ) This is the constructor for a new ConfigReader::Simple object. FILENAME tells the instance where to look for the configuration file. DIRECTIVES is an optional argument and is a reference to an array. Each member of the array should contain one valid directive. A directive is the name of a key that must occur in the configuration file. If it is not found, the module will die. The directive list may contain all the keys in the configuration file, a sub set of keys or no keys at all. This does the actual work. No parameters needed. Returns the parsed value for that directive. _validate_keys ( ) If any keys were declared when the object was constructed, check that those keys actually occur in the configuration file. LIMITATIONS/BUGS ================ Directives are case-sensitive. If a directive is repeated, the first instance will silently be ignored. Always die()s on errors instead of reporting them. get() doesn't warn if used before parse(). get() doesn't warn if you try to acces the value of an unknown directive not know (ie: one that wasn't passed via new()). All these will be addressed in future releases. CREDITS ======= Kim Ryan adapted the module to make declaring keys optional. Thanks Kim. AUTHORS ======= Bek Oberin COPYRIGHT ========= Copyright (c) 2000 Bek Oberin. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Conjury, Next: Conjury/C, Prev: ConfigReader/Simple, Up: Module List Introduction to Perl Conjury **************************** NAME ==== Conjury - Introduction to Perl Conjury DESCRIPTION =========== Perl Conjury is a general purpose software construction framework. It's an alternative to the venerable make utility, but since it is written entirely in Perl, its capabilities extend to functions traditionally implemented using a text preprocessor to generate `Makefile' files, i.e. to configure for product variants. The Perl Conjury system is a modular framework. The core software is very general. For example, to compile and link executable programs written in C or C++, you'll need the `Conjury::C' module- bundled separately. To use Perl Conjury, you will need Perl installed on your system. The command line utility is named *cast*, and it is a very short Perl script. It simply loads the `Conjury::Core' module, which does the heavy lifting: parsing the arguments and interpreting the files containing the "spells" for constructing your products from their sources. Before the *cast* utility loads the `Conjury::Core' module, it first tries to add the top of the source file hierarchy to the Perl library search path. It does this by looking for a `Conjury' directory in the current directory, then its parent, that that directory's parent, all the way to the root of the current directory. Application specific modules for constructing the software should be placed in this directory and use the `Conjury' namespace. You can carry all the general purpose Perl Conjury modules around with your source code, in whole or in part- altering them for your own ends, if you like. Alternatively, you can just require that they be properly installed in the Perl site library. Your choice. If you use the `Conjury::Core' module from the Perl Conjury distribution, then files named `Conjury.pl', which you place in the same directories as the source, contain the code for constructing the products. These are written in Perl, and use modules from the Perl Conjury distribution as well as application-specific modules that are part of the source for the software under construction. You'll need a `Conjury.pl' file at the top of your source file hierarchy, but you may use the `Conjury::Core::deferral' function to create spells that defer action to other spells defined in `Conjury.pl' files you place in different locations in the source file hierarchy. FILES ===== `Conjury.pl' These files are Perl libraries (i.e. they are not executed directly, but rather loaded by the *cast* utility) that contain the code for constructing products from the source file with which they are associated. `Conjury' This directory is found at the top of the source file hierarchy for the software under construction. SEE ALSO ======== More documentation can be found in `cast' in this node, *Note Conjury/Core: Conjury/Core, and, of course- `Perl' in this node. NOTES ===== You're wondering- why the name "Conjury" of all things? It's very simple. If you have much experience owning and maintaining the code responsible for constructing a large, complex, cross-platform software system using make, you've probably seen all manner of horrific mechanisms for generating `Makefile' files using arcane translators and text processors. Some commercial software development environments even seem to perpetuate the problem to promote particular platforms. These systems tend to combine the worst features of several languages together into the sort of Lovecraftian crawling horror that makes Perl seem like a harmless, fluffy bunny in comparison- thus, the motivation for this work. If you haven't yet, you really must see the sequence in that 1950's era animated feature film in which the most famous mouse in the world is "the sorcerer's apprentice," and he has used his master's magical arts to create an army of animated broomsticks to carry his water for him. It is the image of the mouse swirling around in the vortex of a whirlpool in the torrent of water his broomsticks dutifully create for him, while he is frantically thumbing through the documentation looking for the spell that will shut them all down, that the author had in mind when he was casting about for a name for this framework. CREDIT AND ATTRIBUTION ====================== James Woodyatt <`jhw@wetware.com'> The venerable make and its derivatives have inspired many attempts at better ways to approach basically the same problem. Perl Conjury is not the first, and it will doubtless not be the last. The author wishes to give due credit to the authors of *jam* and *cons* for the deep thinking that inspired this work- in particular, the idea of journaling MD5 signatures to track which productions are up-to-date is a very good one, and the author slammed his forehead with his open palm very hard when he first saw it in the *cons* utility. LICENSE ======= Copyright (c) 1999-2000 James H. Woodyatt. All rights reserved. Redistribution and use of the software in source and machine-readable forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must contain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in machine-readable form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND ITS CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO THE IMPLIED MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBLITY OF SUCH DAMAGE.  File: pm.info, Node: Conjury/C, Next: Conjury/C/GNU, Prev: Conjury, Up: Module List Perl Conjury with C/C++ compilers, linkers and archivers ******************************************************** NAME ==== Conjury::C - Perl Conjury with C/C++ compilers, linkers and archivers SYNOPSIS ======== c_object Source => I, Directory => I, Includes => [ I, I, ... ], Defines => { I => I, I => I, ... }, Compiler => I, Options => [ I, I, ... ], Factors => [ I, I, ... ]; c_executable Directory => I, Name => I, Order => [ Searches => [ I, I, ... ], Objects => [ I, I, ... ], Libraries => [ I, I, ...] ], Linker => I, Options => [ I, I, ... ], Factors => [ I, I, ... ] c_static_library Directory => I, Name => I, Objects => [ I, I, ...], Archiver => I, Options => [ I, I, ... ], Factors => [ I, I, ... ] c_compiler Program => I, Options => [ I, I, ... ], Journal => I, Flag_Map => { 'I' => I, 'D' => I, 'c' => I, 'o' => I }, Suffix_Rule => sub { my ($name) = @_; ... return $result }, Scanner => sub { my ($c_file, $args) = @_; ... return @result }; c_compiler Vendor => I, ... c_linker Program => I, Options => [ I, I, ... ], Journal => I, Flag_Map => { 'l' => I, 'L' => I, 'o' => I }, Bind_Rule => sub { my ($lib, $bind) = @_; ... return @result }, Search_Rule => sub { my ($lib, $rule, $bind, @search) = @_; ... return @factors }; c_linker Vendor => I, ... c_archiver Program => I, Options => [ I, I, ... ], Journal => I, Flag_Map => { 'r' => I }; c_archiver Vendor => I, ... DESCRIPTION =========== Spells for compiling and linking C/C++ software are constructed using c_object, c_executable and c_static_library. The compiler, linker and archiver used in the resulting actions are the same compiler, linker and archiver that were used to build Perl itself, unless otherwise specified. Specializations of the general classes of compiler, linker and archiver can be created using c_compiler, c_linker and c_archiver. Compiling Objects From C/C++ Source ----------------------------------- Use the c_object function to create a spell for compiling an object file from a C or C++ source file. The name of the resulting object file will be derived by removing the .c suffix and replacing it with the suffix for object files on the current platform. Use the c_compiler function to create an object to represent a specialization of the C/C++ compiler tool class. c_object This function returns a spell for the action to compile a source file into an object file. The 'Source' argument is required and specifies the name of the source file to compile into an object file. The optional 'Directory' argument specifies the directory in which the object file should be produced. The optional 'Includes' argument specifies a list of directories that should be used by the compiler to search for header files. Preprocessor variables may be specified with the optional 'Defines' argument by placing the names of variables to set into the keys of a hash, and defining the values as needed. The optional 'Compiler' argument specifies that a particular specialization of the C/C++ compiler tool be used (instead of the default compiler). The optional 'Options' argument specifies a list of options with which to invoke the compiler for this particular object file. The optional 'Factors' argument specifies additional factors to associate with the spell created. c_compiler This function returns an object representing a specialization of the C/C++ compiler class. If the 'Vendor' argument is specified, then the vendor-specific subclass of the `Conjury::C::Compiler' class parse the argument list. Otherwise, the specialization is applied to the base class used for the default compiler. The optional 'Program' argument specifies the name of the program to invoke the compiler. The optional 'Options' argument specifies the list of options with which the compiler should be invoked for all object files. The optional 'Journal' argument specifies the journal object that should be used in creating all spells. The optional 'Flag_Map' argument specifies a hash that sets the flag character for various standard options to C/C++ compilers for setting the include path, the preprocessor definitions, the source file and the output file. The optional 'Suffix_Rule' argument specifies a subroutine that converts the name of a source file into the corresponding object file. The optional 'Scanner' argument specifies a subroutine that finds the list of files that a source file references with '#include' directives. Linking Executables From Objects -------------------------------- Use the c_executable function to create a spell for linking an executable program from a list of object files. Use the c_linker function to create an object to represent a specialization of the C/C++ linker tool class. c_executable This function returns a spell for the action to link a list of object files and libraries into an executable file. The optional 'Directory' argument specifies the directory where the executable program is to be produced. If unspecified, the directory of the current context is used. The 'Name' argument is required and specifies the name of the executable program. Any filename extensions the system requires for executable program files will be appended automatically. The 'Order' argument is a required list of verb-object pairs corresponding to orders for the linker to use in producing the executable. The 'Searches' verb specifies a list of directories to add to the library search path; the 'Objects' verb specifies a list of object files to link (either the spells that produce them, or the names of spells that will produce them); the 'Libraries' verb specifies the list of libraries to link. Order verbs may be specified in whatever sequence makes sense to the linker. The optional 'Linker' argument specifies that a particular specialization of the C/C++ linker tool be used (instead of the default linker). The optional 'Options' argument specifies a list of options with which to invoke the linker for this particular object file. The optional 'Factors' argument specifies additional factors to associate with the spell created. c_linker This function returns an object representing a specialization of the C/C++ linker class. If the 'Vendor' argument is specified, then the vendor-specific subclass of the `Conjury::C::Linker' class parse the argument list. Otherwise, the specialization is applied to the base class used for the default linker. The optional 'Program' argument specifies the name of the program to invoke the linker. The optional 'Options' argument specifies the list of options with which the linker should be invoked for all product files. The optional 'Journal' argument specifies the journal object that should be used in creating all spells. The optional 'Flag_Map' argument specifies a hash that sets the flag character for various standard options to C/C++ linkers for setting the search path, the output file and the libraries to link. The optional 'Bind_Rule' argument specifies a subroutine that takes a library name and a binding specification and returns a list of library filenames for which the binding specification applies. Typical binding specifications include 'static' and 'dynamic'- and the unnamed specification, which typically implies "either dynamic or static as required." The optional 'Search_Rule' argument specifies a subroutine that takes a library name, a binding rule (see above), a binding specification (also, see above), and a list of the current directories in the library search path (at the current point in the sequence of orders), and returns the list of factors which produce the library files. Creating Static Archives Of Objects ----------------------------------- Use the c_static_library function to create a spell for composing a static library from a list of object files. Use the c_archiver function to create an object to represent a specialization of the C/C++ archiver tool class. c_static_library This function returns a spell for the action to archive a list of object files in a static library file. The optional 'Directory' argument specifies the directory where the static library file is to be produced. If unspecified, the directory of the current context is used. The 'Name' argument is required and specifies the name of the library file. Any filename extensions and prefixes the system requires for static library files will be added automatically. The 'Objects' argument is required and specifies the list of objects (and/or spells that produce the objects) to be archived into the static library file. The optional 'Archiver' argument specifies that a particular specialization of the C/C++ archiver tool be used (instead of the default archiver). The optional 'Options' argument specifies a list of options with which to invoke the archiver for this particular object file. The optional 'Factors' argument specifies additional factors to associate with the spell created. c_archiver This function returns an object representing a specialization of the C/C++ archiver class. If the 'Vendor' argument is specified, then the vendor-specific subclass of the `Conjury::C::Archiver' class parse the argument list. Otherwise, the specialization is applied to the base class used for the default archiver. The optional 'Program' argument specifies the name of the program to invoke the archiver. The optional 'Options' argument specifies the list of options with which the archiver should be invoked for all static library files. The optional 'Journal' argument specifies the journal object that should be used in creating all spells. The optional 'Flag_Map' argument specifies a hash that sets the flag character for various standard options to C/C++ archivers, including the flag for replacing existing objects with new ones. SEE ALSO ======== The introduction to Perl Conjury is in *Note Conjury: Conjury,. Other useful documents include `cast' in this node and *Note Conjury/Core: Conjury/Core,. The specialization for the GNU tools is documented in *Note Conjury/C/GNU: Conjury/C/GNU,. AUTHOR ====== James Woodyatt <`jhw@wetware.com'>  File: pm.info, Node: Conjury/C/GNU, Next: Conjury/C/Sun, Prev: Conjury/C, Up: Module List Perl Conjury with the GNU C/C++ tools ************************************* NAME ==== Conjury::C::GNU - Perl Conjury with the GNU C/C++ tools SYNOPSIS ======== c_compiler Vendor => 'GNU', Language => I, No_Scanner => 1, Program => I, Options => [ I, I, ... ], Journal => I; c_linker Vendor => 'GNU', Language => I, Program => I, Options => [ I, I, ... ], Journal => I; DESCRIPTION =========== The optional 'Program', 'Options' and 'Journal' arguments to the GNU-specific specializations of the c_compiler and c_linker functions are simply passed through unmodified to the base class constructor. The optional 'Language' argument specifies the langauge for which the compiler or linker should be invoked. The C language is the default if not otherwise specified. The value is case-insensitive and may be any one of the following: 'c', 'c++' or 'objective-c'. The optional 'No_Scanner' argument in the c_compiler specialization specifies that the processing overhead of scanning all the source files for their dependency trees is unnecessary. If you are only building from clean source file hierarchies (with no existing products from previous runs), then the construction time of large builds may be improved with this option. SEE ALSO ======== More documentation can be found in *Note Conjury: Conjury,, `cast' in this node, *Note Conjury/Core: Conjury/Core, and *Note Conjury/C: Conjury/C,. AUTHOR ====== James Woodyatt  File: pm.info, Node: Conjury/C/Sun, Next: Conjury/Core, Prev: Conjury/C/GNU, Up: Module List Perl Conjury with the Sun Workshop C/C++ tools ********************************************** NAME ==== Conjury::C::Sun - Perl Conjury with the Sun Workshop C/C++ tools SYNOPSIS ======== c_compiler Vendor => 'Sun', Language => I, No_Scanner => 1, Program => I, Options => [ I, I, ... ], Journal => I; c_linker Vendor => 'Sun', Language => I, Program => I, Options => [ I, I, ... ], Journal => I; c_archiver Vendor => 'Sun', Language => I, Program => I, Options => [ I, I, ... ], Journal => I; DESCRIPTION =========== The optional 'Program', 'Options' and 'Journal' arguments to the Sun-specific specializations of the c_compiler and c_linker functions are simply passed through unmodified to the base class constructor. The optional 'Language' argument specifies the langauge for which the compiler or linker should be invoked. The C language is the default if not otherwise specified. The value is case-insensitive and may be either 'c'or 'c++'. The optional 'No_Scanner' argument in the c_compiler specialization specifies that the processing overhead of scanning all the source files for their dependency trees is unnecessary. If you are only building from clean source file hierarchies (with no existing products from previous runs), then the construction time of large builds may be improved with this option. SEE ALSO ======== More documentation can be found in *Note Conjury: Conjury,, `cast' in this node, *Note Conjury/Core: Conjury/Core, and *Note Conjury/C: Conjury/C,. AUTHOR ====== James Woodyatt  File: pm.info, Node: Conjury/Core, Next: Conjury/Core/Prototype, Prev: Conjury/C/Sun, Up: Module List the foundation of Perl Conjury ****************************** NAME ==== Conjury::Core - the foundation of Perl Conjury SYNOPSIS ======== use Conjury::Core; tie I, Conjury::Core::Journal, F; $stage = Conjury::Core::Stage->new ( I ); $stage->make_subdir ( F ); $spell = Conjury::Core::Spell->new ( I ); cast_warning ( I ); cast_error ( I ); [$spell =] name_spell ( I ); @spells = fetch_spells ( I ); ($basedir, $subdir) = find_stage ( F ); $spell = Conjury::Core::deferral ( I ); $spell = Conjury::Core::filecopy ( I ); $spell = Conjury::Core::dispell ( I ); DESCRIPTION =========== The `Conjury::Core' module is the foundation of the Perl Conjury software construction framework. You need to understand this module before you design other Perl Conjury modules, especially application-specific ones referenced in your `Conjury.pl' files. In addition to some exported functions, there are four Perl packages in the `Conjury::Core' namespace: Conjury::Core::Context, Conjury::Core::Journal, Conjury::Core::Stage and Conjury::Core::Spell. Conjury::Core::Context ---------------------- A "context" is an association between a directory within the source file hierarchy and the spells defined by the Conjury.pl file there. (The name of the spell definition file may differ on your platform. See *Note Conjury: Conjury,.) A Conjury::Core::Context object encapsulates this association. It should be treated like a structure with named members. Most of its methods are not really for public use. The 'Directory' method returns the name of the directory associated with the context. The `$Current_Context' package variable always contains a reference to the current context object. The `$Top_Context' package variable always contains a reference to the context at the top of the source file hierarchy. Conjury::Core::Journal ---------------------- A "journal" is a file that contains the persistent data that Perl Conjury uses to record the signatures of actions as they are performed, so that they can be skipped on subsequent runs when the signature for products are known not to have changed. It probably should not be implemented as a tied hash, but it is. It should be treated like an opaque object. Create a journal using the tie builtin and specifying the name of the file to write. Conjury::Core::Stage -------------------- A "stage" is an association between a directory and a journal object mapped to a file in that directory with a standard name. On most platforms, journal files in a stage are named `.conjury-journal', but some filesystems have funny conventions so your experience may vary. Create a Conjury::Core::Stage object with its new method. Create subdirectories within the stage using the `make_subdir' method. Conjury::Core::Stage->new Creates a stage object associated with a directory. The arguments are named in a hash. All of them are optional. Use the optional 'Directory' argument to associate the stage with a directory other than the one associated with the current context. Use the optional 'Journal' argument to associate the stage explicitly with a specific journal object. $stage->make_subdir(directory) Creates a subdirectory within the stage. The named subdirectory must be specified by relative path. It will be created during the compile phase, and its creation is not reversed by the *-undo* option. Conjury::Core::Spell -------------------- A "spell" is an object that encapsulates the action required to perform a task, typically for constructing or erasing files. A spell is usually associated with a list of factors, other spells representing actions that must be taken first, if the spell is to succeed. All spells have a profile which is used in computing the signature of the spell. Before an action is taken for a spell, the signatures of all its factors are appended to the profile for the spell, then reduced with the MD5 cryptographic hash function to become the signature for the spell. When a spell creates product files, the names of the files and the signature of the spell that produced them is journaled to a file. In this way, if the signature for a file is found to have changed since it was last journaled, it is because the spell responsible for creating it has acquired a new profile, or one of its factors has a new signature. If a factor of a spell specifies a file not produced by any spells, that file is treated as a source file, and its modification time is appended to the profile of the spell which considers it a factor. In this way, changes to the modification time of a source file results in a cascading change to the signature of every spell that references it in its tree of factors. Use the `Conjury::Core::Spell-'new> subroutine to construct a spell object. The named parameters are all optional, but using some of them implies a requirement for the use of others. A spell constructed with no parameters has no action, no profile, i.e. it generates no effect on the signature of spells that consider it a factor. The named parameters of the new method in detail: Journal => \%journal Associates the spell with a journal object. This is usually not necessary when the spell has no product files. Spells that have products should always journal their signatures, but it is not required. Factors => [ `factor1', `factor2', ... ] Specifies the list of factors for the spell. These may be references to other spell objects or the names of spells to fetch using the fetch_spells function. Product => filename Product => [ *filename1*, *filename2*, ... ] Specifies the name of the file, or a list of the names of files, produced by the action of the spell. When the spell is created, the names of the products are stored internally in a global hash available to the fetch_spells function. Action => SCALAR Action => [ *PROGRAM*, *ARG1*, *ARG2*, ... ] Action => CODE Specifies the action to take when the spell is invoked. The first and second form result in the scalar (or the list of scalars) to be used with the system builtin function. The third form is for specifying a closure. If you use a closure, you will be required to specify a profile for the closure. This is because you cannot convert a code block into a string very easily in Perl. When a spell is invoked, its action is executed in the context in which it was created. Actions return boolean true on failure. Profile => SCALAR Profile => CODE Specifies the profile for an action. The first form is the simple case, i.e. the string is used as the profile for an action closure. You should provide a profile that uniquely describes the action to take, including the name of the action function and the values of any parameters used in the construction of the closure. The second form is the more complicated case, i.e. the profile is a closure itself. Closure profiles require no arguments, and they are called during the invocation phase immediately before the factors are invoked. The explanation for why you would want to use this form is tedious, esoteric and best not presented during dinner. Hint: C language dependency scanning is one case. Exported Functions ------------------ The name_spell, fetch_spells and find_stage functions should probably be moved into an appropriate Conjury::Core::Xxxxx namespace. If they stay where they are, then the contents of `@EXPORT' should be moved to `@EXPORT_OK'. It remains unclear what is the right thing to do here- but it will be. It will. cast_warning Prints a warning message to the standard output. Use this function like the print builtin function. A prefix is inserted to identify the message as a warning from the *cast* utility, and a newline is appended. cast_error Prints an error message to the standard output and dies. Use this function like the die builtin function. A prefix is inserted to identify the message as an error from the *cast* utility, and a newline is appended. name_spell name_spell (Spell => *spell*, Context => context, Name => [ *name1*, *name2*, ... ], # array or scalar is okay Default => 1) Assigns names in a context to a spell. The 'Spell' argument is the only required argument. The others are all optional. If no context is specified, then the current context is assumed. If the 'Default' argument is specified, or the 'Name' argument is unspecified or specifies an empty list, then the spell is explicitly assigned to the list of unnamed spells in the context. These spells are typically the 'default' spells that are invoked when no names are given to the *cast* utility from the command line. fetch_spells fetch_spells(Name => name, Context => context, Require => 1) Returns a list containing references to all the spell objects with the name in the context. If the name is not specified, then the list will contain references to all the unnamed spell objects. You can use a list of names to fetch all the spell objects for the whole list at once. A spell will be fetched if its product matches the specified name, or the spell was explicitly assigned the name with the name_spell function. If the context is not specified, the current context is assumed. Spells for products created in other contexts can be fetched using either an absolute or a relative pathname. Be careful that the path you specify contains no symbolic links or references to parent directory pointers, i.e. the '..' directory, as these may not be resolved properly. If the 'Require' argument is not set, then an empty list is a permissible result. find_stage directory Finds the stage object for the specified directory. In array context, this returns a 2-tuple of the base directory for the stage object and the relative path from the base to specified directory. deferral $spell = deferral(Directory => [ `dir1', `dir2', ...], Name => name, If_Present => 1); Creates a spell object that defers its actions to the named spells in contexts associated with other directories. The 'Name' argument is used with the fetch_spells function to find all the named spells in each directory. There must be a spells definition file in each of the named directories, unless the 'If_Present' argument is defined. The 'Name' argument may specify a single name or a list of names. If it is a list of names, then all the names are passed to the fetch_spells function for each directory at a time. filecopy $spell = filecopy (Journal => *journal*, Factors => [ *spell1*, *spell2*, ... ], Directory => directory, File => [ `file1', `file2', ... ], # array or scalar is okay Permission => *permission*, Owner => [ user, group ]; Creates a spell object that copies a file or a list of files to a directory. The 'File' argument is required and must specify a filename or a list of filenames. The 'Directory' argument is required and must specify the destination directory for the copy action. Use the optional 'Factors' argument to add spells explicitly to the list of factors. If there are already spells that produce the files in the 'File' list, they need not be listed here. They will be fetched and automatically appended to the factors list. Use the optional 'Journal' argument to specify a journal object for the spell. Use the optional 'Permission' argument to specify that the chmod builtin should be used to set the access permissions associated with the files after they have been copied to the destination. The syntax requirements for chmod apply. Use the optional 'Owner' argument to specify that the chown builtin should be used to set the user and group ownership after the files have been copied to the destination. The syntax requirements for chown apply. dispell $spell = dispell (Journal => *journal*, Factors => [ *spell1*, *spell2*, ... ], Directory => [ `directory1', `directory2', ...] # array or scalar okay File => [ `file1', `file2', ... ], # array or scalar okay Require => 1; Creates a spell object that erases files or lists of files in a directory. One or both of the arguments, 'File' and 'Directory', are required. The 'File' argument specifies a filename or a list of filenames to unlink with the 'unlink' builtin function. The 'Directory' argument specifies a directory or a list of directories to remove with the 'rmdir' builtin. The 'Require' argument is optional. If it is set, then the files and directories to be unlinked or removed are required to exist when the action is executed to erase them. Use the optional 'Factors' argument to add spells explicitly to the list of factors. Use the optional 'Journal' argument to specify a journal object for the spell. AUTHOR ====== James Woodyatt <`jhw@wetware.com'>  File: pm.info, Node: Conjury/Core/Prototype, Next: Continuus, Prev: Conjury/Core, Up: Module List function prototype checking in Conjury ************************************** NAME ==== Conjury::Core::Prototype - function prototype checking in Conjury SYNOPSIS ======== require Conjury::Core::Prototype; use Carp qw/&croak/; $prototype = Conjury::Core::Prototype->new; $prototype->required_arg (foo_arg1 => sub { my ($x, $y) = (shift, undef); $y = 'not a HASH reference' unless (ref $x eq 'HASH'); return $y; }); $prototype->optional_arg foo_arg2 => sub { my ($x, $y) = (shift, undef); $y = 'not a CODE reference' unless (ref $x eq 'CODE'); return $y; }); sub foo($%) { my ($this, %arg) = @_; my $error = $prototype->validate(\%arg); croak __PACKAGE__, "::foo-- $error" if $error; # use $arg{foo_arg1} with confidence that it exists and its value # is a HASH reference, and that $arg{foo_arg2} either does not exist, # or it exists and its value is a CODE reference. } DESCRIPTION =========== The `Conjury::Core::Prototype' module is a general purpose function prototype verifier, included in the Conjury distribution as a convenience. Use the `Conjury::Core::Prototype-'new> method to construct an instance of the prototype verifier for a particular function. Use the `required_arg' method to add a required argument to the function prototype. Use the `optional_arg' method to add an optional argument to the function prototype. Both methods require two parameters, the name of the argument, and a reference to a subroutine that validates the argument and returns a descriptive message if the argument violates the prototype. When the validate method is called on the prototype (with a reference to a hash containing the function arguments), each argument is passed to the parameter verifier function that was associated with the parameter name when the prototype was constructed. If none of the verifiers return a value then the argument list fits the prototype and the validate method returns undefined. Otherwise, the validate method returns an error code suitable for use in a call to croak. AUTHOR ====== James Woodyatt <`jhw@wetware.com'>  File: pm.info, Node: Continuus, Next: ControlX10/CM11, Prev: Conjury/Core/Prototype, Up: Module List Perl interface to Continuus CM ****************************** NAME ==== Continuus - Perl interface to Continuus CM SYNOPSIS ======== use Continuus; Check out a file: use Continuus; $ccm = new Continuus; $ccm->start(database => '/proj/Continuus4/rig', host => 'stoxserv01'); $ccm->checkOut(file => 'main.c', version => '2'); $ccm->stop(); DESCRIPTION =========== The Continuus perl module is a interface to the most common Continuus functions. CHANGE HISTORY ============== 0.1 Created. METHODS ======= new: The new method creates a new Continuus object. start: The start method starts a new Continuus session. Parameters: database: Database to open. host: Hostname to start the engine on. iniFile: Ini file to read. Example: $ccm->start(database => "/proj/Continuus0/rig/", host => "stoccm01"); command: The command method acts as a interface to all other Continuus functions not implemented in the Continuus module. Parameters: command: The command to be executed by Continuus Example: $ccm->command('status'); stop: The stop command quits the current Continuus session. Parameters: None. query: The query command is a interface to the Continuus query command. Parameters: query: The query string flags: Flags to pass to Continuus. Format: Formatting options. Example: $ccm->query(query => "status='released'", flags => "-u", format => "%objectname"); checkOut: Checks out a file. Parameters: file: The file to check out. version: The version to set on the new file. Example: $ccm->checkOut(file => "main.c", version => "1.1"); checkIn: Checks in a file. Parameters: file: The file to check out. comment: The comment to set on the new file. Example: $ccm->checkIn(file => "main.c", comment => "Created"); reconfigure: Reconfigure command Parameters: project: The project to reconfigure. parameters: Other parameters to pass to the reconfigure command. Example: $ccm->checkOut(file => "main.c", version => "1.1"); debugOn: Sets the debugging information on. debugOff: Sets the debugging information off. AUTHOR ====== Henrik Jönsson henrik7205@hotmail.com  File: pm.info, Node: ControlX10/CM11, Next: ControlX10/CM17, Prev: Continuus, Up: Module List Perl extension for X10 'ActiveHome' Controller ********************************************** NAME ==== ControlX10::CM11 - Perl extension for X10 'ActiveHome' Controller SYNOPSIS ======== use ControlX10::CM11; # $serial_port is an object created using Win32::SerialPort # or Device::SerialPort depending on OS # my $serial_port = setup_serial_port('COM10', 4800); $data = &ControlX10::CM11::receive_buffer($serial_port); $data = &ControlX10::CM11::read($serial_port, $no_block); $percent = &ControlX10::CM11::dim_level_decode('GE'); # 40% &ControlX10::CM11::send($serial_port, 'A1'); # Address device A1 &ControlX10::CM11::send($serial_port, 'AJ'); # Turn device ON # House Code 'A' present in both send() calls &ControlX10::CM11::send($serial_port, 'B'.'ALL_OFF'); # Turns All lights on house code B off DESCRIPTION =========== The CM11A is a bi-directional X10 controller that connects to a serial port and transmits commands via AC power line to X10 devices. This module translates human-readable commands (eg. 'A2', 'AJ') into the Interface Communication Protocol accepted by the CM11A. send command This transmits a two-byte message containing dim and house information and either an address or a function. Checksum and acknowledge handshaking is automatic. The command accepts a string parameter. The first character in the string must be a *House Code* in the range [A..P] and the rest of the string determines the type of message. Intervening whitespace is not currently permitted between the *House Code* and the Operation. This may change in the future. STRING ALTERNATE_STRING FUNCTION 1..9 Unit Address A..G Unit Address J ON Turn Unit On K OFF Turn Unit Off L BRIGHT Brighten Last Light Programmed 5% M DIM Dim Last Light Programmed 5% O ALL_ON All Units On P ALL_OFF All Units Off There are also functions without "shortcut" letter commands: ALL_LIGHTS_OFF EXTENDED_CODE EXTENDED_DATA HAIL_REQUEST HAIL_ACK PRESET_DIM1 PRESET_DIM2 STATUS_ON STATUS_OFF STATUS Dim and Bright functions can also take a signed value in the range [-95,-90,...,-10,-5,+5,+10,...,+90,+95]. ControlX10::CM11::send($serial_port,'A1'); # Address device A1 ControlX10::CM11::send($serial_port,'AJ'); # Turn device ON ControlX10::CM11::send($serial_port,'A-25'); # Dim to 25% send extended function Starting in version 2.04, extended commands may be sent to devices that support the enhanced X10 protocol. If you have one of the newer (more expensive) LM14A/PLM21 2 way X10 pro lamp modules, you can set it directly to a specific brightness level using a Preset Dim extended code. The 64 extended X10 Preset Dim codes are commanded by appending `&##' to the unit address where `##' is a number between 1 and 63. ControlX10::CM11::send($serial_port,'A5&P16'); # Dim A5 to 25% A partial translation list for the most important levels: &P## % &P## % &P## % 0 0 13 20 44 70 1 2 16 25 47 75 2 4 19 30 50 80 3 5 25 40 57 90 6 10 31 50 61 95 9 15 38 60 63 100 There is another set of Preset Dim commands that are used by some modules (e.g. the RCS TX15 thermostat). These 32 non-extended Preset Dim codes can be coded directly, using the following table: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 PRESET_DIM1 M N O P C D A B E F G H K L I J 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 PRESET_DIM2 M N O P C D A B E F G H K L I J This usage, and the responses assigned to each command, are device specific. For example, the following commands enable preset value 18: ControlX10::CM11::send($serial_port,'M4'); # Address thermostat ControlX10::CM11::send($serial_port,'OPRESET_DIM2'); # Select preset 18 Starting in version 2.07, incoming extended data is also processed. The first character will be the *House Code* in the range [A..P]. The next character will be *Z*, indicating extended data. The remaining data will be the extended data. read This checks for an incoming transmission. It will return "" for no input. It also tests for a received a "power fail" message (0xa5). If it detects one, it automatically sends the command/data to reset the CM11 clock. If the `$no_block' parameter is FALSE (0, "", or undef), the read will retry for up to a second at 50 millisecond intervals. With `$no_block' TRUE, the read checks one time for available data. $data = &ControlX10::CM11::read($serial_port, $no_block); receive_buffer This command handles the upload response to an "Interface Poll Signal" message (0x5a) read from the CM11. The module sends "ready" (0xc3) and receives up to 10 bytes. The first two bytes are size and description of the remaining bytes. These are used to decode the data bytes, but are not returned by the receive_buffer function. Each of the data bytes is decoded as if it was a send command from an external CM11 or equivalent external source (such as an RF keypad). $data = &ControlX10::CM11::receive_buffer($serial_port); # $data eq "A2AK" after an external device turned off A2 Multiple house and unit addresses can appear in a single buffer. if ($data eq "B1BKA2AJ") { print "B1 off, A2 on\n"; } dim_level_decode When the external command includes dim/bright information in addition to the address and function, the dim_level_decode function converts that data byte (as processed by the receive_buffer command) into percent. $data = &ControlX10::CM11::receive_buffer($serial_port); # $data eq "A2AMGE" after an external device dimmed A2 to 40% $percent = &ControlX10::CM11::dim_level_decode("GE"); # $percent == 40 A more complex $data input is possible. if ($data eq "B1B3B5B7B9BLLE") { print "House B Inputs 1,3,5,7,9 Brightened to 85%\n"; } The conversion between text_data and percent makes more sense to the code than to humans. The following table gives representative values. Others may be received from a CM11 and will be properly decoded. Percent Text Percent Text 0 M7 50 AA 5 ED 55 I6 10 EC 60 NF 15 C7 65 N2 20 KD 70 F6 25 K4 75 DB 30 O7 80 D2 35 OA 85 LE 40 G6 90 PB 45 AF 95 P8 The *send_cm11*, *receive_cm11*, *read_cm11*, and *dim_decode_cm11* functions are exported by default starting with Version 2.09. They are identical to the "fully-qualified" names and accept the same parameters. The *export on request* tag `:FUNC' is maintained for compatibility (but deprecated). use ControlX10::CM11; send_cm11($serial_port, 'A1'); # send() - address send_cm11($serial_port, 'AJ'); # send() - function $data = receive_cm11($serial_port); # receive_buffer() $data = read_cm11($serial_port, $no_block); # read() $percent = dim_decode_cm11('GE'); # dim_level_decode() AUTHORS ======= Bruce Winter bruce@misterhouse.net http://misterhouse.net CPAN packaging by Bill Birthisel wcbirthisel@alum.mit.edu http://members.aol.com/bbirthisel MAILING LISTS ------------- General information about the mailing lists is at: http://lists.sourceforge.net/mailman/listinfo/misterhouse-users http://lists.sourceforge.net/mailman/listinfo/misterhouse-announce To post to this list, send your email to: misterhouse-users@lists.sourceforge.net If you ever want to unsubscribe or change your options (eg, switch to or from digest mode, change your password, etc.), visit your subscription page at: http://lists.sourceforge.net/mailman/options/misterhouse-users/$user_id SEE ALSO ======== mh can be download from http://misterhouse.net Win32::SerialPort and Device::SerialPort from CPAN CM11A Protocol documentation available at http://www.x10.com perl(1). COPYRIGHT ========= Copyright (C) 2000 Bruce Winter. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 30 January 2000.