This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: GIFgraph, Next: GIFgraph/EvenlySpaced, Prev: GD/Text/Wrap, Up: Module List Graph Plotting Module (deprecated) ********************************** NAME ==== GIFgraph - Graph Plotting Module (deprecated) SYNOPSIS ======== use GIFgraph::moduleName; DESCRIPTION =========== *GIFgraph* is a *perl5* module to create and display GIF output for a graph. GIFgraph is nothing more than a wrapper around GD::Graph, and its use is deprecated. It only exists for backward compatibility. The documentation for all the functionality can be found in *Note GD/Graph: GD/Graph,. This module should work with all versions of GD, but it has only been tested with version 1.19 and above. Version 1.19 is the last version that produces GIF output directly. Any version later than that requires a conversion step. The default distribution of GIFgraph uses Image::Magick for this. If you'd like to use something else, please replace the sub png2gif in GIFgraph::Convert with something more to your liking. NOTES ===== Note that if you use GIFgraph with a GD version 1.20 or up that any included logos will have to be in the PNG format. The only time that GIF comes into play is _after_ GD has done its work, and the PNG gets converted to GIF. There are no plans to change that behaviour; it's too much work, and for you, the user, it is a one time conversion of these pictures, when you move from GD < 1.20 to GD >= 1.20. SEE ALSO ======== GD::Graph(3), Chart::PNGgraph(3). AUTHOR ====== Martien Verbruggen Copyright --------- Copyright (C) 1995-2000 Martien Verbruggen. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: GIFgraph/EvenlySpaced, Next: GIFgraph/Map, Prev: GIFgraph, Up: Module List spaces the data points evenly ***************************** NAME ==== GIFgraph::EvenlySpaced - spaces the data points evenly DESCRIPTION =========== This module wraps a GIFgraph object so that the data points become numericaly spaced (aproximately). SYNOPSIS ======== Wrapps a GIFgraph object (probably a GIFgraph::lines) so that the x values are spaced numericaly. Use exactly as your GIFgraph object. Due to a problem I had with AUTOLOAD, it must be the outer wrapper class. Use === $graph = new GIFgraph::lines(400,300); $es = new GIFgraph::EvenlySpaced($graph); or $graph = new GIFgraph::lines(400,300); $withmap = new GIFgraph::WithMap($graph); $es = new GIFgraph::EvenlySpaced($withmap); or even $es = new GIFgraph::EvenlySpaced(new GIFgraph::WithMap(new GIFgraph::lines(400,300))); etc. etc. etc. Functions ========= new Returns a new GIFgraph::EvenlySpaced object $es = new GIFgraph::EvenlySpaced($parentGraph); where $parentGraph is any object that behaves like a GIFgraph::lines type object such as a GIFgraph::WithMap. plot This function is overridden to space the data numericaly along the x-axis. Fields ====== fudge This is a fudge factor used in checking whether one number roughly devides into another. It defaults to 0.1 but if it is obviously doing silly things then change it. Good luck - I don't realy know how it works. Guts ==== This module uses MRP::BaseClass to implement member access functions. To make the 'parent' object behave as if it the super class I have done some magic with AUTOLOAD. This has produced the restriction that you can not wrap an EvenlySpaced object inside another - such as WithMap - that also uses magic. @ISA does not include the parent type as it is not known. The isa() method is overridden to account for this. AUTHOR ====== Matthew Pocock mrp@sanger.ac.uk  File: pm.info, Node: GIFgraph/Map, Next: GIFgraph/WithMap, Prev: GIFgraph/EvenlySpaced, Up: Module List generate HTML map text. *********************** NAME ==== *GIFgraph::Map* - generate HTML map text. SYNOPSIS ======== use GIFgraph::Map; $map = new GIFgraph::Map($gr_object); $map->set(key1 => value1, key2 => value2 ...); $HTML_map = $map->imagemap($gr_file, \@data); DESCRIPTION =========== Is a *perl5* module to generate HTML map text for following graph objects *GIFgraph::pie*, *GIFgraph::bars*, *GIFgraph::point* and *GIFgraph::linespoints*. As a result of its work is created HTML code containing IMG and MAP tags. You simply need to insert this code into the necessary place of your page. In the inserted thus image, its certain parts are the references and at a choice their mouse in a status line of your browser displays the additional information.(See Samples). SAMPLES ======= See the samples directory in the distribution. USAGE ===== First of all you must create *GIFgraht* object, if it necessary set options for its, create array of data and use plot_to_gif routine for create GIF image. For example create *GIFgraph::pie* object: $graphic = new GIFgraph::pie; $graphic->set('title' => 'A Pie Chart', 'label' => 'Label', 'axislabelclr' => 'black', 'pie_height' => 80); @data = (["1st","2nd","3rd","4th","5th","6th"], [ 4, 2, 3, 4, 3, 3.5]); $GIFimage = 'Demo.gif'; $graphic->plot_to_gif($GIFimage, \@data); Then create *Fgraph::Map* object. And set options using set routine, or set it in constructor immediately: $map = new GIFgraph::Map($graphic); $map->set(info => "%x slice contains %.1p% of %s (%x)"); Create HTML map text using the same name of GIF image and array of data as use B routine: $HTML_map = $map->imagemap($GIFimage, \@data); Now you can insert $HTML_map into the necessary place of your HTML page. METHODS AND FUNCTIONS ===================== Constructor Constructor of object has following syntax: new GIFgraph::Map($gr_object, [key1 => value1, key2 => value2 ...]); where $gr_object this is one of the following graph objects: *GIFgraph::pie*, *GIFgraph::bars*, *GIFgraph::point* or *GIFgraph::linespoints*; key1, value1 ... the same as using in set routine. NOTE: Before use constructor you should at first set all properties of graph object. imagemap(file, *\@data*) Generate HTML map text using GIF file $file and reference to array of data - \@data. This parameters must the same as used in plot_to_gif routine. set(*key1* => *value1*, *key2* => *value2* .... ) Set options. See OPTIONS. OPTIONS ======= *hrefs*, *lhrefs* Set hyper reference for each data (hrefs), and for each legend (lhrefs). Array @hrefs must the same size as arrays in @data list, otherwise null elements of @hrefs set to default. Similarly array @lhrefs must the same size as legend array. Default use the simple JavaScript code 'javascript:;' instead reference, which do nothing. Example of *@hrefs* array: for *GIFgraph::pie* if @data = ([ "1st", "2nd", "3rd"], [ 4, 2, 3]); then @hrefs = ["1.htm","2.htm","3.htm"]; for *GIFgraph::bars* *GIFgraph::point* and *GIFgraph::linespoints* if @data = ([ "1st", "2nd", "3rd"], [ 5, 12, 24], [ 1, 2, 5]); then @hrefs = (["1.htm","2.htm","3.htm"], ["4.htm","5.htm","6.htm"]); Example of *@lhrefs* array; if @legend = [ 'one', 'two','three']; then @lhrefs = ["1.htm","2.htm","3.htm"]; info, legend Set information string for data and for legend. It will be show in status line of your browser. Format of this string the same for each data, but you may use special symbols for receive individual information. Now available following symbols: *%x* - Is replaced on x values in @data (first array) *%y* - Is replaced on y values in @data (other arrays) %s - Is replaced on sum of all y values. Only for GIFgraph::pie object. *%p* - Is replaced on value, which show what part of all contains this data. Only for *GIFgraph::pie* object. %l - Is replaced on legend. Only for *GIFgraph::bars*, *GIFgraph::points* and *GIFgraph::linespoints* objects. For %x, %y, %s and %p parameters you may use special format (the same as use sprintf routine) for round data: %.d{x|y|p|s}, where d is a digit from 0 to 9. For example %.0p or %.3x. It is desirable use if %x, %y, %s or %p if floating numbers Default is 'x=%x y=%y' for info, and '%l' for legend. You can set any attribute in IMG tag (except UseMap, Src, Width, Height and Border, they will be set automatically) use set routine: set(img_option => value), where option is IMG attribute. For example: routine set(img_Alt => 'Example'); include Alt='Example' to IMG tag. *newWindow*, *window_** If newWindow set to TRUE and link does not contain JavaScript code (javascript:...), that link will be open in new navigator window, Parameters of new window you can set using window_* parameters, similarly img_* option. AUTHOR ====== Roman Kosenko Contact info ------------ E-mail: ra@amk.al.lg.ua Home page: http://amk.al.lg.ua/~ra Copyright --------- Copyright (C) 1999 Roman Kosenko. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: GIFgraph/WithMap, Next: GIFgraph/boxplot, Prev: GIFgraph/Map, Up: Module List generates HTML map text while plotting graph ******************************************** NAME ==== GIFgraph::WithMap - generates HTML map text while plotting graph DESCRIPTION =========== Generates the html map block for a graph so that data series become 'clickable', SYNOPSIS ======== This module extends GIFgraph objects such as GIFgraph::lines. You can do everything that you would with a GIFgraph object. In addition, when the data is plotted, it generates some MAP html text. The series will be labeled 'series 1', 'series 2' etc. unless the $obj->seriesnames has been set. For each series, it will create a polygon area, with the following structure (assuming series is named 'Green', and that the links member array is empty: Green So - clicking on the series will take you to #Green. If you don't specify #Green in the document, clicking on it will do very little. If you have (e.g. in the key) then it should take you there. new === Use something like $map = new GIFgraph::WithMap(new GIFgraph::lines(400,300)); fields ====== map Once plot has been called, map contains the map text. print $graphWithMap->map; fuzz This is the up/down fuzz used to construct the ploygon. It defaults to 1 - so the polygon will be three pixles wide (the pixle drawn and one above and below it). mapname Set this before calling plot. This is the name of the map, as given by usemap="#mapname" in . It is a fatal error to try to plot without a name. seriesnames Array of names for the series. If a name is absent for a series (or all series) then it will be named Series #. This must be set before the graph is plotted. $graphWithMap->seriesnames('name1', 'name2'); Array of links for the series. If a link is absent for a series (or all series) then it will be named #SeriesName (where SeriesName is generated as described in `seriwsnames' in this node). Guts ==== This module uses MRP::BaseClass to implement member access functions. In the constructor, a new object is created that is a meld of an MRP::BaseClass derived object, and the GIFgraph object passed in. The type of that object is stoored in _GIFgraph. In AUTOLOAD, first I check to see if the GIFgraph object's package named in _GIFgraph implements the function. If it does, then I return the value of that function - i.e. it behaves as if the object inherits from that package. If that fails, then I return the value of SUPER::AUTLOLOAD, which will presumably handle it or die gracefully. Hey presto - dynamic parenting. @ISA does not include anything to implement a GIFgraph object as a parent. However, I have overridden 'isa' to account for this.  File: pm.info, Node: GIFgraph/boxplot, Next: GIFgraph/colour, Prev: GIFgraph/WithMap, Up: Module List Box and Whisker Graph Module for Perl 5. **************************************** NAME ==== Boxplot - Box and Whisker Graph Module for Perl 5. SYNOPSIS ======== use GIFgraph::boxplot; DESCRIPTION =========== *boxplot* is a *perl5* module that uses GIFgraph, GD, and Statistics::Descriptive to create and display GIF output for box and whisker graphs. EXAMPLES ======== See the samples directory in the distribution. USAGE ===== Fill an array of arrays with the x values and array references to the data sets to be used. Make sure that every array has the same number of data sets as there are x values, otherwise *GIFgraph* will complain and refuse to compile the graph. For example: $one = [210..275]; $two = [180, 190, 200, 220, 235, 245]; $three = [40, 140..150, 160..180, 250]; $four = [100..125, 136..140]; $five = [10..50, 100, 180]; @data = ( ["1st", "2nd", "3rd", "4th", "5th"], [$one, $two, $three, $four, $five ], [ [-25, 1..15], [-45, 25..45, 100], [70, 42..125], [undef], [180..250] ], # as many sets of data sets as you like ); If you don't have any data for a certain dataset, you can use undef as shown above, and *GIFgraph* will skip that box. Create a new *GIFgraph* object by calling the new operator on the type *boxplot*: $my_graph = new GIFgraph::boxplot( ); Set the graph options: $my_graph->set( x_label => 'X Label', y_label => 'Y label', title => 'Some simple graph', upper_percent => 70, lower_percent => 35, step_const => 1.8 ); Output the graph: $my_graph->plot_to_gif( "sample01.gif", \@data ); METHODS AND FUNCTIONS ===================== See GIFgraph documentation for methods for all GIFgraph graphs. OPTIONS ======= Options for all graphs ---------------------- See GIFgraph documentation for options for all graphs. Options for graphs with axes ---------------------------- Boxplot has axes, and has all of the options available to the other graphs with axes: *bars*, lines, points, *linespoints* and area. See the GIFgraph documentation for all of these options. Options specific to Boxplot graphs ---------------------------------- do_stats, upper_percent, lower_percent If *do_stats* is a true value, the program assumes that raw data are used for input. It calculates the statistics for each box's data, and draws the box, mean, median, upper and lower whiskers, outliers, and far-out-values accordingly. The top and bottom of the box are determined by the numbers given for upper_percent and lower_percent. For example, if you wanted to have the box contain all the data from the 20% to 80% range, you would use: $my_graph->set( lower_percent => 20, upper_percent => 80 ); If *do_stats* is set to 0, the program assumes that the user has already calculated the required statistics for every box. The user must input these statistics in place of the raw data: # data must be in this form: # $data = [mean, lowest, lower-percentile, median, upper-precentile, highest]; $one = [27, -35, 14, 29, 39, 52]; $two = [41, -140, 29, 45, 62, 125]; $three = [100, 30, 88, 95, 115, 155]; $four = [80, -100, 60, 100, 110, 195]; @data = ( ["1st", "2nd", "3rd", "4th"], [ $one, $two, $three, $four], # as many sets as you like, all with the required statistical data ); $my_graph = new GIFgraph::boxplot(); $my_graph->set( box_spacing => 35, do_stats => 0 ); Notice that if do_stats is set to 0, upper_percent and lower_percent are not used, because the user is able to input the actual value for the lower-percentile and upper-percetile. Also notice that outliers and far-out-values are not drawn, because the program does not have the data points to use. However, the lowest or highest values can be drawn as outliers or far-out-values if they fall outside of the whiskers. Default: do_stats = 1, upper_percent = 75, lower_percent = 25. box_spacing Number of pixels to leave open between boxes. This works well in most cases, but on some platforms, a value of 1 will be rounded off to 0. Default: box_spacing = 10 warnings If set to 1, warnings are printed to the standard out when the user sets parameters to questionable values. For example, if there are not enough pixels to draw the boxes properly because there are too many data sets for the given image size, or because the box_spacing is set too high, then a warning is printed so the user is aware of the problem. If set to 0, all warnings are turned off. This option is for users who do not want anything to be printed to the standard output. Default: warnings = 1 step_const Sets the step size equal to step_const box-heights, where the box-height is the distance from the top of the box to the bottom. The whiskers are then drawn one step from the top/bottom of the box, or to the largest/smallest data value, whichever is closer to the box. If there are values further than one step from the box, then the whiskers are drawn to one step from the box, and those values further than the whiskers are drawn as either outliers or far-out-values as explained below. step_cont can be any number greater than 0. Default: step_const = 1.5 fov_const Sets the distance that will mark the boundary between outliers and far-out-values. Outliers will be drawn between the whisker and fov_const steps from the whisker. Far-out-values will be drawn for values that fall farther than fov_const steps from the whisker. fov_const can be any number greater than 0. Default: fov_const = 1 box_fill When set to 1, the boxes are filled with the color for that data set. When set to 0, only the symbols and the outlines of the boxes will be drawn. Default: box_fill = 1 symbolc The color for drawing the symbols and box outlines. Default: symbolc = 'dblue' NOTES ===== This module was designed to function in the same way as other GIFgraph graph types. It has all of the same functionality (except for mixed graphs) as the other graphs. This functionality includes how to set the colors that fill the boxes (same as Bars), change the size of the margins between the plot and the edge of the GIF, etc. Please read the GIFgraph documentation for the full set of options avaiable. AUTHOR ====== Written by: Nigel Wright. Design and Funding: Mark Landry, Client/Server Architects, Inc. Contact info ------------ email: nwright@hmc.edu Copyright --------- Copyright (C) 1999 Nigel Wright. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: GIFgraph/colour, Next: GNOME/GNORBA, Prev: GIFgraph/boxplot, Up: Module List Colour manipulation routines for use with GIFgraph ************************************************** NAME ==== Colour - Colour manipulation routines for use with GIFgraph SYNOPSIS ======== use GIFgraph::colour qw( :colours :lists :files ); DESCRIPTION =========== The *Colour* Package provides a few routines to convert some colour names to RGB values. Also included are some functions to calculate the hue and luminance of the colours, mainly to be able to sort them. The :colours tags can be used to import the *_rgb*, *_hue*, and *_luminance* functions, the :lists tag for *colour_list* and *sorted_colour_list*, and the :files tag exports the *read_rgb* function. FUNCTIONS ========= Colour::colour_list( *number of colours* ) Returns a list of *number of colours* colour names known to the package. Colour::sorted_colour_list( *number of colours* ) Returns a list of *number of colours* colour names known to the package, sorted by luminance or hue. *NB.* Right now it always sorts by luminance. Will add an option in a later stage to decide sorting method at run time. Colour::_rgb( *colour name* ) Returns a list of the RGB values of *colour name*. Colour::_hue( *R,G,B* ) Returns the hue of the colour with the specified RGB values. Colour::_luminance( *R,G,B* ) Returns the luminance of the colour with the specified RGB values. Colour::read_rgb( `file name' ) Reads in colours from a rgb file as used by the X11 system. Doing something like: use GIFgraph::bars; use GIFgraph::colour; GIFgraph::colour::read_rgb("rgb.txt") or die "cannot read colours"; Will allow you to use any colours defined in rgb.txt in your graph. PREDEFINED COLOUR NAMES ======================= white, lgray, gray, dgray, black, lblue, blue, dblue, gold, lyellow, yellow, dyellow, lgreen, green, dgreen, lred, red, dred, lpurple, purple, dpurple, lorange, orange, pink, dpink, marine, cyan, lbrown, dbrown.  File: pm.info, Node: GNOME/GNORBA, Next: GPS/Garmin, Prev: GIFgraph/colour, Up: Module List Perl extension for using ORBit with GNOME ***************************************** NAME ==== GNOME::GNORBA - Perl extension for using ORBit with GNOME SYNOPSIS ======== use GNOME::GNORBA; DESCRIPTION =========== The GNOME::GNORBA module sets up cookies appropriately for using ORBit in a GNOME environment, and also provides an interface to GOAD. (The GNOME Object Activation Directory) AUTHOR ====== Owen Taylor Copyright Red Hat, Inc, 1999. SEE ALSO ======== perl(1).  File: pm.info, Node: GPS/Garmin, Next: GPS/Garmin/Handler, Prev: GNOME/GNORBA, Up: Module List Perl interface to GPS equipment using the Garmin Protocol ********************************************************* NAME ==== GPS::Garmin - Perl interface to GPS equipment using the Garmin Protocol SYNOPSIS ======== use GPS::Garmin; $gps = new GPS::Garmin( 'Port' => '/dev/ttyS0', 'Baud' => 9600, ); To transfer current position, and direction symbols: ($latsign,$lat,$lonsign,$lon) = $gps->get_position; To transfer current time: ($sec,$min,$hour,$mday,$mon,$year) = $gps->get_time; To transfer trackpoints: $gps->prepare_transfer("trk"); while($gps->records) { ($lat,$lon,$time) = $gps->grab; } To transfer Waypoints: $gps->prepare_transfer("wpt"); while($gps->records) { ($title,$lat,$lon,$desc) = $gps->grab; } DESCRIPTION =========== GPS::Garmin allow the connection and use of of a GPS receiver in perl scripts. Currently only the GRMN/GRMN protocol is implemented but NMEA is a work in progress. This module currently works with Garmin GPS II+ equipments, but should work on most Garmin receivers that support the GRMN/GRMN protocol. GETTING STARTED =============== Make sure your GPS receiver is in host mode, GRMN/GRMN protocol. To start a connection in your script, just: use GPS::Garmin; $gps = new GPS::Garmin ( 'Port' => '/dev/ttyS0', 'Baud' => 9600, ) or die "Unable to connect to receiver: $!"; Where Port is the port that your GPS is connected to, and Baud the speed of connection ( default is 9600 bps). To know current coordinates: ($latsign,$lat,$lnsign,$lon) = $gps->get_position; $ltsign is "S" or "N" (South or North) $lat is current latitude in degrees.minutes. $lnsign is "W" or "E" (West or East) $lon is current longitude in degrees.minutes. To transfer the track records: $gps->prepare_transfer("trk"); while($gps->records) { ($lat,$lon,$time) = $gps->grab; } $time is in unix epoch seconds KNOWN LIMITATIONS ================= - Trackpoint transfer won't work in the following Garmin devices, since they don't support it: GPS 50 GPS 55 GPS 150 GPS 150 XL GPS 165 GNC 250 GNC 250XL GNC 300 GNC 300XL You can check you GPS capabilities by looking at the table in page 50 of the Garmin protocol specification at http://www.garmin.com/support/protocol.html - You need to have Win32::SerialPort to have GPS::Garmin working in Windows. BUGS ==== Lacks documentation AUTHOR ====== Joao Pedro B Gonçalves , joaop@iscsp.utl.pt SEE ALSO ======== Peter Bennett's GPS www and ftp directory:' ftp://sundae.triumf.ca/pub/peter/index.html. http://vancouver-webpages.com/peter/idx_garmin.html Official Garmin Communication Protocol Reference http://www.garmin.com/support/protocol.html  File: pm.info, Node: GPS/Garmin/Handler, Next: GPS/Serial, Prev: GPS/Garmin, Up: Module List Handlers to Garmin data *********************** NAME ==== GPS::Garmin::Handler - Handlers to Garmin data SYNOPSIS ======== use GPS::Handler; DESCRIPTION =========== Used internally AUTHOR ====== Joao Pedro B Gonçalves , joaop@sl.pt SEE ALSO ======== Peter Bennett's GPS www and ftp directory:' ftp://sundae.triumf.ca/pub/peter/index.html. http://vancouver-webpages.com/peter/idx_garmin.html Official Garmin Communication Protocol Reference http://www.garmin.com/support/protocol.html  File: pm.info, Node: GPS/Serial, Next: GSSAPI, Prev: GPS/Garmin/Handler, Up: Module List Access to the Serial port for the GPS::* modules ************************************************ NAME ==== GPS::Serial - Access to the Serial port for the GPS::* modules SYNOPSIS ======== use GPS::Serial; DESCRIPTION =========== Used internally AUTHOR ====== Joao Pedro B Gonçalves , joaop@sl.pt SEE ALSO ======== Peter Bennett's GPS www and ftp directory:' ftp://sundae.triumf.ca/pub/peter/index.html. http://vancouver-webpages.com/peter/idx_garmin.html Official Garmin Communication Protocol Reference http://www.garmin.com/support/protocol.html  File: pm.info, Node: GSSAPI, Next: GSSAPI/OID, Prev: GPS/Serial, Up: Module List Perl extension providing access to the GSSAPIv2 library ******************************************************* NAME ==== GSSAPI - Perl extension providing access to the GSSAPIv2 library SYNOPSIS ======== use GSSAPI; # lots of complicated stuff here DESCRIPTION =========== This module gives access to the routines of the GSSAPI library, as described in rfc2743 and rfc2744 and implemented by the Kerberos-1.2 distribution from MIT. The API presented by this module is a mildly object oriented reinterpretation of the C API, where opaque C structures are Perl objects, but the style of function call has been left mostly untouched. As a result, most routines modify one or more of the parameters passed to them, reflecting the C call-by-reference (or call-by-value-return) semantics. All users of this module are therefore strongly advised to localize all usage of these routines to minimize pain if and when the API changes. SEE ALSO ======== RFC2743 RFC2744 GSSAPI::Status(3p) GSSAPI::OID(3p) GSSAPI::OID::Set(3p) perl(1) EXPORT ------ GSS_C_ACCEPT GSS_C_AF_APPLETALK GSS_C_AF_BSC GSS_C_AF_CCITT GSS_C_AF_CHAOS GSS_C_AF_DATAKIT GSS_C_AF_DECnet GSS_C_AF_DLI GSS_C_AF_DSS GSS_C_AF_ECMA GSS_C_AF_HYLINK GSS_C_AF_IMPLINK GSS_C_AF_INET GSS_C_AF_LAT GSS_C_AF_LOCAL GSS_C_AF_NBS GSS_C_AF_NS GSS_C_AF_NULLADDR GSS_C_AF_OSI GSS_C_AF_PUP GSS_C_AF_SNA GSS_C_AF_UNSPEC GSS_C_AF_X25 GSS_C_ANON_FLAG GSS_C_BOTH GSS_C_CALLING_ERROR_MASK GSS_C_CALLING_ERROR_OFFSET GSS_C_CONF_FLAG GSS_C_DELEG_FLAG GSS_C_EMPTY_BUFFER GSS_C_GSS_CODE GSS_C_INDEFINITE GSS_C_INITIATE GSS_C_INTEG_FLAG GSS_C_MECH_CODE GSS_C_MUTUAL_FLAG GSS_C_NO_BUFFER GSS_C_NO_CHANNEL_BINDINGS GSS_C_NO_CONTEXT GSS_C_NO_CREDENTIAL GSS_C_NO_NAME GSS_C_NO_OID GSS_C_NO_OID_SET GSS_C_PROT_READY_FLAG GSS_C_QOP_DEFAULT GSS_C_REPLAY_FLAG GSS_C_ROUTINE_ERROR_MASK GSS_C_ROUTINE_ERROR_OFFSET GSS_C_SEQUENCE_FLAG GSS_C_SUPPLEMENTARY_MASK GSS_C_SUPPLEMENTARY_OFFSET GSS_C_TRANS_FLAG GSS_S_BAD_BINDINGS GSS_S_BAD_MECH GSS_S_BAD_NAME GSS_S_BAD_NAMETYPE GSS_S_BAD_QOP GSS_S_BAD_SIG GSS_S_BAD_STATUS GSS_S_CALL_BAD_STRUCTURE GSS_S_CALL_INACCESSIBLE_READ GSS_S_CALL_INACCESSIBLE_WRITE GSS_S_COMPLETE GSS_S_CONTEXT_EXPIRED GSS_S_CONTINUE_NEEDED GSS_S_CREDENTIALS_EXPIRED GSS_S_CRED_UNAVAIL GSS_S_DEFECTIVE_CREDENTIAL GSS_S_DEFECTIVE_TOKEN GSS_S_DUPLICATE_ELEMENT GSS_S_DUPLICATE_TOKEN GSS_S_FAILURE GSS_S_GAP_TOKEN GSS_S_NAME_NOT_MN GSS_S_NO_CONTEXT GSS_S_NO_CRED GSS_S_OLD_TOKEN GSS_S_UNAUTHORIZED GSS_S_UNAVAILABLE GSS_S_UNSEQ_TOKEN Exportable functions -------------------- $status = indicate_mechs($oidset) # Constant OIDs provided: $oid = gss_nt_user_name; $oid = gss_nt_machine_uid_name; $oid = gss_nt_string_uid_name; $oid = gss_nt_service_name; $oid = gss_nt_exported_name; $oid = gss_nt_service_name_v2; $oid = gss_nt_krb5_name; $oid = gss_nt_krb5_principal; $oid = gss_mech_krb5; $oid = gss_mech_krb5_old; $oid = gss_mech_krb5_v2; # Constant OID sets provided: $oidset = gss_mech_set_krb5; $oidset = gss_mech_set_krb5_old; $oidset = gss_mech_set_krb5_both; $oidset = gss_mech_set_krb5_v2; $oidset = gss_mech_set_krb5_v1v2; All other functions are class or instance methods. AUTHOR ====== Philip Guenther, guenther@gac.edu  File: pm.info, Node: GSSAPI/OID, Next: GSSAPI/OID/Set, Prev: GSSAPI, Up: Module List methods for handling GSSAPI OIDs and some constant OIDs ******************************************************* NAME ==== GSSAPI::OID - methods for handling GSSAPI OIDs and some constant OIDs SYNOPSIS ======== use GSSAPI; #$oid = GSSAPI::OID->new; # rarely needed or wanted $status = GSSAPI::OID->from_str($oid, "{ 1 2 840 113554 1 2 1 1 }"); $status = $oid->to_str($str); $status = $oid->inquire_names($oidset); # Constant OIDs provided: $oid = gss_nt_user_name; $oid = gss_nt_machine_uid_name; $oid = gss_nt_string_uid_name; $oid = gss_nt_service_name; $oid = gss_nt_exported_name; $oid = gss_nt_service_name_v2; $oid = gss_nt_krb5_name; $oid = gss_nt_krb5_principal; $oid = gss_mech_krb5; $oid = gss_mech_krb5_old; $oid = gss_mech_krb5_v2; DESCRIPTION =========== `GSSAPI::OID' objects are used as unique indentifiers/constants for 'mechanisisms' - the particular protocol and version being used - and for the encodings used to represent names. In many cases you can request the default mechanism or encoding for the implmentation by using GSS_C_NO_OID. Check the description of the routine in rfc2743 if you're not sure. AUTHOR ====== Philip Guenther, guenther@gac.edu SEE ALSO ======== perl(1) GSSAPI(3p) GSSAPI::OID::Set(3p) RFC2743  File: pm.info, Node: GSSAPI/OID/Set, Next: GSSAPI/Status, Prev: GSSAPI/OID, Up: Module List methods for handling sets of GSSAPI OIDs, and some constant OID sets. ********************************************************************* NAME ==== GSSAPI::OID::Set - methods for handling sets of GSSAPI OIDs, and some constant OID sets. SYNOPSIS ======== use GSSAPI; $oidset = GSSAPI::OID::Set->new; $status = $oidset->insert($oid); $status = $oidset->contains($oid, $isthere); if ($status && $isthere) { # blah blah blah } # Constant OID sets provided: $oidset = gss_mech_set_krb5; $oidset = gss_mech_set_krb5_old; $oidset = gss_mech_set_krb5_both; $oidset = gss_mech_set_krb5_v2; $oidset = gss_mech_set_krb5_v1v2; DESCRIPTION =========== `GSSAPI::OID::Set' objects are simple sets of GSSAPI:OIDs (duh). BUGS ==== There's no way to list the OIDs in a set; you can only check to see if a particular one is present. This is really a bug in the C API, so any fix would be implementation specific. AUTHOR ====== Philip Guenther, guenther@gac.edu SEE ALSO ======== perl(1) GSSAPI(3p) GSSAPI::OID(3p) RFC2743  File: pm.info, Node: GSSAPI/Status, Next: GTop, Prev: GSSAPI/OID/Set, Up: Module List methods for handlings GSSAPI statuses ************************************* NAME ==== GSSAPI::Status - methods for handlings GSSAPI statuses SYNOPSIS ======== use GSSAPI; $status = GSSAPI::Status->new(GSS_S_COMPLETE, 0); if (GSS_ERROR($status->major)) { die "a horrible death"; } if (! $status) { # another way of writing the above die "a horrible death"; } $status = $some_GSSAPI->someop($args1, etc); if ($status) { foreach ($status->generic_message, $status->specific_message) { print "GSSAPI error: $_\n"; } die "help me"; } DESCRIPTION =========== `GSSAPI::Status' objects are returned by most other GSSAPI operations. Such statuses consist of a GSSAPI generic code and, for most operations, a mechanism specific code. These numeric codes can be accessed via the methods `major' and `minor'. The standard textual messages that go with the current status can be obtained via the `generic_message' and `specific_message' methods. Each of these returns a list of text which should presumably be displayed in order. The generic code part of a GSSAPI::Status is composed of three subfields that can be accessed with the `GSS_CALLING_ERROR', `GSS_ROUTINE_ERROR', and `GSS_SUPPLEMENTARY_INFO' functions. The returned values can be compared against the constants whose names start with `GSS_S_' if your code wants to handle particular errors itself. The `GSS_ERROR' function returns true if and only if the given generic code contains neither a calling error nor a routine error. When evaluated in a boolean context, a `GSSAPI::Status' object will be true if and only if the major status code is `GSS_S_COMPLETE'. When evaluated in a string contect, a `GSSAPI::Status' object will return the generic and specific messages all joined together with newlines. This may or may not make `die $status' work usefully. BUGS ==== The base objects are currently implmented as a blessed C structure containing the major and minor status codes. It should probably be a blessed array or hash instead, thereby cutting down on the amount of C code involved and making it more flexible. AUTHOR ====== Philip Guenther, guenther@gac.edu SEE ALSO ======== perl(1) RFC2743  File: pm.info, Node: GTop, Next: Games/Alak, Prev: GSSAPI/Status, Up: Module List Perl interface to libgtop ************************* NAME ==== GTop - Perl interface to libgtop SYNOPSIS ======== use GTop (); my $gtop = GTop->new; DESCRIPTION =========== Perl interface to libgtop: http://home-of-linux.org/gnome/libgtop/ CLASSES ======= GTop::Cpu --------- my $cpu = $gtop->cpu; flags my $flags = $cpu->flags; total my $total = $cpu->total; user my $user = $cpu->user; nice my $nice = $cpu->nice; sys my $sys = $cpu->sys; idle my $idle = $cpu->idle; frequency my $frequency = $cpu->frequency; GTop::Fsusage ------------- my $fsusage = $gtop->fsusage($disk); flags my $flags = $fsusage->flags; blocks my $blocks = $fsusage->blocks; bfree my $bfree = $fsusage->bfree; bavail my $bavail = $fsusage->bavail; files my $files = $fsusage->files; ffree my $ffree = $fsusage->ffree; GTop::Loadavg ------------- my $loadavg = $gtop->loadavg; flags my $flags = $loadavg->flags; nr_running my $nr_running = $loadavg->nr_running; nr_tasks my $nr_tasks = $loadavg->nr_tasks; last_pid my $last_pid = $loadavg->last_pid; GTop::Mem --------- my $mem = $gtop->mem; flags my $flags = $mem->flags; total my $total = $mem->total; used my $used = $mem->used; free my $free = $mem->free; shared my $shared = $mem->shared; buffer my $buffer = $mem->buffer; cached my $cached = $mem->cached; user my $user = $mem->user; locked my $locked = $mem->locked; GTop::Mountlist --------------- my $mountlist = $gtop->mountlist($all_fs); flags my $flags = $mountlist->flags; number my $number = $mountlist->number; total my $total = $mountlist->total; size my $size = $mountlist->size; GTop::Netload ------------- my $netload = $gtop->netload($interface); flags my $flags = $netload->flags; if_flags my $if_flags = $netload->if_flags; mtu my $mtu = $netload->mtu; subnet my $subnet = $netload->subnet; address my $address = $netload->address; packets_in my $packets_in = $netload->packets_in; packets_out my $packets_out = $netload->packets_out; packets_total my $packets_total = $netload->packets_total; bytes_in my $bytes_in = $netload->bytes_in; bytes_out my $bytes_out = $netload->bytes_out; bytes_total my $bytes_total = $netload->bytes_total; errors_in my $errors_in = $netload->errors_in; errors_out my $errors_out = $netload->errors_out; errors_total my $errors_total = $netload->errors_total; collisions my $collisions = $netload->collisions; GTop::ProcArgs -------------- my $proc_args = $gtop->proc_args($pid); flags my $flags = $proc_args->flags; size my $size = $proc_args->size; GTop::ProcMap ------------- my $proc_map = $gtop->proc_map($pid); flags my $flags = $proc_map->flags; number my $number = $proc_map->number; total my $total = $proc_map->total; size my $size = $proc_map->size; GTop::ProcMem ------------- my $proc_mem = $gtop->proc_mem($pid); flags my $flags = $proc_mem->flags; size my $size = $proc_mem->size; vsize my $vsize = $proc_mem->vsize; resident my $resident = $proc_mem->resident; share my $share = $proc_mem->share; rss my $rss = $proc_mem->rss; rss_rlim my $rss_rlim = $proc_mem->rss_rlim; GTop::ProcSegment ----------------- my $proc_segment = $gtop->proc_segment($pid); flags my $flags = $proc_segment->flags; text_rss my $text_rss = $proc_segment->text_rss; shlib_rss my $shlib_rss = $proc_segment->shlib_rss; data_rss my $data_rss = $proc_segment->data_rss; stack_rss my $stack_rss = $proc_segment->stack_rss; dirty_size my $dirty_size = $proc_segment->dirty_size; start_code my $start_code = $proc_segment->start_code; end_code my $end_code = $proc_segment->end_code; start_stack my $start_stack = $proc_segment->start_stack; GTop::ProcState --------------- my $proc_state = $gtop->proc_state($pid); flags my $flags = $proc_state->flags; GTop::ProcTime -------------- my $proc_time = $gtop->proc_time($pid); flags my $flags = $proc_time->flags; start_time my $start_time = $proc_time->start_time; rtime my $rtime = $proc_time->rtime; utime my $utime = $proc_time->utime; stime my $stime = $proc_time->stime; cutime my $cutime = $proc_time->cutime; cstime my $cstime = $proc_time->cstime; timeout my $timeout = $proc_time->timeout; it_real_value my $it_real_value = $proc_time->it_real_value; frequency my $frequency = $proc_time->frequency; GTop::ProcUid ------------- my $proc_uid = $gtop->proc_uid($pid); flags my $flags = $proc_uid->flags; uid my $uid = $proc_uid->uid; euid my $euid = $proc_uid->euid; gid my $gid = $proc_uid->gid; egid my $egid = $proc_uid->egid; pid my $pid = $proc_uid->pid; ppid my $ppid = $proc_uid->ppid; pgrp my $pgrp = $proc_uid->pgrp; session my $session = $proc_uid->session; tty my $tty = $proc_uid->tty; tpgid my $tpgid = $proc_uid->tpgid; priority my $priority = $proc_uid->priority; nice my $nice = $proc_uid->nice; GTop::Proclist -------------- my $proclist = $gtop->proclist; flags my $flags = $proclist->flags; number my $number = $proclist->number; total my $total = $proclist->total; size my $size = $proclist->size; GTop::Swap ---------- my $swap = $gtop->swap; flags my $flags = $swap->flags; total my $total = $swap->total; used my $used = $swap->used; free my $free = $swap->free; pagein my $pagein = $swap->pagein; pageout my $pageout = $swap->pageout; GTop::Uptime ------------ my $uptime = $gtop->uptime; flags my $flags = $uptime->flags; AUTHOR ====== Doug MacEachern  File: pm.info, Node: Games/Alak, Next: Games/Cards, Prev: GTop, Up: Module List simple game-tree implementation of a gomoku-like game ***************************************************** NAME ==== Games::Alak - simple game-tree implementation of a gomoku-like game SYNOPSIS ======== % perl -MGames::Alak -e Games::Alak::play ...Or just run Alak.pm as if it were a program... ...Program responds with output, and a prompt: Lookahead set to 3. I am X, you are O. Enter h for help X moves from 1 to 5, yielding .xxxx..oooo alak> ...and now you enter the commands to play. DESCRIPTION =========== This module implements a simple game-tree system for the computer to play against the user in a game of Alak. You can just play the game for fun; or you can use this module as a starting point for understanding game trees (and implementing smarter strategy - the module's current logic is fairly simple-minded), particularly after reading my *Perl Journal* #18 article on trees, which discusses this module's implementation of game trees as an example of general tree-shaped data structures. RULES ===== Alak was invented by the mathematician A. K. Dewdney, and described in his 1984 book *Planiverse*. The rules of Alak are simple - at least as I've (mis?)understood them and implemented them here: * Alak is a two-player game played on a one-dimensional board with eleven slots on it. Each slot can hold at most one piece at a time. There's two kinds of pieces, which I represent here as "x" and "o" - x's belong to one player (called X - that's the computer), o's to the other (called O - that's you). * The initial configuration of the board is: xxxx___oooo For sake of reference, the slots are numbered from 1 (on the left) to 11 (on the right), and X always has the first move. * The players take turns moving. At each turn, each player can move only one piece, once. (This is unlike checkers, where you move one piece per move but get to keep moving it if you jump an your opponent's piece.) A player cannot pass up on his turn. A player can move any one of his pieces to the next unoccupied slot to its right or left, which may involve jumping over occupied slots. A player cannot move a piece off the side of the board. * If a move creates a pattern where the opponent's pieces are surrounded, on both sides, by two pieces of the mover's color (with no intervening unoccupied blank slot), then those surrounded pieces are removed from the board. * The goal of the game is to remove all of your opponent's pieces, at which point the game ends. Removing all-but-one ends the game as well, since the opponent can't surround you with one piece, and so will always lose within a few moves anyway. SAMPLE GAME =========== A game between X (computer) and a particularly dim O (human): xxxx___oooo ^ Move 1: X moves from 3 (shown with caret) to 5 (Note that any of X's pieces could move, but that the only place they could move to is 5.) xx_xx__oooo ^ Move 2: O moves from 9 to 7. xx_xx_oo_oo ^ Move 3: X moves from 4 to 6. xx__xxoo_oo ^ Move 4: O (stupidly) moves from 10 to 9. xx__xxooo_o ^ Move 5: X moves from 5 to 10, making the board "xx___xoooxo". The three o's that X just surrounded are removed. xx___x___xo O has only one piece, so has lost. INTERFACE ========= This module uses Term::ReadLine to give you a prompt at which you can type commands. Entering "h" for help at that prompt will give instructions on how to interact with the game. When in doubt, consult the source - it's made to be fairly clear. REFERENCES ========== Burke, Sean M. 2000. "Trees". (In submission: actual article title may differ.) Article in *The Perl Journal* #18. `http://www.tpj.com/' [Portions of this POD are excerpted from that article.] Dewdney, A[lexander] K[eewatin]. 1984. *Planiverse: Computer Contact with a Two-Dimensional World.* Poseidon Press, New York. COPYRIGHT ========= Copyright (c) 2000 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. AUTHOR ====== Sean M. Burke, sburke@cpan.org Thanks to A. K. Dewdney (`http://www.dewdney.com/') for his encouragement in writing my (abovementioned) TPJ article, as well as for having written the enjoyable book where he briefly describes it.  File: pm.info, Node: Games/Cards, Next: Games/Cards/Tk, Prev: Games/Alak, Up: Module List Perl module for writing and playing card games ********************************************** NAME ==== Games::Cards - Perl module for writing and playing card games SYNOPSIS ======== use Games::Cards; my $Rummy = new Games::Cards::Game; # Create the correct deck for a game of Rummy. my $Deck = new Games::Cards::Deck ($Rummy, "Deck"); # shuffle the deck and create the discard pile $Deck->shuffle; my $Discard = new Games::Cards::Queue "Discard Pile"; # Deal out the hands foreach my $i (1 .. 3) { my $hand = new Games::Cards::Hand "Player $i" ; $Deck->give_cards($hand, 7); $hand->sort_by_value; push @Hands, $hand; } # print hands (e.g. "Player 1: AS 2C 3C 3H 10D QS KH") foreach (@Hands) { print ($_->print("short"), "\n") } $Hands[1]->give_a_card ($Discard, "8D"); # discard 8 of diamonds DESCRIPTION =========== This module creates objects and methods to allow easier programming of card games in Perl. It allows you to do things like create decks of cards, have piles of cards, hands, and other sets of cards, turn cards face-up or face-down, and move cards from one set to another. Which is pretty much all you need for most card games. Sub-packages include: Games::Cards::Undo This package handles undoing and redoing moves (important for solitaire). and Games::Cards::Tk This package allows you to write games that use a Tk graphical interface. It's designed so that it will be relatively easy to write a game that uses i a GUI or a simple text interface, depending on the player's circumstances (availability of Tk, suspicious boss, etc.). See *Note Games/Cards/Tk: Games/Cards/Tk, for more details on writing Tk games. Quick Overview of Classes ------------------------- A GC::Game stores information like what cards are in the starting deck, plus pointers to the various Cards and CardSets. A GC::Card represents one playing card. Every Card must belong to one (and only one) CardSet at every point during the game. A GC::CardSet is mostly just a set of GC::Cards. A CardSet has a unique name. Many also have short nicknames, which make it easier to write games that move cards between the sets. (See Klondike or FreeCell, for example.) There are many sorts of CardSet. The basic differentiation is Piles, for which you only access the top or bottom card (or cards) and Hands, where you might access any one of the cards in the Hand. Piles are broken up into Stacks and Queues, and every game starts with a Deck of cards (or more than one). Class Games::Cards::Game ------------------------ This class represents a certain game, like War, or Solitaire. This is necessary to store the various rules for a given game, like the ranking of the cards. (Or, for more exotic games, how many cards of what type are in the deck.) Methods: current_game Returns the current Game object. In almost every case, you'll only be working with one at a time. set_current_game(GAME) In theory, these subs let you handle multiple Games at once, as long as you set_current_game to the right one. Note that Game->new automatically sets the current Game to be that game, so in 99% of cases, you won't have to call set_current_game. new(HASHREF) creates a new game. HASHREF is a reference to a hash containing zero or more of the keys "suits" and "cards_in_suit". "suits" is a list of the suits in a deck, "cards_in_suit" is a reference to a hash whose keys are the names of the cards in one suit and whose values are the values (or ranks) of those cards. If "suits" is not given, the default suits (Clubs, Diamonds, Hearts, Spades) are used. If "cards_in_suit" is not given, the default cards (Ace, 2..10, Jack, Queen, King with values 1..13) are used. For example, war would require "Ace"=>14. get_cardset_by_name(NAME) Returns the CardSet with name NAME get_cardset_by_nickname(NAME) Returns the CardSet with nickname NAME get_card_by_truename(NAME) Returns the Card with truename NAME Games::Cards::Deck ------------------ A deck is a deck of cards. The number of cards and identities of the cards in the deck depend on the particular Game for which the deck is used. new (GAME, NAME) creates an *unshuffled* deck of cards. For each card in the deck it creates a name, suit, value, and suit value. GAME is the GC::Game this deck belongs to, and it stipulates the number of cards in the deck, etc. NAME is the name to give the deck, e.g. "Deck". Class Games::Cards::Queue ------------------------- A Queue (cf. computer science terminology, or the C++ stdlib) is a first-in first-out pile of cards. Cards are removed from the top of the pile, but new cards are added to the bottom of the pile. This might represent, say, a pile of face-down cards, like the player's hand in War. Class Games::Cards::Stack ------------------------- A stack (cf. computer science terminology, or the C++ stdlib) is a last-in first-out pile of cards. Cards are removed from the top of the pile, and new cards are also added to the top of the pile. This would usually represent a pile of cards with its top card (and perhaps all cards) face up. Class Games::Cards::Pile ------------------------ A Pile is a pile of cards. That is, it is a CardSet where we will only access the beginning or end of the set. (This may include the first N cards in the set, but we will never reference the 17'th card.) This is a super class of Queue and Stack, and those classes should be used instead, so that we know whether the cards in the pile are FIFO or LIFO. Methods: give_cards(RECEIVER, NUMBER) Transfers NUMBER cards from the donor (the object on which this method was called) to the CardSet RECEIVER. This method can used for dealing cards from a deck, giving cards to another player (Go Fish), putting cards on the table (War), or transferring a card or cards between piles in solitaire. If NUMBER is "all", then the donor gives all of its cards. Returns 1 usually. If the donor has too few cards, it returns 0 and does not transfer any cards. top_card Returns the top Card in the CardSet (or 0 if CardSet is empty) Class Games::Cards::Hand ------------------------ A Hand represents a player's hand. Most significantly, it's a CardSet which is different from a Pile because the Cards in it are unordered. We may reference any part of the CardSet, not just the top or bottom. Methods: give_a_card(RECEIVER, DESCRIPTION) Transfers Card described by DESCRIPTION from the donor (the Hand on which this method was called) to the CardSet RECEIVER. This method can used for discarding a card from a hand, e.g. If DESCRIPTION matches /^-?\d+$/, then it is the index in the cards array of the Card to give. Otherwise, DESCRIPTION is passed to Hand::index. Returns 1 usually. If the donor does not have the card, it returns 0 and does not transfer anything. move_card(DESCRIPTION, INDEX) Rearrange a Hand by putting Card described by DESCRIPTION at index INDEX. If DESCRIPTION matches /^-?\d+$/, then it is the index in the cards array of the Card to give. Otherwise, DESCRIPTION is passed to Hand::index. Returns 1 usually. If the donor does not have the card, it returns 0 and does not transfer anything. index(DESCRIPTION) Given a card description DESCRIPTION return the index of that Card in the Hand, or undef if it was not found. DESCRIPTION may be a Card or a string (like "8H" or "KC"). Class Games::Cards::CardSet --------------------------- A CardSet is just an array of cards (stored in the "cards" field). It could be a player's hand, a deck, or a discard pile, for instance. This is a super class of a number of other classes, and those subclasses should be used instead. new(GAME, NAME, NICKNAME) create a new (empty) CardSet. GAME is the Game object that this set belongs to. NAME is a unique string that e.g. can be output when you print the CardSet. Optionally, NICKNAME is a (unique!) short name that will be used to reference the set. shuffle shuffles the cards in the CardSet. Shuffling is not undoable. sort_by_value Sorts the Set by value. This and other sort routines will probably be used mostly on Hands, which are "ordered sets", but you might want to reorder a deck or something. Sorting is not undoable. sort_by_suit Sorts the Set by suit, but not by value within the suit. sort_by_suit_and_value Sorts the Set by suit, then by value within the suit. clone(GAME, NAME, NICKNAME) Create a copy of this CardSet. That is, create an object with the same class as arg0. Then make a copy of each Card in the CardSet (true copy, not a reference). arg1 is the Game that the set belongs to. arg2 is the name to give the new CardSet. arg3 (optional) is the nickname. face_down Makes a whole CardSet face down face_up Makes a whole CardSet face up print(LENGTH) Returns a string containing a printout of the Cards in the CardSet. Prints a long printout if LENGTH is "long", short if "short" (or nothing). The CardSet is printed out in reverse order, so that the top card of the set is printed first. name Returns the name of the Set nickname Returns the nickname of the Set (or undef if there is none) cards Returns a reference to the array of Cards in the set size Tells how many cards are in the set Class Games::Cards::Card ------------------------ A Card is a playing card. Methods: new(GAME, HASHREF) creates a new card. GAME is the Game this card is being created in. HASHREF references a hash with keys "suit" and "name". clone(GAME) makes a copy of the Card (not just a reference to it). print(LENGTH) returns a string with the whole card name ("King of Hearts") if LENGTH is "long", otherwise a short version ("KH"). truename Gives a unique description of this card, i.e., you're guaranteed that no other card in the Game will have the same description. suit(LENGTH) Returns the suit of the card. Returns the long version ("Diamonds") if LENGTH is "long", else a short version ("D"). color Is the card "red" or "black"? Returns the color or undef for unknown color. value Calculates the value of a card suit_value Returns the suit_value of a card (1..number of suits) is_face_up Returns true if a card is face up is_face_down Returns true if a card is face down face_up Makes a card face up face_down Makes a card face down owning_cardset Returns the CardSet which this Card is a part of set_owning_cardset(SET_OR_NAME) Makes the Card a part of a CardSet. Arg0 is either an actual CardSet ref, or the name of a CardSet. EXAMPLES ======== An implementation of Klondike (aka standard solitaire) demonstrates how to use this module in a simple game. Other card game examples are included as well. The Games::Cards README should list them all. NOTES ===== How to write your own game -------------------------- So you want to write a card game using Games::Cards (or even Games::Cards::Tk)? Great! That's what the module is for. Here are some tips about how to write a game. Steal code Laziness applies in Games::Cards just like in the rest of Perl. It will be much easier if you start with an existing game. Stack vs. Queue Think carefully about whether the Piles in your game are Stacks (LIFO) or Queues (FIFO). As a general rule, piles of cards that are usually face down will be Stacks; face up will be Queues. CardSets where you want to access specific cards (i.e., not just the first or last) will be Hands. GUI games I've tried to design Games::Cards::Tk and the games that use it so that the Tk game is very similar to the text game. This allows the most code reuse. GUI games may involve clicking, dragging, and a different way to display the game; but the underlying game is still the same. Also note that serious timewasters may prefer to use the keyboard to play GUI games. See *Note Games/Cards/Tk: Games/Cards/Tk, for more details. Public and Private ------------------ This module contains a bunch of methods. The public methods are documented here. That means any method not documented here is probably private, which means you shouldn't call it directly. There are also a bunch of classes. Most private classes are not documented here. A couple private classes are mentioned, since they have methods which public classes inherit. In that case, the privateness is mentioned. TODO ---- See the TODO file in the distribution Not TODO -------- Computer AI and GUI display were left as exercises for the reader. Then Michael Houghton wrote a Tk card game, so I guess the readers are doing their exercises. BUGS ==== You betcha. It's still alpha. test.pl doesn't work with MacPerl, because it uses backticks. However, (as far as I know) the games released with Games::Cards do work. AUTHORS ======= Amir Karger Andy Bach wrote a Free Cell port, and gets points for the first submitted game, plus some neat ideas like CardSet::clone. Michael Houghton herveus@Radix.Net wrote the initial Tk Free Cell (two days after Andy submitted his Free Cell!) I changed almost all of the code eventually, to fit in with Games::Cards::Tk, but he gave me the initial push (and code to steal). COPYRIGHT ========= Copyright (c) 1999-2000 Amir Karger LICENSE ======= This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1), Tk(1)