This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Spreadsheet/WriteExcel/BIFFwriter, Next: Spreadsheet/WriteExcel/Format, Prev: Spreadsheet/WriteExcel, Up: Module List An abstract base class for Excel workbooks and worksheets. ********************************************************** NAME ==== BIFFwriter - An abstract base class for Excel workbooks and worksheets. SYNOPSIS ======== See the documentation for Spreadsheet::WriteExcel DESCRIPTION =========== This module is used in conjunction with Spreadsheet::WriteExcel. AUTHOR ====== John McNamara jmcnamara@cpan.org COPYRIGHT ========= © MM-MMI, John McNamara. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.  File: pm.info, Node: Spreadsheet/WriteExcel/Format, Next: Spreadsheet/WriteExcel/Formula, Prev: Spreadsheet/WriteExcel/BIFFwriter, Up: Module List A class for defining Excel formatting. ************************************** NAME ==== Format - A class for defining Excel formatting. SYNOPSIS ======== See the documentation for Spreadsheet::WriteExcel DESCRIPTION =========== This module is used in conjunction with Spreadsheet::WriteExcel. AUTHOR ====== John McNamara jmcnamara@cpan.org COPYRIGHT ========= © MM-MMI, John McNamara. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.  File: pm.info, Node: Spreadsheet/WriteExcel/Formula, Next: Spreadsheet/WriteExcel/OLEwriter, Prev: Spreadsheet/WriteExcel/Format, Up: Module List A class for generating Excel formulas ************************************* NAME ==== Formula - A class for generating Excel formulas SYNOPSIS ======== See the documentation for Spreadsheet::WriteExcel DESCRIPTION =========== This module is used in conjunction with Spreadsheet::WriteExcel. It should not be used directly. The following notes are to help developers and maintainers understand the sequence of operation. They are also intended as a pro-memoria for the author. ;-) Spreadsheet::WriteExcel::Formula converts a textual representation of a formula into the pre-parsed binary format that Excel uses to store formulas. For example `1+2*3' is stored as follows: `1E 01 00 1E 02 00 1E 03 00 05 03'. This string is comprised of operators and operands arranged in a reverse-Polish format. The meaning of the tokens in the above example is shown in the following table: Token Name Value 1E ptgInt 0001 (stored as 01 00) 1E ptgInt 0002 (stored as 02 00) 1E ptgInt 0003 (stored as 03 00) 05 ptgMul 03 ptgAdd The tokens and token names are defined in the "Excel Developer's Kit" from Microsoft Press. `ptg' stands for Parse ThinG (as in "That lexer can't grok it, it's a parse thang.") In general the tokens fall into two categories: operators such as `ptgMul' above and operands such as `ptgInt'. When the formula is evaluated by Excel the operand tokens push values onto a stack. The operator tokens then pop the required number of operands from the stack, perform an operation and push the resulting value back onto the stack. This methodology is similar to the basic operation of a reverse-Polish (RPN) calculator. Spreadsheet::WriteExcel::Formula parses a formula using a Parse::RecDescent parser (at a later stage it may use a `Parse::Yapp' parser). The parser converts the textual representation of a formula into a parse tree. Thus, `1+2*3' is converted into something like the following, e stands for expression: e / | \ 1 + e / | \ 2 * 3 The function `_reverse_tree()' recurses down through this structure swapping the order of operators followed by operands to produce a reverse-Polish tree. Following the above example the resulting tree would look like this: e / | \ 1 e + / | \ 2 3 * The result of the recursion is a single array of tokens. In our example the simplified form would look like the following: (1, 2, 3, *, +) The actual return value contains some additional information to help in the secondary parsing stage: (_num, 1, _num, 2, _num, 3, ptgMul, ptgAdd, _arg, 1) The additional tokens are: Token Meaning _num The next token is a number _str The next token is a string _ref The next token is a cell reference _rng The next token is a range _fnc The next token is a function _arg The next token is a the number of args for a function The `_arg' token is generated for all lists but is only used for functions the take a variable number of arguments. A secondary parsing stage is carried out by `_parse_tokens()' which converts these tokens into a binary string. For the `1+2*3' example this would give: 1E 01 00 1E 02 00 1E 03 00 05 03 This two-pass method could probably have been reduced to a single pass through the Parse::RecDescent parser. However, it was easier to develop and debug this way. The token values and formula values are stored in the `%ptg' and `%functions' hashes. These hashes and the parser object $parser are exposed as global data. This breaks the OO encapsulation, but means that they can be shared by several instances of Spreadsheet::WriteExcel called from the same program. The parser is initialised by `_init_parser()'. The initialisation is delayed until the first formula is parsed. This eliminates the overhead of generating the parser in programs that are not processing formulas. (The parser should really be pre-compiled, this is to-do when the grammar stabilises). AUTHOR ====== John McNamara jmcnamara@cpan.org COPYRIGHT ========= © MM-MMI, John McNamara. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.  File: pm.info, Node: Spreadsheet/WriteExcel/OLEwriter, Next: Spreadsheet/WriteExcel/Workbook, Prev: Spreadsheet/WriteExcel/Formula, Up: Module List A writer class to store BIFF data in a OLE compound storage file. ***************************************************************** NAME ==== OLEwriter - A writer class to store BIFF data in a OLE compound storage file. SYNOPSIS ======== See the documentation for Spreadsheet::WriteExcel DESCRIPTION =========== This module is used in conjunction with Spreadsheet::WriteExcel. AUTHOR ====== John McNamara jmcnamara@cpan.org COPYRIGHT ========= © MM-MMI, John McNamara. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.  File: pm.info, Node: Spreadsheet/WriteExcel/Workbook, Next: Spreadsheet/WriteExcel/Worksheet, Prev: Spreadsheet/WriteExcel/OLEwriter, Up: Module List A writer class for Excel Workbooks. *********************************** NAME ==== Workbook - A writer class for Excel Workbooks. SYNOPSIS ======== See the documentation for Spreadsheet::WriteExcel DESCRIPTION =========== This module is used in conjunction with Spreadsheet::WriteExcel. AUTHOR ====== John McNamara jmcnamara@cpan.org COPYRIGHT ========= © MM-MMI, John McNamara. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.  File: pm.info, Node: Spreadsheet/WriteExcel/Worksheet, Next: Spreadsheet/WriteExcel/examples/WorkbookBig, Prev: Spreadsheet/WriteExcel/Workbook, Up: Module List A writer class for Excel Worksheets. ************************************ NAME ==== Worksheet - A writer class for Excel Worksheets. SYNOPSIS ======== See the documentation for Spreadsheet::WriteExcel DESCRIPTION =========== This module is used in conjunction with Spreadsheet::WriteExcel. AUTHOR ====== John McNamara jmcnamara@cpan.org COPYRIGHT ========= © MM-MMI, John McNamara. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.  File: pm.info, Node: Spreadsheet/WriteExcel/examples/WorkbookBig, Next: Sprite, Prev: Spreadsheet/WriteExcel/Worksheet, Up: Module List A writer class for Excel Workbooks. *********************************** NAME ==== Workbook - A writer class for Excel Workbooks. SYNOPSIS ======== See the documentation for Spreadsheet::WriteExcel DESCRIPTION =========== This module is used in conjuction with Spreadsheet::WriteExcel. AUTHOR ====== John McNamara jmcnamara@cpan.org COPYRIGHT ========= Copyright (c) 2000, John McNamara. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.  File: pm.info, Node: Sprite, Next: Startup, Prev: Spreadsheet/WriteExcel/examples/WorkbookBig, Up: Module List Module to manipulate text delimited databases using SQL. ******************************************************** NAME ==== Sprite - Module to manipulate text delimited databases using SQL. SYNOPSIS ======== use Sprite; $rdb = new Sprite; $rdb->set_delimiter (-Read => '::') ## OR: ('Read', '::'); $rdb->set_delimiter (-Write => '::') ## OR: ('Write', '::'); $rdb->set_os ('Win95'); ## Valid arguments (case insensitive) include: ## ## Unix, Win95, Windows95, MSDOS, NT, WinNT, OS2, VMS, ## MacOS or Macintosh. Default determined by $^O. $rdb->set_lock_file ('c:\win95\tmp\Sprite.lck', 10); $rdb->set_db_dir ('Mac OS:Perl 5:Data') || die "Can't access dir!\n"; $data = $rdb->sql (<sql (<close; $rdb->close ($database); ## To save updated database DESCRIPTION =========== Here is a simple database where the fields are delimited by commas: Player,Years,Points,Rebounds,Assists,Championships ... Larry Bird,13,25,11,7,3 Michael Jordan,14,29,6,5,5 Magic Johnson,13,22,7,11,5 ... Note: The first line must contain the field names (case sensitive). Supported SQL Commands ====================== Here are a list of the SQL commands that are supported by Sprite: select - retrieves records that match specified criteria: select col1 [,col2] from database where (cond1 OPERATOR value1) [and|or (cond2 OPERATOR value2) ...] The '*' operator can be used to select all columns. The database is simply the file that contains the data. If the file is not in the current directory, the path must be specified. Sprite does not support multiple tables (or commonly knows as "joins"). Valid column names can be used where [cond1..n] and [value1..n] are expected, such as: Example 1: select Player, Points from my_db where (Rebounds > Assists) The following SQL operators can be used: =, <, >, <=, >=, <> as well as Perl's special operators: =~ and !~. The =~ and !~ operators are used to specify regular expressions, such as: Example 2: select * from my_db where (Name =~ /Bird$/i) Selects records where the Name column ends with "Bird" (case insensitive). For more information, look at a manual on regexps. Note: A path to a database can contain only the following characters: \w, \x80-\xFF, -, /, \, ., : If you have directories with spaces or other 'invalid' characters, you need to use the set_db_dir method. update - updates records that match specified criteria. update database set cond1 = (value1)[,cond2 = (value2) ...] where (cond1 OPERATOR value1) [and|or (cond2 OPERATOR value2) ...] Example: update my_db set Championships = (Championships + 1) where (Player = 'Larry Bird') update my_db set Championships = (Championships + 1), Years = (12) where (Player = 'Larry Bird') delete - removes records that match specified criteria: delete from database where (cond1 OPERATOR value1) [and|or (cond2 OPERATOR value2) ...] Example: delete from my_db where (Player =~ /Johnson$/i) or (Years > 12) alter - simplified version of SQL-92 counterpart Removes the specified column from the database. The other standard SQL functions for alter table are not supported: alter table database drop column column-name alter table database add column column-name Example: alter table my_db drop column Years alter table my_db add column Legend insert - inserts a record into the database: insert into database (col1, col2, ... coln) values (val1, val2, ... valn) Example: insert into my_db (Player, Years, Points, Championships) values ('Kareem Abdul-Jabbar', 21, 26, 6) You don't have to specify all of the fields in the database! Sprite also does not require you to specify the fields in the same order as that of the database. Note: You should make it a habit to quote strings. METHODS ======= Here are the available methods: set_delimiter The set_delimiter function sets the read and write delimiter for the database. The delimiter is not limited to one character; you can have a string, and even a regexp (for reading only). *Return Value* None set_os The set_os function can be used to notify Sprite as to the operating system that you're using. Default is determined by $^O. Note: If you're using Sprite on Windows 95/NT or on OS2, make sure to use backslashes - and NOT forward slashes - when specifying a path for a database or to the set_db_dir or set_lock_file methods! *Return Value* None set_lock_file For any O/S that doesn't support flock (i.e Mac, Windows 95 and VMS), this method allows you to set a lock file to use and the number of tries that Sprite should try to obtain a 'fake' lock. However, this method is NOT fully reliable, but is better than no lock at all. 'Sprite.lck' (either in the directory specified by set_db_dir or in the current directory) is used as the default lock file if one is not specified. *Return Value* None set_db_dir A path to a database can contain only the following characters: \w, \x80-\xFF, -, /, \, ., : If your path contains other characters besides the ones listed above, you can use this method to set a default directory. Here's an example: $rdb->set_db_dir ("Mac OS:Perl 5:Data"); $data = $rdb->sql ("select * from phone.db"); Sprite will look for the file "Mac OS:Perl 5:Data:phone.db". Just to note, the database filename cannot have any characters besides the one listed above! *Return Value* 0 - Failure 1 - Success sql The sql function is used to pass a SQL command to this module. All of the SQL commands described above are supported. The select SQL command returns an array containing the data, where the first element is the status. All of the other other SQL commands simply return a status. *Return Value* 1 - Success 0 - Error close The close function closes the file, and destroys the database object. You can pass a filename to the function, in which case Sprite will save the database to that file; the directory set by set_db_dir is used as the default. *Return Value* None NOTES ===== Sprite is not the solution to all your data manipulation needs. It's fine for small databases (less than 1000 records), but anything over that, and you'll have to sit there and twiddle your fingers while Sprite goes chugging away ... and returns a few *seconds* or so later. The main advantage of Sprite is that you can use Perl's regular expressions to search through your data. Yippee! SEE ALSO ======== Text::CSV, RDB ACKNOWLEDGEMENTS ================ I would like to thank the following, especially Rod Whitby and Jim Esten, for finding bugs and offering suggestions: Rod Whitby (rwhitby@geocities.com) Jim Esten (jesten@wdynamic.com) Dave Moore (dmoore@videoactv.com) Shane Hutchins (hutchins@ctron.com) Josh Hochman (josh@bcdinc.com) Barry Harrison (barryh@topnet.net) Lisa Farley (lfarley@segue.com) Loyd Gore (lgore@ascd.org) Tanju Cataltepe (tanju@netlabs.net) Haakon Norheim (hanorhei@online.no) COPYRIGHT INFORMATION ===================== Copyright (c) 1995-1998, Shishir Gundavaram All Rights Reserved Permission to use, copy, and distribute is hereby granted, providing that the above copyright notice and this permission appear in all copies and in supporting documentation.  File: pm.info, Node: Startup, Next: Stat/lsMode, Prev: Sprite, Up: Module List A program flow utility. *********************** NAME ==== Startup - A program flow utility. *ALPHA* version as of `$Date: 1998/04/28 00:38:41 $' SYNOPSIS ======== Have a look at demonstration utility "replace" and at more detailed description below. It might be useful to use "replace" generally as frame for new programs. DESCRIPTION =========== As developing with perl you certainly appreciate it to write easily nifty programs. Unfortunately a bunch of boring problems makes life uncomfortable. With some of them I had to deal so often, that I created this little collection. Imagine: - You want to have an option to work on files recursively. - You want some modules to print some info during work, but this output would hardly be predictable and thus might destroy your program output. - You want to have a little logfile reporting actions. - You want to report errors, but not via "die", and you dislike to write trapping code all the time. This module shall contribute to solve those problems, making your your programs more valuable. INIT METHODS ============ new *$S* = new S This is the modules constructor. Some basic initializations are done, as there are: msg_reset and forbid_logging are called; err_strpat, err_infopat and log_openpat are initialized and log_threshold is set to infinity. init 1 = *$S* -> init ({ SUB_FILES => *\&sub*, # no default SUB_STREAM => *\&sub*, # no default PROG_DATE => *$date*, # no default PROG_NAME => $name, # no default PROG_VER => *$version*, # no default DIRMODE => $string, # Default: "0700" FILEMODE => $string, # Default: "0600" FROM_STDIN => 1||0, # Default: 0 RECURSE => 1||0, # Default: 0 RELATIVE => 1||0, # Default: 0 DESTPATH => $path, # Default: '.' SRCPATH => $path, # Default: '.' LOGPATH => $path, # Default: "$prog_name.log" }) This method you normally will have to call. Via this you pass information like recursive and / or relative mode, program name and version and so on. Init method will provide some default values. Init is called with an anonymous hash as parameter list. Each parameter you can change afterwards with an extra method. Quite necessary (but this depends on your wishes) is to init at least SUB_FILES and PROG_NAME. go 1||0 = *$S* -> go (*@pathes*) Works differently for stream mode and file mode. Anyway go will call a function in your application, that needs to return a true value (1) if successful. If your function returns a zero, go will call msg_error(). Method go normally always returns 1. Zero is returned, when SUB_FILES or SUB_STREAM is needed but not defined, or if src_base or current directory is not available. go: stream mode Message mode is set to silent. Function provided via SUB_STREAM is called with parameter dest_path. go: file mode Function provided via SUB_FILES is called for each input file. Parameters are (Source_purepath $sp, Source_purefilename *$sf*, Destination_path *$dp*, $status). Thus path for input file would be: "$sp/*$sf*". *$dp* will be the path provided via DESTPATH if either relative mode is unset, or the input file path is not relative to the path provided via SRCPATH. If in relative mode and input file has a path relative to SRCPATH, *$dp* will get that relative part starting from DESTPATH. $status will be 1 if input file is a file, 0 if file doesn't exist and `-1' if file is no file but a directory. sub_stream *\&function* = *$S* -> sub_stream ([*\&function*]) Returns (optionally sets) the function doing the work when in stream mode. sub_files *\&function* = *$S* -> sub_files ([*\&function*]) Returns (optionally sets) the function doing the work when in file mode. src_base $path = *$S* -> src_base ([$path]) Returns (optionally sets) the base path for source input files. dest_base $path = *$S* -> dest_base ([$path]) Returns (optionally sets) the base destination path for your output files. from_stdin 1||0 = *$S* -> from_stdin ([1||0]) Returns (optionally sets) stream mode. dir_mode *$mode_string* = *$S* -> dir_mode ([*$mode_string*]) Returns (optionally sets) the owning mode when creating a new directory. Mode is evaluated as an octal number in string representation, e.g. "0700". file_mode *$mode_string* = *$S* -> file_mode ([*$mode_string*]) Returns (optionally sets) the owning mode when creating a file (as of now this is only when creating logfile). Mode is evaluated as an octal number in string representation, e.g. "0700". recurse 1||0 = *$S* -> recurse ([1||0]) Returns (optionally sets) recurse mode. When in recurse mode, directories and directories in directories and ... of input file list will be scanned also. relative 1||0 = *$S* -> relative ([1||0]) Returns (optionally sets) relative mode. Effects only in recurse mode. When in relative mode, output pathes will be created according to input path structure relatively to input base path. E.g.: Input base path is `/cdrom'. Scan path is `/cdrom'. Output path is .. Then starting at path . the same directory structure as in /cdrom/ would be created and passed to sub_files function as output path. prog_date *$date* = *$S* -> prog_date ([*$date*]) Returns (optionally sets) date of application programs creation. prog_name $name = *$S* -> prog_name ([$name]) Returns (optionally sets) name of application program. prog_ver *$ver* = *$S* -> prog_ver ([*$ver*]) Returns (optionally sets) version of application program. ERROR METHODS ============= Error is just a way to get around $!. It is little more than a place to store an error message. It allows you to return 0 as error indicator in a pure procedurale way over several returns and still to comprise "last error" information. error 0 = *$S* -> error ($string, *$number*, *$longinfo*) Saves error message $string, error number *$number*, extra error information *$longinfo* and caller() info. Returns always zero. err_caller *\@err_caller* = *$S* -> err_caller (*[caller()]*) Returns (and optionally sets) a reference to a caller() array (see: man perlfunc). It has the entries (package, filename, line). It is automatically set to "caller()" when calling error method. err_info *$err_info* = *$S* -> err_info ([*$err_info*]) Returns (and optionally sets) error info message, formatted according to err_infopat. err_infopat *$err_infopat* = *$S* -> err_infopat ([*$err_infopat*]) Gimmick pattern for method err_info. Defaults to `'$err_info''. (See method gimmick below at misc section for details) err_num *$err_num* = *$S* -> err_num ([*$err_num*]) Returns (and optionally sets) error number. err_str *$err_str* = *$S* -> err_str ([*$err_str*]) Returns (and optionally sets) error message, formatted according to err_strpat. err_strpat *$err_strpat* = *$S* -> err_strpat ([*$err_strpat*]) Gimmick pattern for method err_str. Defaults to `'$err_package: $err_str''. (See method gimmick below at misc section for details) MESSAGE METHODS =============== Message is a userEss interface allowing you to pass some runtime information to stdout. msg 1 = *$S* -> msg ($str) Prints message $str. Appends ':' if it is 1st message, inserts `' '' if it is 2nd, appends `', '' otherwise. msg_error 0 = *$S* -> msg_error ([str]) Calls `msg_nl ("error!")' and then `msg ("Error: " . $S-'err_str())>. Latter message will be sent even in "silent" mode (see msg_silent). msg_finish 1 = *$S* -> msg_finish ($str) Calls `msg_nl ("$msg.")' unless msg_finish is already called. msg_nl 1 = *$S* -> msg_nl ($str) Prints message $str with a trailing newline \n. Disables internal "continue" mode: further messages will always be sent as msg_nl. msg_warn 1 = *$S* -> msg_warn ($str) Appends a '!' to message $str. MESSAGE INIT METHODS ==================== charset *$charset_id* = *$S* -> charset ($charset_id) Sets standard character set to *$charset_id*. It defaults to $ENV{LC_CTYPE}. It's main purpose is for future releases. msg_reset *$S* = *$S* -> msg_reset () Resets message variables to default values. You will call this normally always when starting a new work a la: 'Processing xyz'. msg_autoindent 1||0 = *$S* -> msg_autoindent ([1||0]) Defaults to 1. Returns (optionally sets) autoindent mode. When set, msg_indent will be automatically set to the position after the first whitespace in the first message. (see also msg_beauty) msg_beauty 1||0 = *$S* -> msg_beauty ([1||0]) Defaults to 1. Returns state of (optionally sets) "beauty" mode. When an output line gets longer than msg_maxcolumn and internal "continue" mode is set, a newline and an indent is inserted. Internal continue mode is unset when calling msg_nl method. msg_indent *$pos* = *$S* -> msg_indent ([*$pos*]) Defaults to 4. Returns (optionally defines) the indent for beauty mode. This value is overridden when msg_autoindent is set. msg_maxcolumn *$pos* = *$S* -> msg_maxcolumn ([*$pos*]) Defaults to 79. Returns (optionally sets) the maximal length of an output line, when in beauty mode. msg_silent 1||0 = *$S* -> msg_silent ([1||0]) Defaults to 0. Returns (optionally sets) silent mode. When set to 1, no message except error messages will be printed to stdout. LOGGING METHODS =============== allow_logging 1 = *$S* -> allow_logging () You have to call this to enable logging. forbid_logging 0 = *$S* -> forbid_logging () This is default. It forbids methods open_log and log, so that they will return always an error. No logfile will be opened, no log entry being written. log_openpat *$pat* = *$S* -> log_openpat ([I<$pat]) Returns (optionally sets) the gimmick pattern used for log opening entries. Defaults to: `'---------- $date, $prog_name $prog_ver '."(perl $])\n"' log_path $path = *$S* -> log_path ([$path]) Returns (optionally sets) path/name of logfile to $path. This overrides the default value set when calling S->init. Default is file `basename($prog_name).".log"' in current directory. open_log 1||0 = *$S* -> open_log () Opens the logfile *$S* -> log_path. close_log 1 = *$S* -> close_log () Closes logfile. log 1||0 = *$S* -> log ($msg, *$pri*, *$threshold*) Adds a log message $msg, getting the priority character *$pri*. If a threshold is given, log this entry only if threshold is smaller or equal *$S* -> log_threshold. log_threshold *$threshold* = *$S* -> log_threshold ([*$threshold*]) Defaults to 0xffffffff. Returns (optionally sets) logging threshold. If set, only log calls with a threshold smaller or equal than this threshold will be logged. REDIRECTION METHODS =================== catch_output 1||0 = *$S* -> catch_output([*$mode_path*]) 1||0 = *$S* -> catch_stdout([*$mode_path*]) 1||0 = *$S* -> catch_stderr([*$mode_path*]) catch_output File mode If parameter *$mode_path* is specified, STDOUT+STDERR / STDOUT / STDERR will be redirected to a file. *$mode_path* is simply given to an open call, so you might use this like: $S -> catch_output(">>my_stdout_stderr.txt"); catch_output Pipe mode If parameter *$mode_path* is omitted, STDOUT+STDERR / STDOUT / STDERR will be sent to the input of a child process. This will check it's input if it is according to catch_output_pattern. If so, it will send STDOUT messages to $S->msg and STDERR messages to $S->msg_error. Note, that $S->msg and $S->msg_error are sending their output to your STDOUT. If you like to get the output passed catch_output_pattern yourself rather than printing it via msg or msg_error, you can pass a code reference to catch_output_sub. This function will then be called with matched output as parameter. catch_output_sub *\&sub* = *$S* -> catch_output_sub([*\&sub*]) *\&sub* = *$S* -> catch_stdout_sub([*\&sub*]) *\&sub* = *$S* -> catch_stderr_sub([*\&sub*]) Returns (optionally sets) the code reference, that will be called when some output passed catch_output_pattern in Pipe mode. restore_output 1||0 = *$S* -> restore_output() 1||0 = *$S* -> restore_stdout() 1||0 = *$S* -> restore_stderr() Restores the output that has been redirected via catch_output. catch_output_pattern *$pattern* = *$S* -> catch_output_pattern([*$pattern*]) *$pattern* = *$S* -> catch_stdout_pattern([*$pattern*]) *$pattern* = *$S* -> catch_stderr_pattern([*$pattern*]) When output is redirected, only those output lines will be regarded, that match $1 of this pattern. Default is: `'^(.*)$''. MISCELLANEOUS METHODS ===================== gimmick *$gimicked_string* = *$Startup* -> gimmick (*$control_string*) Replaces certain strings in a control string. You can use: $S Seconds $M Minutes $H Hour $d day $m month $y year $date '$d.$m.$y' $time '$H:$M:$S' $err_str current error string $err_num current error number $err_info current error info (longer text) $err_package package calling error method $err_filename filename of package $err_line line in package calling error method $prog_name program name (if set by application) $prog_date program date (if set by application) $prog_ver program version (if set by application) TO DO ===== Lots. SEE ALSO ======== AUTHOR ====== Martin Schwartz <`schwartz@cs.tu-berlin.de'>  File: pm.info, Node: Stat/lsMode, Next: Statistics/Candidates, Prev: Startup, Up: Module List format file modes like the `ls -l' command does *********************************************** NAME ==== Stat::lsMode - format file modes like the `ls -l' command does SYNOPSIS ======== use Stat::lsMode; $mode = (stat $file)[2]; $permissions = format_mode($mode); # $permissions is now something like `drwxr-xr-x' $permissions = file_mode($file); # Same as above $permissions = format_perms(0644); # Produces just 'rw-r--r--' $permissions = format_perms(644); # This generates a warning message: # mode 644 is very surprising. Perhaps you meant 0644... Stat::lsMode->novice(0); # Disable warning messages DESCRIPTION =========== `Stat::lsMode' generates mode and permission strings that look like the ones generated by the Unix `ls -l' command. For example, a regular file that is readable by everyone and writable only by its owner has the mode string `-rw-r--r--'. `Stat::lsMode' will either examine the file and produce the right mode string for you, or you can pass it the mode that you get back from Perl's stat call. `format_mode' ------------- Given a mode number (such as the third element of the list returned by stat), return the appopriate ten-character mode string as it would have been generated by `ls -l'. For example, consider a directory that is readable and searchable by everyone, and also writable by its owner. Such a directory will have mode 040755. When passed this value, `format_mode' will return the string `drwxr-xr-x'. If `format_mode' is passed a permission number like `0755', it will return a nine-character string insted, with no leading character to say what the file type is. For example, `format_mode(0755)' will return just `rwxr-xr-x', without the leading d. file_mode --------- Given a filename, do lstat on the file to determine the mode, and return the mode, formatted as above. Novice Operation Mode --------------------- A common mistake when dealing with permission modes is to use `644' where you meant to use `0644'. Every permission has a numeric representation, but the representation only makes sense when you write the number in octal. The decimal number 644 corresponds to a permission setting, but not the one you think. If you write it in octal you get 01204, which corresponds to the unlikely permissions `-w----r-T', not to `rw-r--r--'. The appearance of the bizarre permission `-w----r-T' in a program is almost a sure sign that someone used `644' when they meant to use `0644'. By default, this module will detect the use of such unlikely permissions and issue a warning if you try to format them. To disable these warnings, use Stat::lsMode->novice(0); # disable novice mode Stat::lsMode->novice(1); # enable novice mode again The surprising permissions that are diagnosed by this mode are: 111 => --xr-xrwx 400 => rw--w---- 440 => rw-rwx--- 444 => rw-rwxr-- 551 => ---r--rwt 600 => --x-wx--T 640 => -w------T 644 => -w----r-T 660 => -w--w-r-T 664 => -w--wx--T 666 => -w--wx-wT 700 => -w-rwxr-T 711 => -wx---rwt 750 => -wxr-xrwT 751 => -wxr-xrwt 751 => -wxr-xrwt 755 => -wxrw--wt 770 => r------wT 771 => r------wt 775 => r-----rwt 777 => r----x--t Of these, only 400 is remotely plausible. BUGS ==== As far as I know, the precise definition of the mode bits is portable between varieties of Unix. The module should, however, examine `stat.h' or use some other method to find out if there are any local variations, because Unix being Unix, someone somewhere probably does it differently. Maybe it file_mode should have an option that says that if the file is a symlink, to format the mode of the pointed to file instead of the mode of the link itself, the way `ls -Ll' does. SEE ALSO ======== * `http://www.plover.com/~mjd/perl/lsMode/'. * `ls' in this node * `chmod' in this node * `stat' in this node AUTHOR ====== Mark-Jason Dominus (`mjd-perl-lsmode@plover.com').  File: pm.info, Node: Statistics/Candidates, Next: Statistics/Descriptive, Prev: Stat/lsMode, Up: Module List Perl5 module for manipulating candidate features (help module for `Statistics::MaxEntropy') ******************************************************************************************* NAME ==== Candidates - Perl5 module for manipulating candidate features (help module for `Statistics::MaxEntropy') SYNOPSIS ======== use Statistics::Candidates; # create a new candidates object and read candidate features $candidates = Statistics::Candidates->new($some_file); # checks for constant candidate features $candidates->check(); # writes candidates that were not added to a file $candidates->write($some_other_file); # clear the administration about being added or not ... $candidates->clear(); DESCRIPTION =========== The `Candidates' object is for storage, retrieval, and manipulation of candidate features. The reason for separating this code from `Maxentropy.pm' is that a set of candidate features should be considered a separate object. Blessing them into `MaxEntropy' would be unnatural. Also this code is simpler and more stable than that in the `MaxEntropy' module. This module requires `Bit::SparseVector'. METHODS ======= new $candidates = Statistics::Candidates->new($file); check $candidates->check(); write $candidates->write($file); clear $candidates->clear(); FILE SYNTAX =========== The syntax of the candidate feature file is more or less the same as that for the events file: * each line is an event (events specified in the same order as the events file); * each column is a feature; * constant feature functions are forbidden; * values are 0 or 1; * no space between features; * lines that start with `#' are ignored. Below is a set of candidates for m events, c candidate features; `f_ij' are bits: name_c name_c-1 ... name_2 name_1 f_1c ... f_13 f_12 f_11 . . . f_ic ... f_i3 f_i2 f_i1 . . . f_mc ... f_m3 f_m2 f_m1 SEE ALSO ======== *Note Statistics/MaxEntropy: Statistics/MaxEntropy,, *Note Statistics/SparseVector: Statistics/SparseVector,.. VERSION ======= Version 0.1 AUTHOR ====== Hugo WL ter Doest, terdoest@cs.utwente.nl Hugo WL ter Doest, \texttt{terdoest\symbol{'100}cs.utwente.nl} COPYRIGHT ========= Copyright (C) 1998 Hugo WL ter Doest, terdoest@cs.utwente.nl Univ. of Twente, Dept. of Comp. Sc., Parlevink Research, Enschede, The Netherlands. Copyright (C) 1998 Hugo WL ter Doest, \texttt{terdoest\symbol{'100}cs.utwente.nl} Univ. of Twente, Dept. of Comp. Sc., Parlevink Research, Enschede, The Netherlands. `Statistics::Candidates' comes with ABSOLUTELY NO WARRANTY and may be copied only under the terms of the GNU Library General Public License (version 2, or later), which may be found in the distribution.  File: pm.info, Node: Statistics/Descriptive, Next: Statistics/Distributions, Prev: Statistics/Candidates, Up: Module List Module of basic descriptive statistical functions. ************************************************** NAME ==== Statistics::Descriptive - Module of basic descriptive statistical functions. SYNOPSIS ======== use Statistics::Descriptive; $stat = Statistics::Descriptive::Full->new(); $stat->add_data(1,2,3,4); $mean = $stat->mean(); $var = $stat->variance(); $tm = $stat->trimmed_mean(.25); $Statistics::Descriptive::Tolerance = 1e-10; DESCRIPTION =========== This module provides basic functions used in descriptive statistics. It has an object oriented design and supports two different types of data storage and calculation objects: sparse and full. With the sparse method, none of the data is stored and only a few statistical measures are available. Using the full method, the entire data set is retained and additional functions are available. Whenever a division by zero may occur, the denominator is checked to be greater than the value `$Statistics::Descriptive::Tolerance', which defaults to 0.0. You may want to change this value to some small positive value such as 1e-24 in order to obtain error messages in case of very small denominators. METHODS ======= Sparse Methods -------------- $stat = Statistics::Descriptive::Sparse->new(); Create a new sparse statistics object. $stat->add_data(1,2,3); Adds data to the statistics variable. The cached statistical values are updated automatically. $stat->count(); Returns the number of data items. $stat->mean(); Returns the mean of the data. $stat->sum(); Returns the sum of the data. $stat->variance(); Returns the variance of the data. Division by n-1 is used. $stat->standard_deviation(); Returns the standard deviation of the data. Division by n-1 is used. $stat->min(); Returns the minimum value of the data set. $stat->mindex(); Returns the index of the minimum value of the data set. $stat->max(); Returns the maximum value of the data set. $stat->maxdex(); Returns the index of the maximum value of the data set. $stat->sample_range(); Returns the sample range (max - min) of the data set. Full Methods ------------ $stat = Statistics::Descriptive::Full->new(); Create a new statistics object that inherits from Statistics::Descriptive::Sparse so that it contains all the methods described above. $stat->add_data(1,2,4,5); Adds data to the statistics variable. All of the sparse statistical values are updated and cached. Cached values from Full methods are deleted since they are no longer valid. *Note: Calling add_data with an empty array will delete all of your Full method cached values!* $stat->get_data(); Returns a copy of the data array. $stat->sort_data(); Sort the stored data and update the mindex and maxdex methods. This method uses perl's internal sort. $stat->presorted(1); $stat->presorted(); If called with a non-zero argument, this method sets a flag that says the data is already sorted and need not be sorted again. Since some of the methods in this class require sorted data, this saves some time. If you supply sorted data to the object, call this method to prevent the data from being sorted again. The flag is cleared whenever add_data is called. Calling the method without an argument returns the value of the flag. $x = $stat->percentile(25); ($x, $index) = $stat->percentile(25); Sorts the data and returns the value that corresponds to the percentile as defined in RFC2330: For example, given the 6 measurements: -2, 7, 7, 4, 18, -5 Then F(-8) = 0, F(-5) = 1/6, F(-5.0001) = 0, F(-4.999) = 1/6, F(7) = 5/6, F(18) = 1, F(239) = 1. Note that we can recover the different measured values and how many times each occurred from F(x) -- no information regarding the range in values is lost. Summarizing measurements using histograms, on the other hand, in general loses information about the different values observed, so the EDF is preferred. Using either the EDF or a histogram, however, we do lose information regarding the order in which the values were observed. Whether this loss is potentially significant will depend on the metric being measured. We will use the term "percentile" to refer to the smallest value of x for which F(x) >= a given percentage. So the 50th percentile of the example above is 4, since F(4) = 3/6 = 50%; the 25th percentile is -2, since F(-5) = 1/6 < 25%, and F(-2) = 2/6 >= 25%; the 100th percentile is 18; and the 0th percentile is -infinity, as is the 15th percentile. Care must be taken when using percentiles to summarize a sample, because they can lend an unwarranted appearance of more precision than is really available. Any such summary must include the sample size N, because any percentile difference finer than 1/N is below the resolution of the sample. taken from: RFC2330 - Framework for IP Performance Metrics, Section 11.3. Defining Statistical Distributions rfc2330 is available from: http://www.cis.ohio-state.edu/htbin/rfc/rfc2330.html If the percentile method is called in a list context then it will also return the index of the percentile. $stat->median(); Sorts the data and returns the median value of the data. $stat->harmonic_mean(); Returns the harmonic mean of the data. Since the mean is undefined if any of the data are zero or if the sum of the reciprocals is zero, it will return undef for both of those cases. $stat->geometric_mean(); Returns the geometric mean of the data. $stat->mode(); Returns the mode of the data. $stat->trimmed_mean(ltrim[,utrim]); `trimmed_mean(ltrim)' returns the mean with a fraction `ltrim' of entries at each end dropped. `trimmed_mean(ltrim,utrim)' returns the mean after a fraction `ltrim' has been removed from the lower end of the data and a fraction `utrim' has been removed from the upper end of the data. This method sorts the data before beginning to analyze it. $stat->frequency_distribution(); `frequency_distribution(partitions)' slices the data into `partition' sets (where partition is greater than 1) and counts the number of items that fall into each partition. It returns an associative array where the keys are the numerical values of the partitions used. The minimum value of the data set is not a key and the maximum value of the data set is always a key. The number of entries for a particular partition key are the number of items which are greater than the previous partition key and less then or equal to the current partition key. As an example, $stat->add_data(1,1.5,2,2.5,3,3.5,4); %f = $stat->frequency_distribution(2); for (sort {$a <=> $b} keys %f) { print "key = $_, count = $f{$_}\n"; } prints key = 2.5, count = 4 key = 4, count = 3 since there are four items less than or equal to 2.5, and 3 items greater than 2.5 and less than 4. $stat->least_squares_fit(); $stat->least_squares_fit(@x); `least_squares_fit()' performs a least squares fit on the data, assuming a domain of `@x' or a default of 1..$stat->count(); It returns an array of four elements `($q, $m, $r, $rms)' where `$q and $m' satisfy the equation C($y = $m*$x + $q). $r is the Pearson linear correlation cofficient. `$rms' is the root-mean-square error. If case of error or division by zero, the empty list is returned. The array that is returned can be "coerced" into a hash structure by doing the following: my %hash = (); @hash{'q', 'm', 'r', 'err'} = $stat->least_squares_fit(); REPORTING ERRORS ================ I read 4 of the 5 perl newsgroups comp.lang.perl.{misc,moderated,modules,announce} and check my email at work frequently, so please feel free to post errors to either or both of those places. However, realize that if you post to the newsgroup it has the benefit of alerting other users of the problem. When reporting errors, please include the following to help me out: * Your version of perl. This can be obtained by typing perl -v at the command line. * Which version of Statistics::Descriptive you're using. As you can see below, I do make mistakes. Unfortunately for me, right now there are thousands of CD's with the version of this module with the bugs in it. Fortunately for you, I'm a very patient module maintainer. * Details about what the error is. Try to narrow down the scope of the problem and send me code that I can run to verify and track it down. My email address can be found at www.perl.com under Who's Who. REFERENCES ========== RFC2330, Framework for IP Performance Metrics The Art of Computer Programming, Volume 2, Donald Knuth. Handbook of Mathematica Functions, Milton Abramowitz and Irene Stegun. Probability and Statistics for Engineering and the Sciences, Jay Devore. COPYRIGHT ========= Copyright (c) 1997,1998 Colin Kuskie. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Copyright (c) 1998 Andrea Spinelli. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Copyright (c) 1994,1995 Jason Kastner. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. REVISION HISTORY ================ v2.3 Rolled into November 1998 Code provided by Andrea Spinelli to prevent division by zero and to make consistent return values for undefined behavior. Andrea also provided a test bench for the module. A bug fix for the calculation of frequency distributions. Thanks to Nick Tolli for alerting this to me. Added 4 lines of code to Makefile.PL to make it easier for the ActiveState installation tool to use. Changes work fine in perl5.004_04, haven't tested them under perl5.005xx yet. v2.2 Rolled into March 1998. Fixed problem with sending 0's and -1's as data. The old 0 : true ? false thing. Use defined to fix. Provided a fix for AUTOLOAD/DESTROY/Carp bug. Very strange. v2.1 August 1997 Fixed errors in statistics algorithms caused by changing the interface. v2.0 August 1997 Fixed errors in removing cached values (they weren't being removed!) and added sort_data and presorted methods. June 1997 Transferred ownership of the module from Jason to Colin. Rewrote OO interface, modified function distribution, added mindex, maxdex. v1.1 April 1995 Added LeastSquaresFit and FrequencyDistribution. v1.0 March 1995 Released to comp.lang.perl and placed on archive sites. v.20 December 1994 Complete rewrite after extensive and invaluable e-mail correspondence with Anno Siegel. v.10 December 1994 Initital concept, released to perl5-porters list.