This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Games/Chess/Referee, Next: Games/Dissociate, Prev: Games/Chess/PGN, Up: Module List work with chess positions and games, according to the rules of chess. ********************************************************************* NAME ==== Games::Chess::Referee - work with chess positions and games, according to the rules of chess. SYNOPSIS ======== use Games::Chess:Referee; new_game(); ply('e2e4'); ply('e7e5'); show_board(); move('d2d3', 'd7d6'); show_board(); DESCRIPTION =========== The `Games::Chess:Referee' module provides a mechanism to interpret (almost) standard algebraic chess notation and to print out the resulting positions. It makes use of the Games::Chess::Position and Games::Chess::Piece classes by Gareth Rees, adding the chess rules and move application functionality. ERROR HANDLING ============== Where the code does complain, it uses the carp routine. The ply() and move() routines return zero on failure, one on success. LIMITATIONS =========== In this very early version, many of the rules of chess are not yet implemented. The code is in a state of flux right now, as it is being reworked into a class from a simple afternoon proof of concept. See the README file and comments in the code for more information. BUGS ==== There are no known bugs as of this writing, but it would be reasonable to consider the limitations as bugs. SEE ALSO ======== *Note Games/Chess: Games/Chess, AUTHOR ====== Gregor N. Purdy (`gregor@focusresearch.com') COPYRIGHT AND LICENSE ===================== Copyright (C) 1999 Gregor N. Purdy. 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: Games/Dissociate, Next: Games/Maze, Prev: Games/Chess/Referee, Up: Module List a Dissociated Press algorithm and filter **************************************** NAME ==== Games::Dissociate - a Dissociated Press algorithm and filter SYNOPSIS ======== use Games::Dissociate; ... $brilliant_prose = dissociate($normal_prose); or perl -MGames::Dissociate -e dissociate_filter meno.txt ABSTRACT ======== This module provides the function `dissociate', which implements a Dissociated Press algorithm, well known to Emacs users as "meta-x dissociate". The algorithm here is by no means a straight port of Emacs's `dissociate.el', but is instead merely inspired by it. (I actually intended to make it a straight port, but couldn't manage it - the code in `dissociate.el' is totally uncommented, and is *especially* obscure Lisp.) This module also provides a procedure `dissociate_filter', for use in the one-liner context: perl -MGames::Dissociate -e 'dissociate_filter(2)' < thesis.txt > snip.txt or perl -MGames::Dissociate -e 'dissociate_filter(-2)' < thesis.txt > snip.txt or in a script consisting of #!/usr/local/bin/perl use Games::Dissociate; dissociate_filter; Sample Dissociation ------------------- I got this text from feeding the UNIX man page for "regexp" (in plaintext) to `dissociate' with a $group_size parameter of 3: nd of then the full list of the more branch is zero or "*", "." (matching thand regexp(n) right initional argumented by a pieces of the left to match that (ab|a) general other worDS match to the first, followed by "?". It matcheS In of the next start was been could exp. The characters in expreSSIons belowed in the full matching the in starticular EXpression in "[0-9]" include a list of sequence of the are may before the regexp even therwise. REgexp(n) Tcl regular expression to regexp(n) regexp(n) right. Input string), "\", About Dissociated Press algorithms ---------------------------------- "Dissociated Press" algorithms produce text with token-patterns (patterns of words, or patterns of characters) similar those found to an input text. This may be implemented in terms of Markov chains (basically, statistical modeling of frequency of token-groups), altho both this module and Emacs's `dissociate.el' take shortcuts to avoid having to construct and manipulate a real statistical model of the input text. Basically, the way Dissociated Press algorithms (at least mine - I can't speak for the exact details of all others) work is: 1. Start at a random point in the text, and read a group of tokens (characters or words from there - where group size is a parameter you change) from there. Call this the last-matched group. 2. Output the last-matched group. 3. Look for the other times the last-matched group occurs in the text, and randomly select one of them. (Or: select the next time that group occurs - a shortcut I've made in the code, which seems to still produce random-looking results). Look at the group of tokens that occurs right after that. Make *that* the last-matched group. Loop back to Step 2 until we think we've outputted enough. 4. But if the last-matched group from 2 occurred just that once in the text, go back to step 1. Since the groups of characters or words (at least, when you look at them as bits of text only group-size tokens long) are all taken from the input text, you get somewhat natural-looking text - as opposed to what you'd get if you just randomly outputted single characters or single words from the input text. The process of applying a DissociatedPress algorithm to a bit of text is called "dissociation". PARAMETERS AND USAGE ==================== To use this module after you've installed it, say "use Games::Dissociate". This imports the function `dissociate' and the procedure `dissociate_filter'. The function `dissociate' takes three parameters: $output = dissociate($input, $group_size, $max); $input is the input string, hopefully containing a stretch of (plaintext) text in a human language, encoded either in just plain US-ASCII, or in a character-encoding your locale settings know about. $output will be "dissociated text" (charmingly generated gibberish) based on that input text. (Note that output will contain no line-breaks or tabs. Yoy may wish, as `dissociate_filter' does, to pass the output thru Text::Wrap's wrap.) You'll get strange output if $input contains markup (HTML, LaTeX, etc.), or is very short, or is not in a human language. $group_size is the number of tokens (words or characters) that must be in common between bits of text the dissociation algorithm skips between. A positive value means you want to dissociate by character, with a group-size of that many characters (4 = 4 characters); a negative value means you want to dissociate by word, with a group size of that many words (-2 = 2 words). I suggest values between -3 and 5; I'm a fan of -2. A $group_size value of 0 or 1 is invalid, and currently causes `dissociate' to use the default value of 2 (2 characters) instead. A value of -1 is invalid, and currently causes `dissociate' to use the value of -2 (2 words) instead. The behavior/validity of $group_size values of 0, 1, or -1 may change in future versions. $max is a parameter used to control the maximum number of iterations of `dissociate''s central loop - it corresponds roughly to the number of "chunks" of text you get back, where a chunk is N * -$group_size words for negative values of $group_size, and N * $group_size characters for positive values of $group_size. $max must be greater than 1. If you need (!) more precise control over the size of the output text, try setting set $max high and trim the output to size, and/or try calling `dissociate' multiple times until you get the amount of output you want. (But be sure to give up if `dissociate' keeps returning nullstring, as it will in some strange cases.) `dissociate' can also be called with the following syntaxes: dissociate($input, $group_size); # acts like max of 100 dissociate($input); # acts like group size of 2 (characters) and max of 100 This library also provides the procedure `dissociate_filter', which pulls input from "<>" (files specified on the command line, or STDIN), and sends dissociated output to STDOUT. It can be called with these syntaxes: dissociate_filter($group_size, $max); dissociate_filter($group_size); # uses a default value for $max dissociate_filter(); # uses a default value for $group_size and $max These above-mentioned default values can come from command line switches, if you make a script consisting of: #!/usr/local/bin/perl use Games::Dissociate; dissociate_filter; and call that script, say, `dissociate', and call it as: dissociate -c5 -m200 < foo.txt or dissociate -w2 -m70 foo.txt bar.txt | less and so on. To explain the switches: `-w[number]' specifies a by-word dissociation with that number of words as the group size, `-c[number]' specifies a by-character dissociation with that number of characters as the group size, `-m[number]' specifies a default for $max. If you don't specify a default for $group_size or $max, $group_size defaults to 100 and $max defaults to 2 (characters). Efficiency Notes ---------------- This module has to search the input string by performing regexp searches on it. In the current version of this module, control over compilation of regular expressions may not be not optimally efficient. Perl 5.005 provides options to better control regexp compilation; once Perl 5.005 is in wider use, I may come out with a new version of Games::Dissociate requiring Perl 5.005 or later, using these new regexp compilation control features. If you feed this module a lot of text (over 50K, say), it will indeed get very slow (notably with by-word dissociation), since that whole chunk of text has to be searched over and over and over. If you have an idea for making this module more efficient, feel free to email it to me. Internationalization Notes -------------------------- When dealing with text in heavily inflected languages (like Finnish - lots of unique word endings, frequently used), this module will require longer input text to produce interesting results for by-word dissociation, compared to relatively inflection-poor languages like English. For text written with no inter-word spacing (often the case with Thai, for example), there's no way for this module to tell where the word breaks are - in such cases, use only the by-character mode. The current version of this library assumes "/./" matches a single character, for by-character dissociation; and, for by-word dissociation, that "/\w+/" matches whole words and /\W+/ matches non-word strings. These are locale-dependent functions, and Games::Dissociate has a "use locale" in it, hopefully triggering correct behavior for your favorite locale, language, and character-encoding. Consult *Note Perllocale: (perl.info)perllocale, and *Note Locale: locale, for more information on locales. I *have* found "use locale" to do unwelcome things (like unceremoniously dumping core) on a few very strange, very old (and otherwise barely-working) machines. If this is a problem for you, or if you don't plan to use locales, comment out the "use locale" in the Games::Dissociate source code. The treatment of locales and support for them may change in future versions of this module, depending on how future Perl versions shape up, particularly in their support of Unicode. Randomness Notes ---------------- This library uses rand extensively, but never calls srand. If you're getting the same dissociated output all the time, then you're using an old (pre-5.004) version of Perl that doesn't do implicit randomness seeding - just call "srand();", maybe right after you say "use Games::Dissociate"; SEE ALSO ======== * Emacs's `dissociate.el' (written circa 1985?). COPYRIGHT ========= Copyright (c) 1998-2001, Sean M. Burke. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. REMINDER ======== It's just a toy. AUTHOR ====== Sean M. Burke  File: pm.info, Node: Games/Maze, Next: Games/Maze/MazeD2, Prev: Games/Dissociate, Up: Module List Create Mazes as Objects. ************************ NAME ==== Games::Maze - Create Mazes as Objects. SYNOPSIS ======== use Games::Maze::MazeD2; use Games::Maze::MazeXD2; use Games::Maze::MazeD3; use Games::Maze::MazeXD3; my($minos) = MazeD2->new($columns, $rows); my($theseus) = MazeXD2->new($columns, $rows); my($minotaur) = MazeD3->new($columns, $rows, $levels); my($posiedon) = MazeXD3->new($columns, $rows, $levels); $minos->reset(); # Actually, automatically called. $minos->make(); $minos->solve(); $minos->to_ascii(); $minos->to_hex_dump(); PREREQUISITES ============= Perl 5.003_20 or later. This is the version that is required for the "use constant" pragma, and constants are used throughout the code. INSTALLATION ============ perl Makefile.PL make make test make install Note: You may get a warning when running 'make test'. This may occur because you have compiled your perl with a value of RANDBITS that is unknown to the test case. The test files will be written in /tmp. Please send them and your RANDBITS value to *jgamble@ripco.com* so that they can be incorporated into the next release. DESCRIPTION =========== Simply put, these packages create mazes. Your choices are the simple 2-dimensional rectangular maze, the 2-dimensional hexagonal maze, the 3-dimensional rectangular maze, and the 3-dimensional hexagonal maze. The mazes are objects that you can manipulate using the available methods. From a purely functional standpoint, the 2-dimensional packages are unneeded, as a 3-dimensional maze that is one level deep does mimic a 2-dimensional maze, but the internal functionality of the 2-dimensional maze is slightly different and somewhat more efficient, and so is retained. Maze Object Methods ------------------- new([columns [, rows [, levels] ]) Creates the object with it's attributes. Columns and rows will default to 3 if you don't pass parameters to the method. For 3-dimensional mazes, *levels* defaults to 2. reset Resets the matrix m. You should not normally need to call this method, as the other methods will call it when needed. make Perform a random walk through the walls of the grid. This creates a simply-connected maze. solve Finds a solution to the maze by examining a path until a dead end is reached. to_hex_dump Returns a formatted string all of the cell values, including the border cells, in hexadecimal. to_ascii Translate the maze into a string of ascii 7-bit characters. If called in an array context, return as a list of levels. Otherwise returned as a single string, each level separated by a single newline. The maze created by MazeD2 and MazeXD2 is always a single string. Currently, this is the only method available to view the maze. It uses underscores, both slash characters, and vertical bars to represent the walls of the maze. The asterisk represents the path, and the letters 'c', 'f', and 'b' represent entries through the ceiling, floor, or both, respectively. EXAMPLES ======== use Games::Maze::MazeD3; my($minos) = MazeD3->new(8, 6, 3); $minos->make(); $, = "\n\n"; print $minos->to_ascii(); print "\nThe Solution...\n"; $minos->solve(); print $minos->to_ascii(); exit(0); AUTHOR ====== John M. Gamble may be found at *jgamble@ripco.com*  File: pm.info, Node: Games/Maze/MazeD2, Next: Games/Maze/MazeD3, Prev: Games/Maze, Up: Module List Create maze objects. ******************** NAME ==== Games::MazeD2 - Create maze objects. Maze creation is done through the maze object's methods, listed below: new([columns, [rows]]) Creates the object with it's attributes. Columns and rows will default to 3 if you don't pass parameters to the method. describe Returns information about the maze object. reset Resets the matrix m. You should not normally need to call this method, as the other methods will call it when needed. make Perform a random walk through the walls of the grid. This creates a simply-connected maze. solve Finds a solution to the maze by examining a path until a dead end is reached. to_hex_dump Returns a formatted string all of the cell values, including the border cells, in hexadecimal. to_ascii Translate the maze into a string of ascii 7-bit characters. If called in an array context, return as a list of levels. Otherwise returned as a single string, each level separated by a single newline.  File: pm.info, Node: Games/Maze/MazeD3, Next: Games/Maze/MazeXD2, Prev: Games/Maze/MazeD2, Up: Module List Create 3-D maze objects. ************************ NAME ==== Games::MazeD3 - Create 3-D maze objects. Maze creation is done through the maze object's methods, listed below: new([columns, [rows, [levels]]]) Creates the object with it's attributes. Columns, rows, and levels will default to 3, 3, and 2 if you don't pass parameters to the method. describe Returns information about the maze object. reset Resets the matrix m. You should not normally need to call this method, as the other methods will call it when needed. make Perform a random walk through the walls of the grid. This creates a simply-connected maze. solve Finds a solution to the maze by examining a path until a dead end is reached. to_hex_dump Returns a formatted string all of the cell values, including the border cells, in hexadecimal. to_ascii Translate the maze into a string of ascii 7-bit characters. If called in an array context, return as a list of levels. Otherwise returned as a single string, each level separated by a single newline.  File: pm.info, Node: Games/Maze/MazeXD2, Next: Games/Maze/MazeXD3, Prev: Games/Maze/MazeD3, Up: Module List Create hexagon maze objects. **************************** NAME ==== Games::MazeXD2 - Create hexagon maze objects. Maze creation is done through the maze object's methods, listed below: new([columns, [rows]]) Creates the object with it's attributes. Columns and rows will default to 3 if you don't pass parameters to the method. describe Returns information about the maze object. reset Resets the matrix m. You should not normally need to call this method, as the other methods will call it when needed. make Perform a random walk through the walls of the grid. This creates a simply-connected maze. solve Finds a solution to the maze by examining a path until a dead end is reached. to_hex_dump Returns a formatted string all of the cell values, including the border cells, in hexadecimal. to_ascii Translate the maze into a string of ascii 7-bit characters. If called in an array context, return as a list of levels. Otherwise returned as a single string, each level separated by a single newline.  File: pm.info, Node: Games/Maze/MazeXD3, Next: Games/WordFind, Prev: Games/Maze/MazeXD2, Up: Module List Create 3-D hexagon maze objects. ******************************** NAME ==== Games::MazeXD3 - Create 3-D hexagon maze objects. Maze creation is done through the maze object's methods, listed below: new([columns, [rows, [levels]]]) Creates the object with it's attributes. Columns, rows, and levels will default to 3, 3, and 2 if you don't pass parameters to the method. describe Returns information about the maze object. reset Resets the matrix m. You should not normally need to call this method, as the other methods will call it when needed. make Perform a random walk through the walls of the grid. This creates a simply-connected maze. solve Finds a solution to the maze by examining a path until a dead end is reached. to_hex_dump Returns a formatted string all of the cell values, including the border cells, in hexadecimal. to_ascii Translate the maze into a string of ascii 7-bit characters. If called in an array context, return as a list of levels. Otherwise returned as a single string, each level separated by a single newline.  File: pm.info, Node: Games/WordFind, Next: Games/WordGuess, Prev: Games/Maze/MazeXD3, Up: Module List Class for generating Word Find type puzzles ******************************************* NAME ==== WordFind - Class for generating Word Find type puzzles SYNOPSIS ======== use Games::WordFind; $puz=Games::WordFind->new({cols=>10}); @words=qw(perl camel llama linux great); $puz->create_puzzle(@words); print $puz->get_plain(); or, print $puz->get_latex(); DESCRIPTION =========== This module simply provides a class which can be used to generate WordFind type puzzles. It is simple to use, the relevant methods are: $puzzle = Games::WordFind->new({cols => 10,intersect=>1}); Obviously, this returns a WordFind object. By default the puzzle created by this object is a 10x10 lattice--you may give an optional hash reference with a 'cols' as the key and some number as the value for the size of the lattice. You may also provide an 'intersect' key, which allows words to intersect in the puzzle (share letters) when set to a non-zero value. $puzzle->create_puzzle(LIST) This method takes the LIST of words and creates the puzzle. Any words which are longer than the number of columns in the puzzle are dropped from the wordlist and a warning is issued. This method will return references to three arrays; a two dimensional array of the puzzle, an array of the words used, and a two dimensional array of the puzzle solution. These are so you can format your puzzle output yourself rather than using the latex or html formatting functions described next. $puzzle->get_plain({solution => 1}) This method gets the puzzle and its solution matrix in a plain text format. If you supply the optional hash reference with a non-zero value for 'solution', a solution matrix is included immediately following the puzzle. $puzzle->get_latex({solution => 1, wrapper => 1}) This method a latex formatted version of the puzzle containing tabular environments to set the puzzle and solution (a newpage separates the two). The optional hash argument can contain the key 'wrapper' which tells the method to return the puzzle wrapped with a latex preamble, and the key 'solution' which will return the solution matrix after a `\newpage' command in the latex source. $puzzle->get_html({solution =>1, wrapper =>1}) Similar to the latex method, though, of course, there is no newpage separation of the solution. AUTHOR ====== Andrew L Johnson Copyright ========= WordFind.pm and wordfind.pl are copyright (c) 1997,1998 Andrew L Johnson. This is free software and you may redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1).  File: pm.info, Node: Games/WordGuess, Next: Games/Worms, Prev: Games/WordFind, Up: Module List a class for creating word-guessing game *************************************** NAME ==== Games::WordGuess - a class for creating word-guessing game SYNOPSIS ======== use Games::WordGuess; $game = new Games::WordGuess; $game = new Games::WordGuess("/usr/games/lib/fortunes/startrek"); DESCRIPTION =========== Games::WordGuess is a module for word-guessing game. Scoring is calculated from the number of chances left for each mystery word. Constructor ----------- Specify the full path to the file containing words to be played at the new() method, for example: $game = new Games::WordGuess("/usr/games/lib/fortunes/startrek"); otherwise, `Games::WordGuess' uses some internal Indonesian words as the default. Simple command line user interface ---------------------------------- Look at examples/cmdln script on example of using command_interface(). process_guess() --------------- This is the core method. Passed a character, `process_guess' will return undef if there's no matched character in the current mystery word. If it is passed a previous matched character, it returns undef as well. On success, it returns 0, or 1 if the mystery word has already revealed. in_progress() ------------- Returns the mystery word in current player's progress. Initially, after a `Game::WordGuess' object is created, this will return the mystery word covered with asterisks. On each matched guess, the corresponding asterisk will be substituted by the real character. get_chances() ------------- Returns the remaining chances left for current player. get_score() ----------- Returns total score for current player. init_mystery() -------------- Provides a new mystery word to current player. Call to this method is required to continue the game after successful guess of one complete word. HISTORY ======= * August 16, 1999 - Version 0.20: process_guess() now returns undef on missed guess. Added in_progress() method. Added documentation, and a CGI script example using Apache::Session. * July 1999 - Version 0.11: Changes to command_interface(), as suggested by Steven Haryanto . * April 1999 - Publicly released, Version 0.10 AUTHOR ====== Edwin Pratomo <*ed.pratomo@computer.org*> COPYRIGHT ========= Copyright (c) 1999 Edwin Pratomo . All rights reserved. This is a free code; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Games/Worms, Next: Games/Worms/Base, Prev: Games/WordGuess, Up: Module List alife simulator for Conway/Patterson/Beeler worms, etc. ******************************************************* NAME ==== Games::Worms - alife simulator for Conway/Patterson/Beeler worms, etc. SYNOPSIS ======== perl -MGames::Worms -e worms -- -tPS perl -MGames::Worms -e worms -- -tPS / / / / > foo1.ps perl -MGames::Worms -e worms -- -tTk perl -MGames::Worms -e worms -- -tTek4010 / / / Games::Worms::Random2 BUGS, WARNINGS, AND CAVEATS =========================== This is an alpha release. The documentation is incomplete, and the interface is not yet finalized. Occasionally I've seen Perl 5.004_02 for MSWin segfault at global destruction time. The Tk part, I've only tested under pTk. This's my first hack at Tk, so lets hope all the code I wrote is portable. Suggestions welcome! I've tested the PostScript part only under GhostScript. I've tested the Tek interface under MSKermit. I hear xterm has a Tek emulator in it - I'd be interested to hear if it works well with Worms's Tek interface. DESCRIPTION =========== [elaborate] Worms is an implementation of an artificial-life game. It can output via Perl-Tk, Tek4010, and PostScript. It is a game not in the sense of checkers, but in the sense of Conway's Life. In a Worms universe, worms crawl around an isometric grid of triangles, leaving trails behind them, and turning in accordance to simple rules that are based upon which way they can move at a each junction. From the simple rules emerges surprising complexity. TO DO ===== Allow board-size specifications on the command line. Better docs. Maybe a GIF output mode? More interactive interface in pTk mode? Currently the interface is pretty much: specify things on the command line, then sit back and watch the worms go, until they all die. Hopefully I (or someone ambitious who knows Tk better than I do) may add more interactivity to the interface. INVOCATION ========== Start it up by making a Perl program called `worms', with the content: !/usr/bin/perl use Games::Worms; worms; Then start up with the -t switch specifying which interface to use: worms -tTk ...for Tk mode worms -tPS ...for PostScript mode worms -tTek4010 ...for Tektronics mode Command line arguments thereafter are interpreted as the names of classes worms should come from. (Currently, three are provided in this distribution: *Note Games/Worms/Random: Games/Worms/Random,, *Note Games/Worms/Random2: Games/Worms/Random2,, and *Note Games/Worms/Beeler: Games/Worms/Beeler,.) If no arguments are provided, Worms uses two Random2s and two Beelers. For each name you specify, if it contains a slash, the rest of that name is passed to the worm as an expression of its rules. Example specifications: Games::Worms::Beeler Games::Worms::Random Games::Worms::Random2 Games::Worms::Beeler/1a2d3caaa4b Games::Worms::Beeler/1A2B3ACAC4B Games::Worms::Beeler/1B2B3AAAB4A (A Beeler worm with no rules specified makes up a random rule set when it starts. A Random worm obeys no rules. A Random2 worm is random but consistent.) If you specify a name starting with '/', it's interpreted as short for 'Games::Worms::Beeler/'. In other words, /1a2d3caaa4b equals Games::Worms::Beeler/1a2d3caaa4b /1A2B3ACAC4B equals Games::Worms::Beeler/1A2B3ACAC4B /1B2B3AAAB4A equals Games::Worms::Beeler/1B2B3AAAB4A See the *Scientific American* article on Beeler worms for the meaning of these Beeler worm rule specifications. I don't have the citation for the first run of the article, but it's reproduced with nice addenda in the book cited below. If you don't want to bother making that little script called "worms", you can just as well invoke Worms via: perl -MGames::Worms -e worms -- -tTk perl -MGames::Worms -e worms -- -tPS perl -MGames::Worms -e worms -- -tTek4010 perl -MGames::Worms -e worms -- -tTek4010 Games::Worms::Random Games::Worms::Random2 /1a2d3caaa4b /1A2B3ACAC4B /1B2B3AAAB4A CONCEPTS ======== [to be written] REFERENCES ========== "Worm Paths", chapter 17 in: Martin Gardner, 1986, *Knotted Doughnuts and Other Mathematical Entertainments*, W. H. Freeman and Company. "Patterson's Worm", M. Beeler, MIT AI Memo #290. (early 1970s?) "Worms?" [sic], David Maynard, Electronic Arts, 1983. (A game for the Atari 400 (or 800?), the Commodore 64, and maybe other machines. Games::Worms isn't based on EOA "Worms?", but "Worms?" is the best known implementation of Beeler worms. It uses them as the basis for a very interesting and abstract interactive game.) GUTS ==== Read the source. It's OOPilicious! COPYRIGHT ========= Copyright 1999, Sean M. Burke `sburke@netadventure.net', all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHOR ====== Sean M. Burke `sburke@netadventure.net'  File: pm.info, Node: Games/Worms/Base, Next: Games/Worms/Beeler, Prev: Games/Worms, Up: Module List base class for worms ******************** NAME ==== Games::Worms::Base - base class for worms SYNOPSIS ======== package Spunky; use Games::Worms::Random; @ISA = ('Games::Worms::Random'); ...stuff... DESCRIPTION =========== This is the base class for all worms in Worms.  File: pm.info, Node: Games/Worms/Beeler, Next: Games/Worms/Random, Prev: Games/Worms/Base, Up: Module List class for Conway/Patterson/Beeler worms *************************************** NAME ==== Games::Worms::Beeler - class for Conway/Patterson/Beeler worms SYNOPSIS ======== perl -MGames::Worms -e worms -- -tTk Games::Worms::Beeler/1a2d3cbaa4b DESCRIPTION =========== This class implements Conway/Patterson/Beeler worms - "Beeler worms" for short. See the *Scientific American* reference in *Note Games/Worms: Games/Worms,. Note that my notation for rule-strings is directly taken from that article.  File: pm.info, Node: Games/Worms/Random, Next: Games/Worms/Random2, Prev: Games/Worms/Beeler, Up: Module List random worms ************ NAME ==== Games::Worms::Random - random worms SYNOPSIS ======== perl -MGames::Worms -e worms -- -tTk Games::Worms::Random DESCRIPTION =========== Worms in the class Games::Worms::Random are totally random - they move at random in whichever way they can, without regard to any rules or past movement.  File: pm.info, Node: Games/Worms/Random2, Next: GedNav, Prev: Games/Worms/Random, Up: Module List class for consistent random worms ********************************* NAME ==== Games::Worms::Random2 - class for consistent random worms SYNOPSIS ======== perl -MGames::Worms -e worms -- -tTk Games::Worms::Random2 DESCRIPTION =========== Worms in the class Games::Worms::Random2 are random, but consistent - that is, a worm in this class, upon meeting a new context, will choose at random which way to go, and then will associate that context with that move; and for the rest of its life, given that context, it will move in that direction. Games::Worms::Random2 is implemented by simply inheriting from Games::Worms::Random, but setting memoization to true. This simple change leads to worms that often behave rather like Beeler worms, but sometimes behave astonishingly differently.  File: pm.info, Node: GedNav, Next: Gedcom, Prev: Games/Worms/Random2, Up: Module List Perl extension for quick (& dirty) navigation of GEDCOM files ************************************************************* NAME ==== GedNav - Perl extension for quick (& dirty) navigation of GEDCOM files SYNOPSIS ======== use GedNav; blah blah blah DESCRIPTION =========== GedNav is a set of perl modules for navigating a GEDCOM file quickly. The intent was to make it fast enough for CGI purposes, on large GEDCOM files. I have not yet included the code for the report objects I've written (outline & register so far), except for the example code in outline.pl. I've also not included the Apache::GedNav stuff I've written. That'll probably come in a separate lump, when the time comes. AUTHOR ====== Rob Fugina, robf@geeks.com SEE ALSO ======== perl(1).  File: pm.info, Node: Gedcom, Next: Gedcom/CGI, Prev: GedNav, Up: Module List a module to manipulate Gedcom genealogy files ********************************************* NAME ==== Gedcom - a module to manipulate Gedcom genealogy files Version 1.09 - 12th February 2001 SYNOPSIS ======== use Gedcom; my $ged = Gedcom->new(gedcom_file => $gedcom_file); my $ged = Gedcom->new(grammar_version => 5.5, gedcom_file => $gedcom_file, read_only => 1, callback => $cb); my $ged = Gedcom->new(grammar_file => "gedcom-5.5.grammar", gedcom_file => $gedcom_file); return unless $ged->validate; my $xref = $self->resolve_xref($value); $ged->resolve_xrefs; $ged->unresolve_xrefs; $ged->normalise_dates; my %xrefs = $ged->renumber; $ged->order; $ged->write($new_gedcom_file, $flush); $ged->write_xml($fh, $level); my @individuals = $ged->individuals; my @families = $ged->families; my $me = $ged->get_individual("Paul Johnson"); my $xref = $ged->next_xref("I"); DESCRIPTION =========== Copyright 1998-2001, Paul Johnson (pjcj@cpan.org) This software is free. It is licensed under the same terms as Perl itself. The latest version of this software should be available from my homepage: http://www.pjcj.net This module provides for manipulation of Gedcom files. Gedcom is a format for storing genealogical information designed by The Church of Jesus Christ of Latter-Day Saints (http://www.lds.org). Information about Gedcom is available as a zip file at ftp://gedcom.org/pub/genealogy/gedcom/gedcom55.zip. Unfortunately, this is only usable if you can access a PC running Windows of some description. Part of the reason I wrote this module is because I don't do that. Well, I didn't. I can now although I prefer not to... Requirements: Perl 5.005 or later ActivePerl5 Build Number 520 or later has been reported to work Optional Modules: Date::Manip.pm to work with dates Text::Soundex.pm to use soundex Parse::RecDescent.pm to use lines2perl Roman.pm to use the LifeLines function roman from lines2perl The Gedcom format is specified in a grammar file (gedcom-5.5.grammar). Gedcom.pm parses the grammar which is then used to validate and allow manipulation of the Gedcom file. I have only used Gedcom.pm with version 5.5 of the Gedcom grammar, which I had to modify slightly to correct a few errors. The advantage of this approach is that Gedcom.pm should be useful if the Gedcom grammar is ever updated. It also made the software easier to write, and probably more dependable too. I suppose this is the virtue of laziness shining through. The vice of laziness is also shining brightly - I need to document how to use this module in much greater detail. This is happening - this release has more documentation than the previous ones - but if you would like information feel free to send me mail. This module provides some functions which work over the entire Gedcom file, such as reformatting dates, renumbering entries and ordering the entries. It also allows access to individuals, and then to relations of individuals, for example sons, siblings, spouse, parents and so forth. This release includes a lines2perl program to convert LifeLines programs to Perl. The program works, but it has a few rough edges, and some missing functionality. I'll be working on it when it hits the top of my TODO list. This release provides an option for read only access to the gedcom file. Actually, this doesn't stop you changing or writing the file, but it does parse the gedcom file lazily, meaning that only those portions of the gedcom file which are needed will be read. This can provide a substantial saving of time and memory providing that not too much of the gedcom file is read. If you are going to read the whole gedcom file, this mode is less efficient. Note that this is an early release of this software - caveat emptor. Should you find this software useful, or if you make changes to it, or if you would like me to make changes to it, please send me mail. I would like to have some sort of an idea of the use this software is getting. Apart from being of interest to me, this will guide my decisions when I feel the need to make changes to the interface. There is a low volume mailing list available for discussing the use of Perl in conjunction with genealogical work. This is an appropriate forum for discussing Gedcom.pm. To subscribe to the regular list, send a message to majordomo@icomm.ca and put subscribe perl-gedcom as the body of the message. To get on the digest version of the list, put subscribe perl-gedcom-digest. To store my genealogy I wrote a syntax file (gedcom.vim) and used vim (http://www.vim.org) to enter the data, and Gedcom.pm to validate and manipulate it. I find this to be a nice solution. GETTING STARTED =============== This space is reserved for something of a tutorial. If you learn best by looking at examples, take a look at the test directory, t. The most simple test is *birthdates.t*. The first thing to do is to read in the Gedcom file. At its most simple, this will involve a statement such as my $ged = Gedcom->new(gedcom_file => $gedcom_file); It is now possible to access the records within the gedcom file. Each individual and family is a record. Records can contain other records. For example, an individual is a record. The birth information is a sub-record of the individual, and the date of birth is a sub-record of the birth record. Some records, such as the birth record, are simply containers for other records. Some records have a value, such as the date record, whose value is a date. This is all defined in the Gedcom standard. To access an individual use a statement such as my $i = $ged->get_individual("Paul Johnson"); To access information about the individual, use a function of the same name as the Gedcom tag, or its description. Tags and descriptions are listed at the head of Gedcom.pm. For example for my $b ($i->birth) { } will loop through all the birth records in the individual. Usually there will only be one such record, but there may be zero, one or more. Calling the function in scalar context will return only the first record. my $b = $i->birth; But the second record may be returned with my $b = $i->birth(2); If the record required has a value, for example my $n = $i->name; then the value is returned, in this case the name of the individual. If there is no value, as is the case for the birth record, then the record itself is returned. If there is a value, but the record itself is required, then the get_record() function can be used. Information must be accesed through the Gedcom structure so, for example, the birthdate is accessed via the date record from the birth record within an individual. my $d = $b->date; Be aware that if you access a record in scalar context, but there is no such record, then undef is returned. In this case, $b would be undef if $i had no birth record. This is another reason why looping through records is a nice solution, all else being equal. Access to values can also be gained through the get_value() function. This is a preferable solution where it is necessary to work down the Gedcom structure. For example my $bd = $i->get_value("birth date"); my $bd = $i->get_value(qw(birth date)); will both return an individual's birth date or undef if there is none. And my @bd = $i->get_value("birth date"); will return all the birth dates. The second birth date, if there is one, is my $bd2 = $i->get_value(["birth", 2], "date"); Using the get_record() function in place of the get_value() function, in all cases will return the record rather than the value. All records are of a type derived from Gedcom::Item. Individuals are of type Gedcom::Individual. Families are of type Gedcom::Family. Events are of type Gedcom::Event. Other records are of type Gedcom::Record which is the base type of Gedcom::Individual, Gedcom::Family and Gedcom::Event. As individuals are of type Gedcom::Individual, the functions in Gedcom::Individual.pm are available. These allow access to relations and other information specific to individuals, for example my @sons = $i->sons; It is possible to get all the individuals in the gedcom file as my @individuals = $ged->individuals; HASH MEMBERS ============ I have not gone the whole hog with data encapsulation and such within this module. Maybe I should have done. Maybe I will. For now though, the data is accessable though hash members. This is partly because having functions to do this is a little slow, especially on my old DECstation, and partly because of laziness again. I'm not too sure whether this is good or bad laziness yet. Time will tell no doubt. As of version 1.05, you should be able to access all the data through functions. Well, read access anyway. The TODO list mentions something about improving the situation as far as write access is concerned. Some of the more important hash members are: $ged->{grammar} --------------- This contains the gedcom grammar. See Gedcom::Grammar.pm for more details. $ged->{record} -------------- This contains the top level gedcom record. A record contains a number of items. Each of those items are themselves records. This is the way in which the hierarchies are modelled. If you want to get at the data in the gedcom object, this is where you start. See Gedcom::Record.pm for more details. METHODS ======= new --- my $ged = Gedcom->new(gedcom_file => $gedcom_file); my $ged = Gedcom->new(grammar_version => 5.5, gedcom_file => $gedcom_file, read_only => 1, callback => $cb); my $ged = Gedcom->new(grammar_file => "gedcom-5.5.grammar", gedcom_file => $gedcom_file); Create a new gedcom object. gedcom_file is the name of the gedcom file to parse. You may optionally pass grammar_version as the version number of the gedcom grammar you want to use. At the moment only version 5.5 is available. If you do not specify a grammar version, you may specify a grammar file as grammar_file. Usually, you will do neither of these, and in this case the grammar version will default to the latest available version, currently 5.5. The read_only parameter indicates that the Gedcom data structure will be used primarily for read_only operations. In this mode the gedcom file is read lazily, such that whenever possible the Gedcom records are not read until they are needed. This can save on both memory and CPU usage, provided that not too much of the gedcom file is needed. If the whole of the gedcom file needs to be read, for example to validate it, or to write it out in a different format, then this option should not be used. When using the read_only option an index file is kept which can also speed up operations. It's usage should be transparant, but will require write access to the directory containing the gedcom file. If you access individuals only by their xref (eg I20) then the index file will allow only the relevant parts of the gedcom file to be read. With or without the read_only option, the gedcom file is accessed in the same fashion and the data structures can be changed. In this respect, the name read_only is not very accurate, but since changing the Gedcom data will generally mean that the data will be written which means that the data will first be read, the read_only option is generally useful when the data will not be written and when not all the data will be read. You may find it useful to experiment with this option and check the amount of CPU time and memory that your application uses. callback is an optional reference to a subroutine which will be called at various times while the gedcom file (and the grammar file, if applicable) is being read. Its purpose is to provide feedback during potentially long operations. The subroutine is called with five arguments: my ($title, $txt1, $txt2, $current, $total) = @_; $title is a brief description of the current operation $txt1 and $txt2 provide more information on the current operation $current is the number of operations performed $total is the number of operations that need to be performed If the subroutine returns false, the operation is aborted. write ----- $ged->write($new_gedcom_file, $flush); Write out the gedcom file. Takes the name of the new gedcom file, and whether or not to indent the output according to the level of the record. $flush defaults to false, but the new file name must be specified. write_xml --------- $ged->write_xml($fh); Write the item to a FileHandle as XML. Takes the name of the new gedcom file. Note that this function is experimental. The XML output doesn't conform to any standard that I know of, because I don't know of any standard. If and when such a standard surfaces, and probably even if it doesn't, I'll change the output from this function. If you make use of this function, beware. I'd also be very interested in hearing from you to determine the requirements for the XML. collect_xrefs ------------- $ged->collect_xrefs($callback); Collect all the xrefs into a data structure ($ged->{xrefs}) for easy location. $callback is not used yet. Called by new(). resolve_xref ------------ my $xref = $self->resolve_xref($value); Return the record $value points to, or undef. resolve_xrefs ------------- $ged->resolve_xrefs($callback); Changes all xrefs to reference the record they are pointing to. Like changing a soft link to a hard link on a Unix filesystem. $callback is not used yet. unresolve_xrefs --------------- $ged->unresolve_xrefs($callback); Changes all xrefs to name the record they contained. Like changing a hard link to a soft link on a Unix filesystem. $callback is not used yet. validate -------- return unless $ged->validate($callback); Validate the gedcom object. This performs a number of consistency checks, but could do even more. $callback is not properly used yet. Any errors found are given out as warnings. If this is unwanted, use $SIG{__WARN__} to catch the warnings. Returns true iff the gedcom object is valid. normalise_dates --------------- $ged->normalise_dates; $ged->normalise_dates("%A, %E %B %Y"); Change all recognised dates into a consistent format. This routine used Date::Manip to do the work, so you can look at it's documentation regarding formats that are recognised and % sequences for the output. Optionally takes a format to use for the output. The default is currently "%A, %E %B %Y", but I may change this, as it seems that some programs don't like that format. renumber -------- $ged->renumber; my %xrefs = $ged->renumber(INDI => 34, FAM => 12, xrefs => [$xref1, $xref2]); Renumber all the records. Optional parameters are: tag name => last used number (defaults to 0) xrefs => list of xrefs to renumber first As a record is renumbered, it is assigned the next available number. The husband, wife, children parents and siblings are then renumbered in that order. This helps to ensure that families are numerically close together. The hash returned is the updated hash that was passed in. sort_sub -------- $ged->order($ged->sort_sub); Default ordering subroutine. The sort is by record type in the following order: HEAD, SUBM, INDI, FAM, NOTE, TRLR, and then by xref within the type. order ----- $ged->order; $ged->order($order_sub); Order all the records. Optionally provide a sort subroutine. This orders the entries within the gedcom object, which will affect the order in which they are written out. The default sort function is Gedcom::sort_sub. You will need to ensure that the HEAD record is first and that the TRLR record is last. individuals ----------- my @individuals = $ged->individuals; Return a list of all the individuals. families -------- my @families = $ged->families; Return a list of all the families. get_individual -------------- my $me = $ged->get_individual("Paul Johnson"); Return a list of all individuals matching the specified name. There are thirteen matches performed, and the results from the first successful match are returned. The matches are: 1 - Xref 2 - Exact 3 - On word boundaries 4 - Anywhere 5 - Exact, case insensitive 6 - On word boundaries, case insensitive 7 - Anywhere, case insensitive 8 - Names in any order, on word boundaries 9 - Names in any order, anywhere 10 - Names in any order, on word boundaries, case insensitive 11 - Names in any order, anywhere, case insensitive 12 - Soundex code 13 - Soundex of name next_xref --------- my $xref = $ged->next_xref("I"); Return the next available xref with the specified prefix.