This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Kite/XML2PS, Next: Kite/XML/Node, Prev: Kite/Profile, Up: Module List reads an XML curve definition file and generates PostScript *********************************************************** NAME ==== Kite::XML2PS - reads an XML curve definition file and generates PostScript SYNOPSIS ======== use Kite::XML2PS; my $ps = Kite::XML2PS( filename => 'example.xml' ) || die $Kite::XML2PS::ERROR, "\n"; # return PostScript definitions for image and image path print "image definition: ", $ps->image(); print "image path: ", $ps->path(); # generate entire PostScript document with tiling, etc. print $ps->doc(); DESCRIPTION =========== Module for converting an XML file containing curve definitions (see xml/kiteparts.dtd) into PostScript. PUBLIC METHODS ============== new(\%config) ------------- Constuctor method called to create a new Kite::XML2PS object. Accepts a reference to a hash array of configuration items or a list of `name => value' pairs. The following items may be specified: filename Specifies a filename from which the XML definition should be read. This parameter is mandatory. The XML content of this document should conform to the OpenKite layout format as specified in the xml/kiteparts.dtd file (relative to the distribution root directory). title Optional parameter which can be used to set the title for the document. Setting this value will override any title defined in the XML document. regmarks Enables registration marks when set to any true value. border Specifies a border width in mm (default: 5mm). The clipping area will be inset this distance from the imageable area on the page. This is useful for printers that can't actually print to the edge of the area that they think they can. map The tiling procedure adds a small map to the top left hand corner of each page, indicating the position of the current page within the tiling set. This option can be set to 0 to disable this feature. The file specified via the filename option will be parsed and converted into PostScript definitions for the image as a whole (IMAGE) and the outline path (PATH). These can then be retrieved via the image() and path() method calls. On error, the constructor returns undef. The error message generated can be retrieved by calling the error() class method, or by examining the $Kite::XML2PS::ERROR variable. doc() ----- Returns a PostScript document containing the kite parts layed out as specified in the input file. The output is automatically tiled onto multiple pages. image() ------- Returns a PostScript string defining the image for the parts parsed from the input file. path() ------ Returns a PostScript string defining the the outline path of the parts parsed from the input file. AUTHORS ======= Simon Stapleton wrote the original xml2ps.pl utility which performs the XML -> PostScript conversion. Andy Wardley re-packaged it into a module for integration into the Kite bundle. REVISION ======== $Revision: 1.3 $ COPYRIGHT ========= Copyright (C) 2000 Simon Stapleton, Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== See also *Note Kite: Kite,, *Note Kite/PScript/Defs: Kite/PScript/Defs, and `okxml2ps' in this node.  File: pm.info, Node: Kite/XML/Node, Next: Kite/XML/Node/Kite, Prev: Kite/XML2PS, Up: Module List base class for XML parser nodes ******************************* NAME ==== Kite::XML::Node - base class for XML parser nodes SYNOPSIS ======== package Kite::XML::Node::Foo; use base qw( Kite::XML::Node ); use vars qw( $ATTRIBUTES $ELEMENTS $ERROR ); # define some attributes for the element node $ATTRIBUTES = { id => undef, # mandatory lang => 'en', # default value title => '', # optional attribute }; # define permitted child elements $ELEMENTS = { # single 'bar' child element bar => 'Kite::XML::Node::Bar', # multiple 'baz' child elements baz => 'Kite::XML::Node::Baz+', # require "Kite/XML/Node/Baz.pm" wiz => [ 'Kite::XML::Node::Wiz' => 1 ] # require some other module, accept multiple children waz => [ 'Kite::XML::Node::Waz+' => 'some/other/module.pm' ], # accept character content CDATA => 1, }; package main; my $foo = Kite::XML::Node::Foo->new(id => 12345) || die Kite::XML::Node::Foo->error(), "\n"; # set/get attributes via AUTOLOAD accessor methods... $foo->title('New Title'); print $foo->id(); # 12345 print $foo->lang(); # 'en' print $foo->title(); # 'New Title' # ...or using explicit attr() (or attribute()) method $foo->attr('title', 'New Title'); $foo->attribute('title', 'New Title'); print $foo->attr('title'); # 'New Title' # create new 'bar' child element $foo->child('bar', @some_bar_args) || die $foo->error(), "\n"; # same, using AUTOLOAD method (_must_ pass additional args) $foo->bar(@some_bar_args) || die $foo->error(), "\n"; # retrieve elements via AUTOLOAD methods (_don't_ pass any args) my $bar = $foo->bar(); # ...or using explicit elem() (or element()) method $bar = $foo->elem('bar'); $bar = $foo->element('bar'); # create multiple 'baz' children $foo->child('baz', @some_baz_args) || die $foo->error(), "\n"; $foo->child('baz', @more_baz_args) || die $foo->error(), "\n"; # multiple elements returned as (possibly empty) list reference foreach my $baz (@{ $foo->baz() }) { print $baz->some_attribute(); } # append/retrieve character content $foo->char('Character Content'); print $foo->char(); DESCRIPTION =========== This module implements a base class for objects that are constructed automatically by the Kite::XML::Parser to represented parsed XML nodes (i.e. elements). Other modules may be derived from base class to represent specific XML element nodes. package Kite::XML::Node::Foo; use base qw( Kite::XML::Node ); The base class methods examine variables in the package of the subclass to determine the permitted attributes and elements of the node. The $ERROR variable is also used for reporting class errors. use vars qw( $ATTRIBUTES $ELEMENTS $ERROR ); The $ATTRIBUTES package variable may be defined as hash reference containing valid attributes for the node. Default values may be provided. Any values left undefined are mandatory and must be provided to the new() constructor. # define some attributes for the element node $ATTRIBUTES = { id => undef, # mandatory lang => 'en', # default value title => '', # optional attribute }; The $ELEMENTS package variable may also be defined as a hash reference detailing valid child elements of the node. The keys represent the element names and the relevant values should be the package names of other Kite::XML::Node subclasses. The package name may be suffixed by a '+' to indicate that multiple child elements of this type are permitted. It may also be defined as a reference to an array containing the package name as before, followed by the name of a specific module to load (via require()) before instantiating objects of that type. This value may also be specified as '1' to indicate that the relevant module for the package should be required (i.e. change '::' to '/' and append '.pm'). The CDATA key can also be specified to contain any true to indicate that the element should also accept character content. # define permitted child elements $ELEMENTS = { # single 'bar' child element bar => 'Kite::XML::Node::Bar', # multiple 'baz' child elements baz => 'Kite::XML::Node::Baz+', # require "Kite/XML/Node/Baz.pm" wiz => [ 'Kite::XML::Node::Wiz' => 1 ] # require some other module, accept multiple children waz => [ 'Kite::XML::Node::Waz+' => 'some/other/module.pm' ], # accept character content CDATA => 1, }; The derived class can then be used to instantiate XML node objects to represent XML elements. Any mandatory attributes (i.e. $ATTRIBUTES set to undef) must be provided to the constructor. package main; my $foo = Kite::XML::Node::Foo->new(id => 12345) || die Kite::XML::Node::Foo->error(), "\n"; Any optional attributes may also be provided. Any default values specified in $ATTRIBUTES will be set if otherwise undefined. my $foo = Kite::XML::Node::Foo->new(id => 12345, title => 'test') || die Kite::XML::Node::Foo->error(), "\n"; Attribute arguments may also be specified as a hash reference for convenience. my $foo = Kite::XML::Node::Foo->new({ id => 12345, title => 'test', }) || die Kite::XML::Node::Foo->error(), "\n"; The new() constructor returns undef on failure and sets the $ERROR package variable in the subclass. This can then be inspected directly or by calling error() as a class method. my $foo = Kite::XML::Node::Foo->new(...) || die $Kite::XML::Node::Foo::ERROR; my $foo = Kite::XML::Node::Foo->new(...) || die Kite::XML::Node::Foo->error(); An AUTOLOAD method is provided to allow attributes to be accessed as methods. Arguments passed to these methods will be used to set the attribute, otherwise the attribute value will be returned. $foo->title('New Title'); print $foo->id(); # 12345 print $foo->lang(); # 'en' print $foo->title(); # 'New Title' The attr() method can also be used explicitly. This is also aliased to attribute(). $foo->attr('title', 'New Title'); $foo->attribute('title', 'New Title'); print $foo->attr('title'); # 'New Title' The child() method is used to create a new child element. The first argument specifies the element type and should be defined in $ELEMENTS. Any additional arguments are passed to the new() constructor method for that element. The instantiated child node is stored internally by the element name. Single elements (i.e. those that aren't suffixed by '+' in $ELEMENTS) may only be defined once and will generate an error (returning undef) if an attempt is made to redefine an existing element. # create new 'bar' child element $foo->child('bar', @some_bar_args) || die $foo->error(), "\n"; Multiple elements (i.e. those suffixed '+' in $ELEMENTS) may be added any number of times. $foo->child('baz', @some_baz_args) || die $foo->error(), "\n"; $foo->child('baz', @more_baz_args) || die $foo->error(), "\n"; The AUTOLOAD method can be used to return element values. Single elements return a single object (or undef), multiple elements return a reference to a list which may be empty (no children defined). my $bar = $foo->bar(); print $bar->some_attribute(); foreach my $baz (@{ $foo->baz() }) { print $baz->some_attribute(); } The elem() method can also be used explicitly. This is also aliased to element(). my $bar = $foo->elem('bar'); my $baz = $foo->element('bar'); Additional arguments may be passed to the elem() method to create a new child element. This is then delegated to the child() method. $foo->elem('bar', @some_bar_args) || die $foo->error(), "\n"; # same as $foo->child('bar', @some_bar_args) || die $foo->error(), "\n"; The AUTOLOAD method can be used in the same way. Note that both these uses require additional arguments to be passed to distinguish them from simple retrieval calls. $foo->bar(@some_bar_args) || die $foo->error(), "\n"; The char() method is provided to retrieve and update character content for the element. The CDATA item should be defined to any true value in $ELEMENTS for character data to be accepted. Note however, that any node which doesn't defined CDATA true will accept and ignore any character data consisting of nothing but whitespace. Any text data passed as the first argument is appended to the current character content buffer. The buffer is then returned. # append/retrieve character content $foo->char('Character Content'); print $foo->char(); AUTHOR ====== Andy Wardley REVISION ======== $Revision: 1.1 $ COPYRIGHT ========= Copyright (C) 2000 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== See also .  File: pm.info, Node: Kite/XML/Node/Kite, Next: Kite/XML/Parser, Prev: Kite/XML/Node, Up: Module List XML nodes to represent kite markup ********************************** NAME ==== Kite::XML::Node::Kite - XML nodes to represent kite markup SYNOPSIS ======== package Kite::XML::Node::Kite; DESCRIPTION =========== TODO AUTHOR ====== Andy Wardley REVISION ======== $Revision: 1.2 $ COPYRIGHT ========= Copyright (C) 2000 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== See also *Note Kite/XML/Node: Kite/XML/Node,, and *Note Kite/XML/Parser: Kite/XML/Parser,.  File: pm.info, Node: Kite/XML/Parser, Next: Krb4, Prev: Kite/XML/Node/Kite, Up: Module List XML parser for kite related markup ********************************** NAME ==== Kite::XML::Parser - XML parser for kite related markup SYNOPSIS ======== package Kite::XML::Parser; my $parser = Kite::XML::Parser->new(); my $kite = $parser->parsefile($filename); DESCRIPTION =========== This is a simple stack based parser built around the XML::Parser module. It parses XML text and instantiates Kite::XML::Node::* objects as it identifies various elements in the markup. These are automatically constructed into a tree (a.k.a 'grove'). A node object representing the root object is returned. AUTHOR ====== Andy Wardley REVISION ======== $Revision: 1.1 $ COPYRIGHT ========= Copyright (C) 2000 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== See also and  File: pm.info, Node: Krb4, Next: Krb5, Prev: Kite/XML/Parser, Up: Module List Perl extension for Kerberos 4 ***************************** NAME ==== Krb4 - Perl extension for Kerberos 4 SYNOPSIS ======== use Krb4; DESCRIPTION =========== Krb4 is an object oriented extension to Perl 5 which implements several user-level Kerberos 4 functions. With this module, you can create Kerberized clients and servers written in Perl. It is compatible with both AFS and MIT Kerberos. VARIABLES & FUNCTIONS --------------------- NOTE: No methods or variables are exported, so each variable and function should be preceded by 'Krb4::' error Contains the error code of the most recent Kerberos function call. get_phost(alias) Returns the instance name of the host 'alias' get_lrealm(n) Returns the nth realm of the host machine. n is zero by default. realmofhost(host) Returns the realm of the machine 'host'. mk_req(service,instance,realm,checksum) Returns a Krb4::Ticket object for the specified service, instance, and realm. It will return undef if there was an error. rd_req(ticket,service,instance,fn) Returns a Krb4::AuthDat object, which contains information obtained from the ticket, or undef upon failure. Ticket is a variable of the class Krb4::Ticket, which can be obtained from mk_req(). fn is a path to the appropriate srvtab. /etc/srvtab will be used if fn is null. get_cred(service,instance,realm) Search the caller's ticket file for a ticket for the service and instance in the given realm. Returns a Krb4::Creds object, or undef upon failure. This method can be used to extract a ticket's session key. get_key_sched(session) Returns the key schedule for the session key 'session', which can be obtained from rd_req() or get_cred(). The key schedule is a Krb4::KeySchedule object. mk_priv(in,schedule,key,sender,receiver) Encrypts the data stored in 'in' and returns the encrypted data. sender and receiver should be in standard internet format, which can be achieved using the inet_aton and sockaddr_in functions in the Socket module. rd_priv(in,schedule,key,sender,receiver) Decrypts the variable 'in' and returns the original data. Other parameters are as described in mk_priv() sendauth(options,fh,service,inst,realm,checksum,laddr,faddr,version) Obtains a ticket for the specified service, instance, and realm, and writes it to the socket 'fh'. Use recvauth to read the ticket on the server. 'laddr' is the packed network address of the client, and 'faddr' is the packed network address of the server. 'options' can be any of the following: Krb4::KOPT_DONT_MK_REQ Krb4::KOPT_DO_MUTUAL Krb4::KOPT_DONT_CANON Use Krb4::KOPT_DO_MUTUAL if you plan to do any encryption. This function returns a list containing the service ticket, the credentials, and the key schedule. recvauth(options,fh,service,inst,faddr,laddr,fn) Reads a ticket/authenticator pair from the socket 'fh'. 'options' can be set as described above. 'faddr' is the packed network address of the client, and 'laddr' is the packed network address of the server. This function returns a list containing the ticket, an AuthDat object, the key schedule, and the version string. get_pw_in_tkt(user,inst,realm,service,srealm,lifetime,password) Tries to get an initial ticket for 'user' using 'password'. This function is especially useful for verifying a user's password. See the Kerberos documentation for details. get_svc_in_tkt(user,inst,realm,service,srealm,lifetime,srvtab) Tries to get an initial ticket for 'user' using the private key stored in 'srvtab'. read_service_key(user,inst,realm,kvno,srvtab) Extracts the private key from a srvtab and returns it. Use a kvno of 0 to extract the first matching entry. dest_tkt() Destroys the ticket file, much like kdestroy. get_err_txt(n) Returns a string containing a textual description of the kerberos error number n. CLASSES & METHODS ----------------- There are four classes in the Krb4 module, Ticket, AuthDat, Creds, and KeySchedule. They are all simply abstractions of Kerberos 4 structures. You almost never need to worry about creating new objects-the functions which return these objects create them for you. The one exception is when you need to construct a Ticket object for rd_req(). See below for details. Ticket Contains a ticket for a specified service, instance, and realm. new(dat) Returns a new Ticket object containing the data in 'dat'. You must create a new Ticket object on the server side for passing to rd_req(). dat The data contained in the ticket. Looks like junk to the naked eye. length The length of the data contained in 'dat'. AuthDat Contains the contents of the AUTH_DAT structure returned by rd_req(). See below for the goodies. pname Returns the principal's name. pinst Returns the principal's instance. prealm Returns the principal's realm. session The session key. Pass this to get_key_sched() to obtain a key schedule for encryption. k_flags Flags from the ticket. checksum The checksum from the ticket. See mk_req(). life Life of the ticket. time_sec The time the ticket was issued. localtime() can convert this to a nicer format. address The address in the ticket. Useful for mutual authentication. reply Reply to send to the client (not implemented yet). Creds Contains information retreived from your ticket file. service The service name. instance The instance realm The realm session Returns the session key. Pass this to get_key_sched() to obtain a key schedule for encryption. lifetime The lifetime of the ticket. kvno The key version number. ticket The ticket itself. issue_date The date the ticket was issued. pname The name of the principal. pinst The instance of the principal. KeySchedule You don't need to fool around with this. AUTHOR ====== Jeff Horwitz SEE ALSO ======== perl(1).  File: pm.info, Node: Krb5, Next: LEGO/RCX, Prev: Krb4, Up: Module List Perl extension for Kerberos 5 ***************************** NAME ==== Krb5 - Perl extension for Kerberos 5 SYNOPSIS ======== use Krb5; Krb5::init_context(); Krb5::init_ets(); DESCRIPTION =========== Krb5 is an object oriented interface to the Kerberos 5 API. Both the implementation and documentation are nowhere near complete, and may require previous experience with Kerberos 5 programming. Most of the functions here are documented in detail in the Kerberos 5 API documentation. FUNCTIONS --------- error(n) Returns the error code from the most recent Krb5 call. If provided with an error code 'n', this function will return a textual description of the error. init_context() Initializes a context for the application. Returns a Krb5::Context object, or undef if there was an error. Should be called along with init_ets at the beginning of a script. init_ets() Initializes the Kerberos error tables. Should be called along with init_context at the beginning of a script. get_default_realm() Returns the default realm of your host. get_host_realm(host) Returns the realm of the specified host. get_krbhst(realm) Returns a list of the Kerberos servers from the specified realm. build_principal_ext(p) Not like the actual krb5_build_principal_ext. This is legacy code from Malcolm's code, which I'll probably change in future releases. In any case, it creates a 'server' principal for use in getting a TGT. Pass it the principal for which you would like a TGT. parse_name(name) Converts a string representation of a principal to a principal object. You can use this to create a principal from your username. sname_to_principal(hostname,sname,type) Generates a server principal from the given hostname, service, and type. Type can be one of the following: NT_UNKNOWN, NT_PRINCIPAL, NT_SRV_INST, NT_SRV_HST, NT_SRV_XHST, NT_UID. See the Kerberos documentation for details. cc_resolve(name) Returns a credentials cache identifier which corresponds to the given name. 'name' must be in the form TYPE:RESIDUAL. See the Kerberos documentation for more information. cc_default_name() Returns the name of the default credentials cache, which may be equivalent to KRB5CCACHE. cc_default() Returns a Krb5::Ccache object representing the default credentials cache. kt_resolve(name) Returns a Krb5::Keytab object representing the specified keytab name. get_in_tkt_with_password(client,server,password,cc) Attempt to get an initial ticket for the client. 'client' is a principal object for which you want an initial ticket. 'server' is a principal object for the service (usually krbtgt/REALM@REALM). 'password' is the password for the client, and 'cc' is a Krb5::Ccache object representing the current credentials cache. Returns a Kerberos error code. mk_req(auth_context,ap_req_options,service,hostname,in,cc) Obtains a ticket for a specified service and returns a KRB_AP_REQ message suitable for passing to rd_req. 'auth_context' is the Krb5::AuthContext object you want to use for this connection, 'ap_req_options' is an OR'ed representation of the possible options (see Kerberos docs), 'service' is the name of the service for which you want a ticket (like 'host'), hostname is the hostname of the server, 'in' can be any user-specified data that can be verified at the server end, and 'cc' is your credentials cache object. rd_req(auth_context,in,server,keytab) Parses a KRB_AP_REQ message and returns its contents in a Krb5::Ticket object. 'auth_context' is the connection's Krb5::AuthContext object, 'in' is the KRB_AP_REQ message (usually from mk_req), and server is the expected server's name for the ticket. 'keytab' is a Krb5::Keytab object for the keytab you want to use. Specify 'undef' or leave off to use the default keytab. mk_priv(auth_context,in) Encrypts 'in' using parameters specified in auth_context, and returns the encrypted data. Requires use of a replay cache. rd_priv(auth_context,in) Decrypts 'in' using parameters specified in auth_context, and returns the decrypted data. sendauth(auth_context,fh,version,client,server,options,in,in_creds,cc) Obtains and sends an authenticated ticket from a client program to a server program using the filehandle 'fh'. 'version' is an application-defined version string that recvauth compares to its own version string. 'client' is the client principal, e.g. username@REALM. 'server' is the service principal to which you are authenticating, e.g. service.hostname@REALM. The only useful option right now is AP_OPTS_MUTUAL_REQUIRED, which forces sendauth to perform mutual authentication with the server. 'in' is a string that will be received by recvauth and verified by the server-it's up to the application. 'in_creds' is not yet supported, so just use 'undef' here. 'cc' should be set to the current credentials cache. sendauth returns true on success and undefined on failure. recvauth(auth_context,fh,version,server,keytab) Receives authentication data from a client using the sendauth function through the filehandle 'fh'. 'version' is as described in the sendauth section. 'server' is the server principal to which the client will be authenticating. 'keytab' is a Krb5::Keytab object specifying the keytab to use for this service. recvauth returns a Krb5::Ticket object on success or undefined on failure. genaddrs(auth_context,fh,flags) Uses the open socket filehandle 'fh' to generate local and remote addresses for auth_context. Flags should be one of the following, depending on the type of address you want to generate (flags can be OR'ed): KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR gen_portaddr(addr,port) Generates a local port address that can be used to name a replay cache. 'addr' is a Krb5::Address object, and port is a port number in network byte order. For generateing a replay cache name, you should supply the local address of the client and the socket's local port number. Returns a Krb5::Address object containing the address. gen_replay_name(addr,string) Generate a unique replay cache name. 'addr' is a Krb5::Address object created by gen_portaddr. 'string' is used as a unique identifier for the replay cache. Returns the replay cache name. get_server_rcache(name) Returns a Krb5::Rcache object using the replay cache name 'name.' CLASSES & METHODS ----------------- Krb5::Principal Kerberos 5 princpal object. o realm Returns the realm of the principal. o type Returns the type of the principal. o data Returns a list containing the components of the principal (everything before the realm). Krb5::Ccache Kerberos 5 credentials cache object. o initialize(p) Creates/refreshes a credentials cache for the primary principal 'p'. If the cache already exists, its contents are destroyed. o get_name Returns the name of the credentials cache. o get_principal Returns the primary principal of the credentials cache. o destroy Destroys the credentials cache and releases all resources it used. Krb5::AuthContext Kerberos 5 auth_context object. o new Allocates memory for a new Krb5::AuthContext object and returns it. o setaddrs(localaddr,remoteaddr) Sets the local and remote addresses for the AuthContext object. 'localaddr' and 'remoteaddr' are Krb5::Address objects, usually of type ADDRTYPE_INET. o getaddrs() Returns a list containing the local and the remote address of the AuthContext object. o setrcache(rc) Sets the replay cache for auth_context. 'rc' is a Krb5::Rcache object generated by get_server_rcache. Krb5::Ticket Kerberos 5 ticket object. o server Returns the server stored in the ticket. o enc_part2 Returns a Krb5::EncTktPart object representation of the ticket data. See below. Krb5::EncTktPart Object representation of the krb5_enc_tkt_part structure. o client The client principal contained in the ticket. AUTHOR ====== Jeff Horwitz (jhorwitz@umich.edu) ACKNOWLEDGEMENTS ================ Based on the original work by Doug MacEachern and Malcolm Beattie. Code contributions from Scott Hutton (shutton@indiana.edu). SEE ALSO ======== perl(1), kerberos(1).  File: pm.info, Node: LEGO/RCX, Next: LISP, Prev: Krb5, Up: Module List RCX *** NAME ==== RCX SYNOPSIS ======== use LOGO::RCX; $rcx = new LEGO::RCX(); # # Turn motor A on for 10 seconds, then turn # it off # $rcx->motorOn( "A" ); sleep( 10 ); $rcx->motorOff( "A" ); DESCRIPTION =========== This module allows one to communicate with the Lego MindStorms(R) RCX brick from a workstation through the IR tower. The internals of this module are based of the *rcx.tcl* by Peter Pletcher and Laurent Demailly . I have hower made my external interface to this module OO based, and changed the way a few things are done. Without there tcl module I would have never been able to complete this in a timely manner. Thanks guys. METHODS ======= ping() or alive() Check to see if RCX is on and responding. A defined value on the return means it is alive, an undef means it is not alive. motorOn( motors ) Turns motor(s) on Motors are specifed in string format eg: "A" eg: "bc" motorOff( motors ) Turns motor(s) off Motors are specifed in string format eg: "A" eg: "bc" motorFloat( motors ) Floats motor(s) output Motors are specifed in string format eg: "A" eg: "bc" motorPower( motors, power ) Sets the motors power to value from 0-7 Motors are specifed in string format eg: "A" eg: "bc" motorDir( motors, direction Sets the motors direction which can be "forward", "reverse", or "toggle" Motors are specifed in string format eg: "A" eg: "bc" beep( sound ); Plays on of the following sounds 0 Blip 1 Beep beep 2 Downward tones 3 Upward tones 4 Low buzz 5 Fast upward tones tone( frequence, duration ) Plays a tone of a specific frequency for a length of duration frequency is in Hz and duration is in 1/100th of a second. display( display ) Selects the display for the RCX. The valid display values are: 0 Watch 1 Sensor 1 2 Sensor 2 3 Sensor 3 4 Motor A 5 Motor B 6 Motor C powerOff() Powers the RCX off. powerDelay( delay ) Sets the power off delay time for the RCX. The delay is measured in minutes. A 0 value tells the RCX to never power off, and vuture powerOff() calls will fail. program( program_number ) Sets the RCX to be on the specified program number. The valid program_number values ares 1-5. watch( hour, minutes) Sets the RCX's watch to hour house and minute mintutes. hour is 0-23 and minutes is 0-59. messageSet( message ) Set a message in the RCX. Valid message values are 0-255. start( task|name ) || start() Starts a specific task running. If no task is specified it defaults to task 0. Valid task values are 0-9. If the *loadNQClist* method has been called then you can specify a task name stop( task|name ) || stop(); Stops a specific task. If no task is specified it will stop all running tasks. If the *loadNQClist* method has been called then you can specify a task name call( subnumber|name ) Call a subroutine. If the *loadNQClist* method has been called then you can specify a subroutine name. clearTimer( timer ) This will clear the selected RCX timer. The timer values are from 0-3. clearSensor( sensor_number ) This will clear the counter associated with sensor_number sensor. setSensorType( sensor_number, sensor_type ) This will set the sensor sensor_number's type to sensor_type. The type value can be any one of the following. $SENSOR_TYPE_RAW $SENSOR_TYPE_TOUCH $SENSOR_TYPE_TEMPERATURE $SENSOR_TYPE_LIGHT $SENSOR_TYPE_ROTATION setSensorMode( sensor_number, sensor_mode, [ slope ] ) This will set the sensor sensor_number's mode to sensor_mode, with said slope. If slope is omited it defaults to 0. This is like NQC. The mode value can be any one of the following. $SENSOR_MODE_RAW $SENSOR_MODE_BOOL $SENSOR_MODE_EDGE $SENSOR_MODE_PULSE $SENSOR_MODE_PERCENT $SENSOR_MODE_CELSIUS $SENSOR_MODE_FAHRENHEIT $SENSOR_MODE_ROTATION setSensor( sensor_number, sensor_kind ) This will set the sensor sensor_number's kind to sensor_kind. This is like the NQC function *SetSensor*. The kind value can be any one of the following. $SENSOR_TOUCH $SENSOR_LIGHT $SENSOR_ROTATION $SENSOR_CELSIUS $SENSOR_FAHRENHEIT $SENSOR_PULSE $SENSOR_EDGE getReg( register ) | getVar( variable ) Get the value of a variable/register (the same thing) in the RCX. The register/variable can be from 0-31. If the *loadNQClist* method has been called then you can specify a variable name instead of a number. setReg( register, value ) | setVar( variable, value ); Set the value of a variable/register (the same thing) in the RCX to value. The register/variable can be from 0-31. If the *loadNQClist* method has been called then you can specify a variable name instead of a number. addReg( register, value ) | addVar( register, value ) Add value to a register and store back in register. subReg( register, value ) | subVar( register, value ) Subtract value from a register and store back in register. mulReg( register, value ) | mulVar( register, value ) Multiply value to a register and store back in register. divReg( register, value ) | divVar( register, value ) Divide value into a register and store back in register. andReg( register, value ) | andVar( register, value ) And value with a register and store back in register. orReg( register, value ) | orVar( register, value ) Or value with a register and store back in register. getSensor( sensor_number ) Get value of a sensor sensor_number. sensor_number can be 1-3. getSensorType( sensor_number ) Get type of a sensor sensor_number. sensor_number can be 1-3. getSensorMode( sensor_number ) Get mode of a sensor sensor_number. sensor_number can be 1-3. getSensorRaw( sensor_number ) Get raw value of a sensor sensor_number. sensor_number can be 1-3. getSensorBool( sensor_number ) Get boolean value of a sensor sensor_number. sensor_number can be 1-3. setTXRange( range ) Set the Transmit range of the RCX. Ranges are eithor "short" or "long" deleteAllTasks() Delete all tasks in current program deleteTask( task ) Delete task in current program. If the *loadNQClist* method has been called then you can specify a task name. deleteAllSubs() Delete a subroutines in current program deleteSub( sub ) Delete all subroutines in current program If the *loadNQClist* method has been called then you can specify a subroutine name. getBattery() Returns the battery voltage in volts. getVersion() Returns the version of the ROM and Firmware in the following order. ( $ROMMajor, $ROMMinor, $FIRMMajor, $FIRMMinor ); setCommTimeout( timeout ) Sets the timeout in seconds for all commands sent to the RCX. Default is 2 seconds. uploadDatalog() Returns an array of the datalog. Each item in the data log has two elements in the array. The first is the type of data being loged, and the second is the value of the data. The different types are listed as follows (taken from http://graphics.stanford.edu/~kekoa/rcx/opcodes.html 0x00-0x1f Variable value (source 0, variables 0..31) 0x20-0x23 Timer value (source 1, timers 0..3) 0x40-0x42 Sensor reading (source 9, sensors 0..2) 0x80 Clock reading (source 14) loadNQClist( nqc_list_file_name ) This method will read in a list file produced by nqc version 2.0. It parses out the variable, task, and subrouting information to allow you to use names in the related calls instead of just the numbers. This will also allow the fredom to move things around with out impacting the code. NOTES ===== I have developed this software under Linux. I know it works there. AUTHORS ======= John C. Quillan quillan@doitnow.com MODIFICATION HISTORY ==================== 01/29/2000 VER 0.5 First Version 02/04/2000 VER 0.6 Removed some commented code Added posix serial code. 02/06/2000 VER 0.7 Added the alive/ping method Added the time out for communications. Added the setCommTimeout method Added the uploadDatalog method 02/22/2000 VER 0.8 Fixed wrong named method in NQC translation Added getVersion Added clearSensor Started sensor config code Moved package RCX to Lego::RCX Made a real perl module with Makefile.PL Added div,mul,add,sub,and,or variable Added setTXRange Added deleteAllTasks and deleteAllSubs Added deleteTask and deleteSub 02/29/2000 VER 0.9 Moved package from Lego::RCX to LEGO::RCX Added setSensor, setSensorMode, setSensorType Fixed / 1000 bug in getReg. Fixed bug in pattern matches that was not catching 0x0a characters. Now a single line match. 04/16/2000 VER 1.00 Clean up source a little bit. Made README more descriptive for CPAN users. Fixed some typo in the pod documentation for the usage. Sorry for any problems this may have caused. Fixed a typo in the warning. Added a few samples to start off with  File: pm.info, Node: LISP, Next: LISP/Lambda, Prev: LEGO/RCX, Up: Module List Perl extension for blah blah blah ********************************* NAME ==== LISP - Perl extension for blah blah blah SYNOPSIS ======== use LISP; my $list = LISP->new(\@array); my $lambda = LISP->new(\&function); my $cons_cell = LISP->cons($car, $cdr); my $list = LISP::list(@array); DESCRIPTION =========== Implements Lisp-like linked-lists and functions/methods. Methods new ([ARRAYREF|CODEREF]) If given an array reference, returns a linked list with every array reference within the given array reference also expanded into another list. ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If given a subroutine reference, blesses the reference into LISP::Lamba and returns the reference. cons (CAR, CDR) Creates a new cons-cell and returns it. list (ARRAY) Like the new method, but called with an array as an argument instead of an array reference, and is more meant to be called as a function rather than a method (This could change). EXPORT ------ None by default. :all This will export cons and list from this package, listp and nilp from LISP::List, and mapcar and apply from LISP::Lambda. AUTHOR ====== Douglas Wilson, dwilson@gtemail.net SEE ALSO ======== LISP::List, LISP::Lambda, perl(1).  File: pm.info, Node: LISP/Lambda, Next: LISP/List, Prev: LISP, Up: Module List Perl extension for implementing Lisp Lambda expressions ******************************************************* NAME ==== LISP::Lambda - Perl extension for implementing Lisp Lambda expressions SYNOPSIS ======== use LISP::Lambda; my $lambda = LISP::Lambda->new(\&sub); $lambda->mapcar(@lists) $lambda->apply($list); DESCRIPTION =========== Lambda expressions are Lisp's version of anonymous subroutines, and may be blessed into this package so that you can use them or the provided 'meta-methods' in an object oriented way. If you want to want to use them as regular functions, you may export them. Any reference to lists here refers to linked lists ala Lisp, and not to perl lists/arrays. Methods ------- mapcar(FUNCTION, LISTS) mapcar applies the FUNCTION to the list formed by the first element of each list, then to the second, etc., up to the length of the shortest list, and returns a list of the results. $list = LISP->new([[a],[b],[c],[d]]); # ((a) (b) (c) (d)) $car = $list->can('car'); $cars = $car->mapcar($list); print $cars->string; # Prints (a b c d); $list1 = LISP->new([qw(1 2 3)]]); $list2 = LISP->new([qw(4 5 6)]]); $lister = $list1->can('list'); $list3 = mapcar($lister, $list1, $list2); print $list3->string # Prints ((1 4) (2 5) (3 6)) apply(FUNCTION, LIST) apply returns the result of executing FUNCTION using the subnodes of LIST as arguments. $list = LISP->new([qw(1 2 3)]); $totaller = sub { my $total=0; $total += $_ for @_; $total }; print apply($totaller, $list); # Prints 6 $inc = LISP->new(sub { map {$_ + 1} @_ }); my @ary = $inc->apply($list); print "@ary"; # Prints 2 3 4 EXPORT ------ :all exports methods mapcar and apply, and each may be exported individually. AUTHOR ====== Douglas Wilson, dwilson@gtemail.net SEE ALSO ======== perl(1).  File: pm.info, Node: LISP/List, Next: LWP, Prev: LISP/Lambda, Up: Module List Perl extension for implementing linked lists as in Lisp ******************************************************* NAME ==== LISP::List - Perl extension for implementing linked lists as in Lisp SYNOPSIS ======== use LISP::List; $list = LISP->new([qw(1 2 3)]); $car = $list->car; $cdr = $list->cdr; $caar = $list->cddr; $cddr = $list->cddr; $cadr = $list->cadr; # etc. $list->rplaca($car); $list->rplacd($cdr); @sub_nodes = $list->sub_nodes; $rev_list = $list->reverse; $new_list = $list->append(@lists); $scalar = $list->pop; $list->push($element); $last_list = $list->last; $length = $list->length; $is_a_list = $list->listp; $is_empty_list = $list->nilp; $new_list = $list->mapcar($code_ref, [@more_lists]); $result = $list->apply($code_ref); $string = $list->string; DESCRIPTION =========== This is an implementation of linked lists, with Lisp-like functionality. Any reference to lists here refers to Lisp-like linked lists, while @variables in perl will be called arrays. Explanation Here is a brief description of linked lists in Lisp. -------------------------------------------------------------------- (1 2 3 4) is short hand for: (1 . (2 . (3 . (4 . NIL)))) which graphically represented as: .--.--.--.--NIL | | | | 1 2 3 4 The list 'starts' with the node in the upper-left corner. The car of a list node is the element below a node, and the cdr of a node is the element to the right of a node. In a 'true' list, the cdr of a list is always a list, and the 'last' cdr is NIL, which represents the empty list. List nodes are also called 'cons' cells. Cons cells do not have to have a list (NIL or otherwise) as their cdr. Things referred to as lists below do not always refer to a 'true' list necessarily, and may also apply to cons cells. Methods ------- new (ARRAY_REF) Calling LISP::List->new($array_ref), or LISP->new($array_ref) for short, will create a new linked list of the elements of $array_ref, with each array reference within $array_ref itself becoming a linked list. car Returns the car of a list. cdr Returns the cdr of a list. caar, cddr, cadr, etc. E.g. cadr returns the car of the cdr of a list, any method matching /c[ad][ad]+r/ is autoloaded to return the appropriate chaining of car and cdr. sub_nodes Returns all of the car's of the top-level nodes of a list in an array. reverse Returns a copy of the top-level nodes of a list in reverse. append (LISTS) Copies the top-level nodes of all but the last list and appends all of the copies, including the last list, together into a new list. pop Returns the car of a list and sets the list to the cdr of itself. push (ELEMENT) Creates a new cons cell with the given element as its car, and the list as its cdr, and sets the list to the new cons cell. last Returns the last non-NIL top-level node of the LIST. length Returns the number of non-NIL top-level nodes of a list. listp Returns true if its argument is a list (This method may be exported and used as a function). nilp Returns true if its argument is NIL (This method may be exported and used as a function). string Returns a string representation of a list. apply (CODEREF) Same as apply in LISP::Lambda but takes the arguments in a different order, so the list is the object instead of the subroutine. mapcar (CODEREF, [@MORE_LISTS]) Same as mapcar in LISP::Lambda but takes arguments in a different order, so the list is the object instead of the subroutine. EXPORT ------ Nothing exported by default. :all exports the methods/functions listp and nilp so they can be used as functions on values other than lists. AUTHOR ====== Douglas Wilson, dwilson@gtemail.net SEE ALSO ======== perl(1).  File: pm.info, Node: LWP, Next: LWP/AuthenAgent, Prev: LISP/List, Up: Module List Library for WWW access in Perl ****************************** NAME ==== LWP - Library for WWW access in Perl SYNOPSIS ======== use LWP; print "This is libwww-perl-$LWP::VERSION\n"; DESCRIPTION =========== Libwww-perl is a collection of Perl modules which provides a simple and consistent application programming interface (API) to the World-Wide Web. The main focus of the library is to provide classes and functions that allow you to write WWW clients, thus libwww-perl is a WWW client library. The library also contain modules that are of more general use. Most modules in this library are object oriented. The user agent, requests sent and responses received from the WWW server are all represented by objects. This makes a simple and powerful interface to these services. The interface should be easy to extend and customize for your needs. The main features of the library are: * Contains various reusable components (modules) that can be used separately or together. * Provides an object oriented model of HTTP-style communication. Within this framework we currently support access to http, https, gopher, ftp, news, file, and mailto resources. * Provides a full object oriented interface or a very simple procedural interface. * Supports the basic and digest authorization schemes. * Supports transparent redirect handling. * Supports access through proxy servers. * Provides parser for `robots.txt' files and a framework for constructing robots. * Cooperates with Tk. A simple Tk-based GUI browser called 'tkweb' is distributed with the Tk extension for perl. * Implements HTTP content negotiation algorithm that can be used both in protocol modules and in server scripts (like CGI scripts). * Supports HTTP cookies. * A simple command line client application called `lwp-request'. HTTP STYLE COMMUNICATION ======================== The libwww-perl library is based on HTTP style communication. This section tries to describe what that means. Let us start with this quote from the HTTP specification document : The HTTP protocol is based on a request/response paradigm. A client establishes a connection with a server and sends a request to the server in the form of a request method, URI, and protocol version, followed by a MIME-like message containing request modifiers, client information, and possible body content. The server responds with a status line, including the message's protocol version and a success or error code, followed by a MIME-like message containing server information, entity meta-information, and possible body content. What this means to libwww-perl is that communication always take place through these steps: First a request object is created and configured. This object is then passed to a server and we get a response object in return that we can examine. A request is always independent of any previous requests, i.e. the service is stateless. The same simple model is used for any kind of service we want to access. For example, if we want to fetch a document from a remote file server, then we send it a request that contains a name for that document and the response will contain the document itself. If we access a search engine, then the content of the request will contain the query parameters and the response will contain the query result. If we want to send a mail message to somebody then we send a request object which contains our message to the mail server and the response object will contain an acknowledgment that tells us that the message has been accepted and will be forwarded to the recipient(s). It is as simple as that! The Request Object ------------------ The libwww-perl request object has the class name HTTP::Request. The fact that the class name uses `HTTP::' as a prefix only implies that we use the HTTP model of communication. It does not limit the kind of services we can try to pass this request to. For instance, we will send HTTP::Requests both to ftp and gopher servers, as well as to the local file system. The main attributes of the request objects are: * The method is a short string that tells what kind of request this is. The most used methods are GET, PUT, POST and HEAD. * The url is a string denoting the protocol, server and the name of the "document" we want to access. The url might also encode various other parameters. * The headers contain additional information about the request and can also used to describe the content. The headers are a set of keyword/value pairs. * The content is an arbitrary amount of data. The Response Object ------------------- The libwww-perl response object has the class name `HTTP::Response'. The main attributes of objects of this class are: * The code is a numerical value that indicates the overall outcome of the request. * The message is a short, human readable string that corresponds to the code. * The headers contain additional information about the response and describe the content. * The content is an arbitrary amount of data. Since we don't want to handle all possible code values directly in our programs, a libwww-perl response object has methods that can be used to query what kind of response this is. The most commonly used response classification methods are: is_success() The request was was successfully received, understood or accepted. is_error() The request failed. The server or the resource might not be available, access to the resource might be denied or other things might have failed for some reason. The User Agent -------------- Let us assume that we have created a request object. What do we actually do with it in order to receive a response? The answer is that you pass it to a *user agent* object and this object takes care of all the things that need to be done (like low-level communication and error handling) and returns a response object. The user agent represents your application on the network and provides you with an interface that can accept *requests* and return *responses*. The user agent is an interface layer between your application code and the network. Through this interface you are able to access the various servers on the network. The libwww-perl class name for the user agent is `LWP::UserAgent'. Every libwww-perl application that wants to communicate should create at least one object of this class. The main method provided by this object is request(). This method takes an HTTP::Request object as argument and (eventually) returns a `HTTP::Response' object. The user agent has many other attributes that let you configure how it will interact with the network and with your application. * The timeout specifies how much time we give remote servers to respond before the library disconnects and creates an internal timeout response. * The *agent* specifies the name that your application should use when it presents itself on the network. * The from attribute can be set to the e-mail address of the person responsible for running the application. If this is set, then the address will be sent to the servers with every request. * The *parse_head* specifies whether we should initialize response headers from the section of HTML documents. * The proxy and *no_proxy* attributes specify if and when to go through a proxy server. * The *credentials* provide a way to set up user names and passwords needed to access certain services. Many applications want even more control over how they interact with the network and they get this by sub-classing `LWP::UserAgent'. The library includes a sub-class, LWP::RobotUA, for robot applications. An Example ---------- This example shows how the user agent, a request and a response are represented in actual perl code: # Create a user agent object use LWP::UserAgent; $ua = new LWP::UserAgent; $ua->agent("AgentName/0.1 " . $ua->agent); # Create a request my $req = new HTTP::Request POST => 'http://www.perl.com/cgi-bin/BugGlimpse'; $req->content_type('application/x-www-form-urlencoded'); $req->content('match=www&errors=0'); # Pass request to the user agent and get a response back my $res = $ua->request($req); # Check the outcome of the response if ($res->is_success) { print $res->content; } else { print "Bad luck this time\n"; } The $ua is created once when the application starts up. New request objects should normally created for each request sent. NETWORK SUPPORT =============== This section discusses the various protocol schemes and the HTTP style methods that headers may be used for each. For all requests, a "User-Agent" header is added and initialized from the $ua->agent attribute before the request is handed to the network layer. In the same way, a "From" header is initialized from the $ua->from attribute. For all responses, the library adds a header called "Client-Date". This header holds the time when the response was received by your application. The format and semantics of the header are the same as the server created "Date" header. You may also encounter other "Client-XXX" headers. They are all generated by the library internally and are not received from the servers. HTTP Requests ------------- HTTP requests are just handed off to an HTTP server and it decides what happens. Few servers implement methods beside the usual "GET", "HEAD", "POST" and "PUT", but CGI-scripts may implement any method they like. If the server is not available then the library will generate an internal error response. The library automatically adds a "Host" and a "Content-Length" header to the HTTP request before it is sent over the network. For GET request you might want to add the "If-Modified-Since" header to make the request conditional. For POST request you should add the "Content-Type" header. When you try to emulate HTML
handling you should usually let the value of the "Content-Type" header be "application/x-www-form-urlencoded". See *Note Lwpcook: lwpcook, for examples of this. The libwww-perl HTTP implementation currently support the HTTP/1.0 protocol. HTTP/0.9 servers are also handled correctly. The library allows you to access proxy server through HTTP. This means that you can set up the library to forward all types of request through the HTTP protocol module. See *Note LWP/UserAgent: LWP/UserAgent, for documentation of this. HTTPS Requests -------------- HTTPS requests are HTTP requests over an encrypted network connection using the SSL protocol developed by Netscape. Everything about HTTP requests above also apply to HTTPS requests. In addition the library will add the headers "Client-SSL-Cipher", "Client-SSL-Cert-Subject" and "Client-SSL-Cert-Issuer" to the response. These headers denote the encryption method used and the name of the server owner. The request can contain the header "If-SSL-Cert-Subject" in order to make the request conditional on the content of the server certificate. If the certificate subject does not match, no request is sent to the server and an internally generated error response is returned. The value of the "If-SSL-Cert-Subject" header is interpreted as a Perl regular expression. FTP Requests ------------ The library currently supports GET, HEAD and PUT requests. GET retrieves a file or a directory listing from an FTP server. PUT stores a file on a ftp server. You can specify a ftp account for servers that want this in addition to user name and password. This is specified by including an "Account" header in the request. User name/password can be specified using basic authorization or be encoded in the URL. Failed logins return an UNAUTHORIZED response with "WWW-Authenticate: Basic" and can be treated like basic authorization for HTTP. The library supports ftp ASCII transfer mode by specifying the "type=a" parameter in the URL. Directory listings are by default returned unprocessed (as returned from the ftp server) with the content media type reported to be "text/ftp-dir-listing". The `File::Listing' module provides methods for parsing of these directory listing. The ftp module is also able to convert directory listings to HTML and this can be requested via the standard HTTP content negotiation mechanisms (add an "Accept: text/html" header in the request if you want this). For normal file retrievals, the "Content-Type" is guessed based on the file name suffix. See *Note LWP/MediaTypes: LWP/MediaTypes,. The "If-Modified-Since" request header works for servers that implement the MDTM command. It will probably not work for directory listings though. Example: $req = HTTP::Request->new(GET => 'ftp://me:passwd@ftp.some.where.com/'); $req->header(Accept => "text/html, */*;q=0.1"); News Requests ------------- Access to the USENET News system is implemented through the NNTP protocol. The name of the news server is obtained from the NNTP_SERVER environment variable and defaults to "news". It is not possible to specify the hostname of the NNTP server in news: URLs. The library supports GET and HEAD to retrieve news articles through the NNTP protocol. You can also post articles to newsgroups by using (surprise!) the POST method. GET on newsgroups is not implemented yet. Examples: $req = HTTP::Request->new(GET => 'news:abc1234@a.sn.no'); $req = HTTP::Request->new(POST => 'news:comp.lang.perl.test'); $req->header(Subject => 'This is a test', From => 'me@some.where.org'); $req->content(<new(GET => 'gopher://gopher.sn.no/'); File Request ------------ The library supports GET and HEAD methods for file requests. The "If-Modified-Since" header is supported. All other headers are ignored. The host component of the file URL must be empty or set to "localhost". Any other host value will be treated as an error. Directories are always converted to an HTML document. For normal files, the "Content-Type" and "Content-Encoding" in the response are guessed based on the file suffix. Example: $req = HTTP::Request->new(GET => 'file:/etc/passwd'); Mailto Request -------------- You can send (aka "POST") mail messages using the library. All headers specified for the request are passed on to the mail system. The "To" header is initialized from the mail address in the URL. Example: $req = HTTP::Request->new(POST => 'mailto:libwww@perl.ord'); $req->header(Subject => "subscribe"); $req->content("Please subscribe me to the libwww-perl mailing list!\n"); OVERVIEW OF CLASSES AND PACKAGES ================================ This table should give you a quick overview of the classes provided by the library. Indentation shows class inheritance. LWP::MemberMixin -- Access to member variables of Perl5 classes LWP::UserAgent -- WWW user agent class LWP::RobotUA -- When developing a robot applications LWP::Protocol -- Interface to various protocol schemes LWP::Protocol::http -- http:// access LWP::Protocol::file -- file:// access LWP::Protocol::ftp -- ftp:// access ... LWP::Authen::Basic -- Handle 401 and 407 responses LWP::Authen::Digest HTTP::Headers -- MIME/RFC822 style header (used by HTTP::Message) HTTP::Message -- HTTP style message HTTP::Request -- HTTP request HTTP::Response -- HTTP response HTTP::Daemon -- A HTTP server class WWW::RobotRules -- Parse robots.txt files WWW::RobotRules::AnyDBM_File -- Persistent RobotRules The following modules provide various functions and definitions. LWP -- This file. Library version number and documentation. LWP::MediaTypes -- MIME types configuration (text/html etc.) LWP::Debug -- Debug logging module LWP::Simple -- Simplified procedural interface for common functions HTTP::Status -- HTTP status code (200 OK etc) HTTP::Date -- Date parsing module for HTTP date formats HTTP::Negotiate -- HTTP content negotiation calculation File::Listing -- Parse directory listings MORE DOCUMENTATION ================== All modules contain detailed information on the interfaces they provide. The *lwpcook* manpage is the libwww-perl cookbook that contain examples of typical usage of the library. You might want to take a look at how the scripts `lwp-request', `lwp-rget' and `lwp-mirror' are implemented. BUGS ==== The library can not handle multiple simultaneous requests yet. Also, check out what's left in the TODO file. ACKNOWLEDGEMENTS ================ This package owes a lot in motivation, design, and code, to the libwww-perl library for Perl 4, maintained by Roy Fielding . That package used work from Alberto Accomazzi, James Casey, Brooks Cutter, Martijn Koster, Oscar Nierstrasz, Mel Melchner, Gertjan van Oosten, Jared Rhine, Jack Shirazi, Gene Spafford, Marc VanHeyningen, Steven E. Brenner, Marion Hakanson, Waldemar Kebsch, Tony Sanders, and Larry Wall; see the libwww-perl-0.40 library for details. The primary architect for this Perl 5 library is Martijn Koster and Gisle Aas, with lots of help from Graham Barr, Tim Bunce, Andreas Koenig, Jared Rhine, and Jack Shirazi. COPYRIGHT ========= Copyright 1995-2000, Gisle Aas Copyright 1995, Martijn Koster This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AVAILABILITY ============ The latest version of this library is likely to be available from CPAN as well as: http://www.linpro.no/lwp/ The best place to discuss this code is on the mailing list.