This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: LWP/Protocol, Next: LWP/Protocol/bbs, Prev: LWP/ParallelUA, Up: Module List Base class for LWP protocols **************************** NAME ==== LWP::Protocol - Base class for LWP protocols SYNOPSIS ======== package LWP::Protocol::foo; require LWP::Protocol; @ISA=qw(LWP::Protocol); DESCRIPTION =========== This class is used a the base class for all protocol implementations supported by the LWP library. When creating an instance of this class using `LWP::Protocol::create($url)', and you get an initialised subclass appropriate for that access method. In other words, the LWP::Protocol::create() function calls the constructor for one of its subclasses. All derived LWP::Protocol classes need to override the request() method which is used to service a request. The overridden method can make use of the collect() function to collect together chunks of data as it is received. The following methods and functions are provided: $prot = LWP::Protocol->new() The LWP::Protocol constructor is inherited by subclasses. As this is a virtual base class this method should not be called directly. $prot = LWP::Protocol::create($url) Create an object of the class implementing the protocol to handle the given scheme. This is a function, not a method. It is more an object factory than a constructor. This is the function user agents should use to access protocols. $class = LWP::Protocol::implementor($scheme, [$class]) Get and/or set implementor class for a scheme. Returns " if the specified scheme is not supported. $prot->request(...) $response = $protocol->request($request, $proxy, undef); $response = $protocol->request($request, $proxy, '/tmp/sss'); $response = $protocol->request($request, $proxy, \&callback, 1024); Dispactches a request over the protocol, and returns a response object. This method needs to be overridden in subclasses. Referer to *Note LWP/UserAgent: LWP/UserAgent, for description of the arguments. $prot->timeout($seconds) Get and set the timeout value in seconds $prot->parse_head($yesno) Should we initialize response headers from the section of HTML documents. $prot->collect($arg, $response, $collector) Called to collect the content of a request, and process it appropriately into a scalar, file, or by calling a callback. If $arg is undefined, then the content is stored within the $response. If $arg is a simple scalar, then $arg is interpreted as a file name and the content is written to this file. If $arg is a reference to a routine, then content is passed to this routine. The $collector is a routine that will be called and which is reponsible for returning pieces (as ref to scalar) of the content to process. The $collector signals EOF by returning a reference to an empty sting. The return value from collect() is the $response object reference. Note: We will only use the callback or file argument if $response->is_success(). This avoids sendig content data for redirects and authentization responses to the callback which would be confusing. $prot->collect_once($arg, $response, $content) Can be called when the whole response content is available as $content. This will invoke collect() with a collector callback that returns a reference to $content the first time and an empty string the next. SEE ALSO ======== Inspect the `LWP/Protocol/file.pm' and `LWP/Protocol/http.pm' files for examples of usage. COPYRIGHT ========= Copyright 1995-2000 Gisle Aas. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: LWP/Protocol/bbs, Next: LWP/RobotPUA, Prev: LWP/Protocol, Up: Module List BBS/RPC support for LWP *********************** NAME ==== LWP::Protocol::bbs - BBS/RPC support for LWP SYNOPSIS ======== # start daemon % bbscomd MAPLE2 /srv/bbs # fetch some property % lwp-download bbs://localhost/boards/sysop/articles/1/body DESCRIPTION =========== This is an attempt to combine raw BBS fetch with LWP protocol, intended to be used as the bridge to foreign renderes. It's still in early alpha stage, and the interface remains undecided as of now. COPYRIGHT ========= Copyright 2001 by Autrijus Tang . All rights reserved. You can redistribute and/or modify this module under the same terms as Perl itself.  File: pm.info, Node: LWP/RobotPUA, Next: LWP/RobotUA, Prev: LWP/Protocol/bbs, Up: Module List Parallel LWP::RobotUA ********************* NAME ==== LWP::RobotPUA - Parallel LWP::RobotUA SYNOPSIS ======== require LWP::RobotPUA; $ua = new LWP::RobotPUA 'my-robot/0.1', 'me@foo.com'; (see description of LWP::Parallel::RobotUA) DESCRIPTION =========== RobotPUA is a simple frontend to the LWP::Parallel::RobotUA module. It is here in order to maintain the compatibility with previous releases. However, in order to prevent the previous need for changing the original LWP sources, all extension files have been moved to the LWP::Parallel subtree. If you start from scratch, maybe you should start using LWP::Parallel and its submodules directly. See the *Note LWP/Parallel/RobotUA: LWP/Parallel/RobotUA, for the documentation on this module. AUTHOR ====== Marc Langheinrich, marclang@cs.washington.edu SEE ALSO ======== *Note LWP/Parallel/RobotUA: LWP/Parallel/RobotUA,, *Note LWP/Parallel/UserAgent: LWP/Parallel/UserAgent,, *Note LWP/RobotUA: LWP/RobotUA, COPYRIGHT ========= Copyright 1997-2001 Marc Langheinrich. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: LWP/RobotUA, Next: LWP/SecureSocket, Prev: LWP/RobotPUA, Up: Module List A class for Web Robots ********************** NAME ==== LWP::RobotUA - A class for Web Robots SYNOPSIS ======== require LWP::RobotUA; $ua = new LWP::RobotUA 'my-robot/0.1', 'me@foo.com'; $ua->delay(10); # be very nice, go slowly ... # just use it just like a normal LWP::UserAgent $res = $ua->request($req); DESCRIPTION =========== This class implements a user agent that is suitable for robot applications. Robots should be nice to the servers they visit. They should consult the `/robots.txt' file to ensure that they are welcomed and they should not make requests too frequently. But, before you consider writing a robot take a look at . When you use a LWP::RobotUA as your user agent, then you do not really have to think about these things yourself. Just send requests as you do when you are using a normal *LWP::UserAgent* and this special agent will make sure you are nice. METHODS ======= The LWP::RobotUA is a sub-class of LWP::UserAgent and implements the same methods. In addition the following methods are provided: $ua = LWP::RobotUA->new($agent_name, $from, [$rules]) Your robot's name and the mail address of the human responsible for the robot (i.e. you) are required by the constructor. Optionally it allows you to specify the *WWW::RobotRules* object to use. $ua->delay([$minutes]) Set the minimum delay between requests to the same server. The default is 1 minute. $ua->use_sleep([$boolean]) Get/set a value indicating whether the UA should sleep() if requests arrive too fast (before $ua->delay minutes has passed). The default is TRUE. If this value is FALSE then an internal SERVICE_UNAVAILABLE response will be generated. It will have an Retry-After header that indicates when it is OK to send another request to this server. $ua->rules([$rules]) Set/get which *WWW::RobotRules* object to use. $ua->no_visits($netloc) Returns the number of documents fetched from this server host. Yes I know, this method should probably have been named num_visits() or something like that. :-( $ua->host_wait($netloc) Returns the number of seconds (from now) you must wait before you can make a new request to this host. $ua->as_string Returns a string that describes the state of the UA. Mainly useful for debugging. SEE ALSO ======== *Note LWP/UserAgent: LWP/UserAgent,, *Note WWW/RobotRules: WWW/RobotRules, COPYRIGHT ========= Copyright 1996-2000 Gisle Aas. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: LWP/SecureSocket, Next: LWP/Simple, Prev: LWP/RobotUA, Up: Module List SSL TCP/IP socket interface *************************** NAME ==== LWP::SecureSocket - SSL TCP/IP socket interface SYNOPSIS ======== $socket = new LWP::SecureSocket; $socket->connect('localhost', 7); # echo $quote = 'I dunno, I dream in Perl sometimes...'; $socket->write("$quote\n"); $socket->read_until("\n", \$buffer); $socket->read(\$buffer); $socket = undef; # close DESCRIPTION =========== *Beware:* New code should not use this depreciated module. This class implements SSL TCP/IP sockets. It groups socket generation, TCP address manipulation and buffered reading. Errors are handled by dying (throws exceptions). The following methods are provided: $sock = new LWP::SecureSocket() Constructs a new socket object. $sock->connect($host, $port) Connect the socket to given host and port. $sock->shutdown() Shuts down the connection. $sock->bind($host, $port) Binds a name to the socket. $sock->listen($queuesize) Set up listen queue for socket. $sock->accept($timeout) Accepts a new connection. Returns a new LWP::SecureSocket object if successful. Timeout not implemented yet. would require modifying new, and not necessary for app, so I\'m not bothering to modify. Might work anyways, though. $sock->getsockname() Returns a 2 element array ($host, $port) $sock->read_until($delim, $data_ref, $size, $timeout) Reads data from the socket, up to a delimiter specified by a regular expression. If $delim is undefined all data is read. If $size is defined, data will be read internally in chunks of $size bytes. This does not mean that we will return the data when size bytes are read. Note that $delim is discarded from the data returned. $sock->read($bufref, [$size, $timeout]) Reads data of the socket. Not more than $size bytes. Might return less if the data is available. Dies on timeout. $sock->pushback($data) Put data back into the socket. Data will returned next time you read(). Can be used if you find out that you have read too much. $sock->write($data, [$timeout]) Write data to socket. The $data argument might be a scalar or code. If data is a reference to a subroutine, then we will call this routine to obtain the data to be written. The routine will be called until it returns undef or empty data. Data might be returned from the callback as a scalar or as a reference to a scalar. Write returns the number of bytes written to the socket. $sock->_getaddress($h, $p) Given a host and a port, it will return the address (sockaddr_in) suitable as the name argument for connect() or bind(). Might return several addresses in array context if the hostname is bound to several IP addresses. AUTHOR ====== Derived by Joshua Kronengold from Socket.pm and SSLeay  File: pm.info, Node: LWP/Simple, Next: LWP/Sink, Prev: LWP/SecureSocket, Up: Module List Procedural LWP interface ************************ NAME ==== get, head, getprint, getstore, mirror - Procedural LWP interface SYNOPSIS ======== perl -MLWP::Simple -e 'getprint "http://www.sn.no"' use LWP::Simple; $content = get("http://www.sn.no/") if (mirror("http://www.sn.no/", "foo") == RC_NOT_MODIFIED) { ... } if (is_success(getprint("http://www.sn.no/"))) { ... } DESCRIPTION =========== This interface is intended for those who want a simplified view of the libwww-perl library. It should also be suitable for one-liners. If you need more control or access to the header fields in the requests sent and responses received you should use the full object oriented interface provided by the `LWP::UserAgent' module. The following functions are provided (and exported) by this module: get($url) The get() function will fetch the document identified by the given URL and return it. It returns undef if it fails. The $url argument can be either a simple string or a reference to a URI object. You will not be able to examine the response code or response headers (like 'Content-Type') when you are accessing the web using this function. If you need that information you should use the full OO interface (see *Note LWP/UserAgent: LWP/UserAgent,). head($url) Get document headers. Returns the following 5 values if successful: ($content_type, $document_length, $modified_time, $expires, $server) Returns an empty list if it fails. In scalar context returns TRUE if successful. getprint($url) Get and print a document identified by a URL. The document is printed to STDOUT as data is received from the network. If the request fails, then the status code and message are printed on STDERR. The return value is the HTTP response code. getstore($url, $file) Gets a document identified by a URL and stores it in the file. The return value is the HTTP response code. mirror($url, $file) Get and store a document identified by a URL, using *If-modified-since*, and checking the *Content-Length*. Returns the HTTP response code. This module also exports the HTTP::Status constants and procedures. These can be used when you check the response code from getprint(), getstore() and mirror(). The constants are: RC_CONTINUE RC_SWITCHING_PROTOCOLS RC_OK RC_CREATED RC_ACCEPTED RC_NON_AUTHORITATIVE_INFORMATION RC_NO_CONTENT RC_RESET_CONTENT RC_PARTIAL_CONTENT RC_MULTIPLE_CHOICES RC_MOVED_PERMANENTLY RC_MOVED_TEMPORARILY RC_SEE_OTHER RC_NOT_MODIFIED RC_USE_PROXY RC_BAD_REQUEST RC_UNAUTHORIZED RC_PAYMENT_REQUIRED RC_FORBIDDEN RC_NOT_FOUND RC_METHOD_NOT_ALLOWED RC_NOT_ACCEPTABLE RC_PROXY_AUTHENTICATION_REQUIRED RC_REQUEST_TIMEOUT RC_CONFLICT RC_GONE RC_LENGTH_REQUIRED RC_PRECONDITION_FAILED RC_REQUEST_ENTITY_TOO_LARGE RC_REQUEST_URI_TOO_LARGE RC_UNSUPPORTED_MEDIA_TYPE RC_INTERNAL_SERVER_ERROR RC_NOT_IMPLEMENTED RC_BAD_GATEWAY RC_SERVICE_UNAVAILABLE RC_GATEWAY_TIMEOUT RC_HTTP_VERSION_NOT_SUPPORTED The HTTP::Status classification functions are: is_success($rc) True if response code indicated a successful request. is_error($rc) True if response code indicated that an error occured. The module will also export the LWP::UserAgent object as $ua if you ask for it explicitly. The user agent created by this module will identify itself as "LWP::Simple/#.##" (where "#.##" is the libwww-perl version number) and will initialize its proxy defaults from the environment (by calling $ua->env_proxy). SEE ALSO ======== *Note LWP: LWP,, *Note LWP/UserAgent: LWP/UserAgent,, *Note HTTP/Status: HTTP/Status,, `lwp-request' in this node, `lwp-mirror' in this node  File: pm.info, Node: LWP/Sink, Next: LWP/Socket, Prev: LWP/Simple, Up: Module List Something that receive data *************************** NAME ==== LWP::Sink - Something that receive data SYNOPSIS ======== require LWP::Sink; @ISA=qw(LWP::Sink); DESCRIPTION =========== The *LWP::Sink* class is an abstraction similar to writeable files. You can send data to it. Different variations of sinks are available that all conform to this simple interface: $s = LWP::Sink::Foo->new The object constructor. The *LWP::Sink* class is abstract, so you will create some subclass normally. $s->put($data) Data is given to a sink by calling the put() method with suitable sized chunkes of data. The return value from $s->put will be a reference to the object itself. $s->flush Buffered data should be processed/sent off. $s->close Invoking the close() method signals that the last chunk of data has been put()ed. Resources associated with the sink can now be freed. One important class of sinks are those that transform data in some way. These will be subclasses of *LWP::Sink::_Pipe* which means that they have a attribute called *sink* that reference the sink that will received data after processing. By convention call transformation sink classes have all lowercase names within the LWP::Sink::* namespace. They also have variations suffixed with ::encode and ::decode that performs the transformations forwards or backwards. BUGS ==== Perhaps *LWP::Sink* should provide an interface to load sink subclasses on demand and return references to them. Similar to how URI works. COPYRIGHT ========= Copyright 1998, Gisle Aas This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: LWP/Socket, Next: LWP/TkIO, Prev: LWP/Sink, Up: Module List TCP/IP socket interface *********************** NAME ==== LWP::Socket - TCP/IP socket interface SYNOPSIS ======== $socket = new LWP::Socket; $socket->connect('localhost', 7); # echo $quote = 'I dunno, I dream in Perl sometimes...'; $socket->write("$quote\n"); $socket->read_until("\n", \$buffer); $socket->read(\$buffer); $socket = undef; # close DESCRIPTION =========== *Beware:* New code should not use this module. The IO::Socket::INET module provide the standard Perl interface to OO Internet sockets. Even LWP is now rewritten to use IO::Socket::INET throughout. This class implements TCP/IP sockets. It groups socket generation, TCP address manipulation and buffered reading. Errors are handled by dying (throws exceptions). Running this module standalone executes a self test which requires localhost to serve chargen and echo protocols. The following methods are available: $sock = new LWP::Socket() Constructs a new socket object. $sock->connect($host, $port) Connect the socket to given host and port. $sock->shutdown() Shuts down the connection. $sock->bind($host, $port) Binds a name to the socket. $sock->listen($queuesize) Set up listen queue for socket. $sock->accept($timeout) Accepts a new connection. Returns a new LWP::Socket object if successful. Timeout not implemented yet. $sock->getsockname() Returns a 2 element array ($host, $port) $sock->read_until($delim, $data_ref, $size, $timeout) Reads data from the socket, up to a delimiter specified by a regular expression. If $delim is undefined all data is read. If $size is defined, data will be read internally in chunks of $size bytes. This does not mean that we will return the data when size bytes are read. Note that $delim is discarded from the data returned. $sock->read($bufref, [$size, $timeout]) Reads data of the socket. Not more than $size bytes. Might return less if the data is available. Dies on timeout. $sock->pushback($data) Put data back into the socket. Data will returned next time you read(). Can be used if you find out that you have read too much. $sock->write($data, [$timeout]) Write data to socket. The $data argument might be a scalar or code. If data is a reference to a subroutine, then we will call this routine to obtain the data to be written. The routine will be called until it returns undef or empty data. Data might be returned from the callback as a scalar or as a reference to a scalar. Write returns the number of bytes written to the socket. $sock->_getaddress($h, $p) Given a host and a port, it will return the address (sockaddr_in) suitable as the name argument for connect() or bind(). Might return several addresses in array context if the hostname is bound to several IP addresses. SELF TEST ========= This self test is only executed when this file is run standalone. It tests its functions against some standard TCP services implemented by inetd. If you do not have them around the tests will fail.  File: pm.info, Node: LWP/TkIO, Next: LWP/UserAgent, Prev: LWP/Socket, Up: Module List Tk I/O routines for the LWP library *********************************** NAME ==== LWP::TkIO - Tk I/O routines for the LWP library SYNOPSIS ======== use Tk; require LWP::TkIO; require LWP::UserAgent; DESCRIPTION =========== This module provide replacement functions for the LWP::IO functions. Require this module if you use Tk and want non exclusive IO behaviour from LWP. This does not allow LWP to run simultaneous requests though. See also *Note LWP/IO: LWP/IO,.  File: pm.info, Node: LWP/UserAgent, Next: LaTeX/Parser, Prev: LWP/TkIO, Up: Module List A WWW UserAgent class ********************* NAME ==== LWP::UserAgent - A WWW UserAgent class SYNOPSIS ======== require LWP::UserAgent; $ua = LWP::UserAgent->new; $request = HTTP::Request->new('GET', 'file://localhost/etc/motd'); $response = $ua->request($request); # or $response = $ua->request($request, '/tmp/sss'); # or $response = $ua->request($request, \&callback, 4096); sub callback { my($data, $response, $protocol) = @_; .... } DESCRIPTION =========== The `LWP::UserAgent' is a class implementing a simple World-Wide Web user agent in Perl. It brings together the HTTP::Request, HTTP::Response and the LWP::Protocol classes that form the rest of the core of libwww-perl library. For simple uses this class can be used directly to dispatch WWW requests, alternatively it can be subclassed for application-specific behaviour. In normal use the application creates a UserAgent object, and then configures it with values for timeouts, proxies, name, etc. It next creates an instance of HTTP::Request for the request that needs to be performed. This request is then passed to the UserAgent request() method, which dispatches it using the relevant protocol, and returns a `HTTP::Response' object. The basic approach of the library is to use HTTP style communication for all protocol schemes, i.e. you also receive an `HTTP::Response' object for gopher or ftp requests. In order to achieve even more similarity to HTTP style communications, gopher menus and file directories are converted to HTML documents. The request() method can process the content of the response in one of three ways: in core, into a file, or into repeated calls to a subroutine. You choose which one by the kind of value passed as the second argument to request(). The in core variant simply stores the content in a scalar 'content' attribute of the response object and is suitable for small HTML replies that might need further parsing. This variant is used if the second argument is missing (or is undef). The filename variant requires a scalar containing a filename as the second argument to request() and is suitable for large WWW objects which need to be written directly to the file without requiring large amounts of memory. In this case the response object returned from request() will have an empty content attribute. If the request fails, then the content might not be empty, and the file will be untouched. The subroutine variant requires a reference to callback routine as the second argument to request() and it can also take an optional chuck size as the third argument. This variant can be used to construct "pipe-lined" processing, where processing of received chuncks can begin before the complete data has arrived. The callback function is called with 3 arguments: the data received this time, a reference to the response object and a reference to the protocol object. The response object returned from request() will have empty content. If the request fails, then the the callback routine is not called, and the response->content might not be empty. The request can be aborted by calling die() in the callback routine. The die message will be available as the "X-Died" special response header field. The library also allows you to use a subroutine reference as content in the request object. This subroutine should return the content (possibly in pieces) when called. It should return an empty string when there is no more content. METHODS ======= The following methods are available: $ua = LWP::UserAgent->new; Constructor for the UserAgent. Returns a reference to a LWP::UserAgent object. $ua->simple_request($request, [$arg [, $size]]) This method dispatches a single WWW request on behalf of a user, and returns the response received. The $request should be a reference to a HTTP::Request object with values defined for at least the method() and uri() attributes. If $arg is a scalar it is taken as a filename where the content of the response is stored. If $arg is a reference to a subroutine, then this routine is called as chunks of the content is received. An optional $size argument is taken as a hint for an appropriate chunk size. If $arg is omitted, then the content is stored in the response object itself. $ua->request($request, $arg [, $size]) Process a request, including redirects and security. This method may actually send several different simple requests. The arguments are the same as for `simple_request()'. $ua->redirect_ok This method is called by request() before it tries to do any redirects. It should return a true value if a redirect is allowed to be performed. Subclasses might want to override this. The default implementation will return FALSE for POST request and TRUE for all others. $ua->credentials($netloc, $realm, $uname, $pass) Set the user name and password to be used for a realm. It is often more useful to specialize the get_basic_credentials() method instead. $ua->get_basic_credentials($realm, $uri, [$proxy]) This is called by request() to retrieve credentials for a Realm protected by Basic Authentication or Digest Authentication. Should return username and password in a list. Return undef to abort the authentication resolution atempts. This implementation simply checks a set of pre-stored member variables. Subclasses can override this method to e.g. ask the user for a username/password. An example of this can be found in `lwp-request' program distributed with this library. $ua->agent([$product_id]) Get/set the product token that is used to identify the user agent on the network. The agent value is sent as the "User-Agent" header in the requests. The default agent name is "libwww-perl/#.##", where "#.##" is substitued with the version numer of this library. The user agent string should be one or more simple product identifiers with an optional version number separated by the "/" character. Examples are: $ua->agent('Checkbot/0.4 ' . $ua->agent); $ua->agent('Mozilla/5.0'); $ua->from([$email_address]) Get/set the Internet e-mail address for the human user who controls the requesting user agent. The address should be machine-usable, as defined in RFC 822. The from value is send as the "From" header in the requests. There is no default. Example: $ua->from('gaas@cpan.org'); $ua->timeout([$secs]) Get/set the timeout value in seconds. The default timeout() value is 180 seconds, i.e. 3 minutes. $ua->cookie_jar([$cookies]) Get/set the *HTTP::Cookies* object to use. The default is to have no cookie_jar, i.e. never automatically add "Cookie" headers to the requests. $ua->parse_head([$boolean]) Get/set a value indicating wether we should initialize response headers from the section of HTML documents. The default is TRUE. Do not turn this off, unless you know what you are doing. $ua->max_size([$bytes]) Get/set the size limit for response content. The default is undef, which means that there is no limit. If the returned response content is only partial, because the size limit was exceeded, then a "X-Content-Range" header will be added to the response. $ua->clone; Returns a copy of the LWP::UserAgent object $ua->is_protocol_supported($scheme) You can use this method to query if the library currently support the specified scheme. The scheme might be a string (like 'http' or 'ftp') or it might be an URI object reference. $ua->mirror($url, $file) Get and store a document identified by a URL, using If-Modified-Since, and checking of the Content-Length. Returns a reference to the response object. $ua->proxy(...) Set/retrieve proxy URL for a scheme: $ua->proxy(['http', 'ftp'], 'http://proxy.sn.no:8001/'); $ua->proxy('gopher', 'http://proxy.sn.no:8001/'); The first form specifies that the URL is to be used for proxying of access methods listed in the list in the first method argument, i.e. 'http' and 'ftp'. The second form shows a shorthand form for specifying proxy URL for a single access scheme. $ua->env_proxy() Load proxy settings from *_proxy environment variables. You might specify proxies like this (sh-syntax): gopher_proxy=http://proxy.my.place/ wais_proxy=http://proxy.my.place/ no_proxy="localhost,my.domain" export gopher_proxy wais_proxy no_proxy Csh or tcsh users should use the `setenv' command to define these environment variables. $ua->no_proxy($domain,...) Do not proxy requests to the given domains. Calling no_proxy without any domains clears the list of domains. Eg: $ua->no_proxy('localhost', 'no', ...); SEE ALSO ======== See *Note LWP: LWP, for a complete overview of libwww-perl5. See `lwp-request' and `lwp-mirror' for examples of usage. COPYRIGHT ========= Copyright 1995-2000 Gisle Aas. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: LaTeX/Parser, Next: LabPopEntry, Prev: LWP/UserAgent, Up: Module List Perl extension to parse LaTeX files *********************************** NAME ==== LaTeX::Parser - Perl extension to parse LaTeX files SYNOPSIS ======== use LaTeX::Parser; my $l = new LaTeX::Parser 'file' => 'file.tex'; my $p = $l->latex; # $p now hold a reference to an array of # file.tex parsed Or use it to break up LaTeX in a variable: my $l = new LaTeX::Parser 'content' => '\textit{Three Lives} by Gertrude Stein.'; Contents of nested braces are extracted as a single element. Another `LaTeX::Parser' will have to be created to parse nested braces. This is a very early version of `LaTeX::Parser', there are many bugs. I think this will work fine with plain TeX files but I do not plan on ever support that. DESCRIPTION =========== For now, only simple descriptions of the modules functions. LaTeX::Parser->new %hash Creates a LaTeX::Parser object. All values in `%hash' are initialize to the values in the object. The only two tested values to set are `file' and `content'. `file' is the name of the file to load the LaTeX file from, and it get copied into `content'. If content is set by then `%hash' then `file' will never be called. LaTeX::Parser->latex No arguments. Actualy does all the work. Loads the LaTeX file if not content was specified, and returns a reference to all parsed information. BUGS ==== Many bugs i'll find soon enough. Off the top of my head, I know backslashed brackes in LaTeX are considered normal brackets. I haven't even thought about math things, and don't think I will think about that any time soon. AUTHOR ====== Sven Heinicke, SEE ALSO ======== perl(1), latex(1).  File: pm.info, Node: LabPopEntry, Next: Language/Basic, Prev: LaTeX/Parser, Up: Module List A LabEntry widget with an automatic, configurable right-click menu built in, plus input masks. ********************************************************************************************** NAME ==== LabPopEntry - A LabEntry widget with an automatic, configurable right-click menu built in, plus input masks. SYNOPSIS -------- use LabPopEntry; $dw = $parent->LabPopEntry( -pattern => 'alpha', 'alphanum', 'capsonly', 'signed_int', 'unsigned_int', 'float', 'nondigit', or any supplied regexp. -nomenu => 0 or 1, -case => 'upper', 'lower', 'capitalize', -maxwidth => int, -minvalue => int, -maxvalue => int, -nospace => 0 or 1, -menuitems => ['string', 'callback', 'binding', 'index'], ); $dw->pack; DESCRIPTION ----------- LabPopEntry is a LabEntry widget with a right-click menu automatically attached. In addition, certain field masks can easily be applied to the entry widget in order to force the end-user into entering only the values you want him or her to enter. By default, there are five items attached to the right-click menu: Cut, Copy, Paste, Delete and Sel. All. The default bindings for the items are Control-x, Control-c, Control-v, Control-d, and Control-a, respectively. The difference between 'Cut' and 'Delete' is that the former automatically copies the contents that were cut to the clipboard, while the latter does not. OPTIONS ------- *-pattern =>* string The pattern specified here creates an input mask for the LabPopEntry widget. There are seven pre-defined masks: * alpha - Upper and lower case a-z only. * alphanum - Alpha-numeric characters only. * capsonly - Upper case A-Z only. * nondigit - Any characters except 0-9. * float - A float value, which may or may not include a decimal. * signed_int - A signed integer value, which may or may not include a '+'. * unsigned_int - An unsigned integer value. You may also specify a regular expression of your own design using Perl's standard regular expression mechanisms. Be sure to use single quotes, e.g. '/\d\w\d/' *-nomenu =>* **0* or 1* If set to true, then no right-click menu will appear. Presumably, you would set this if you were only interested in the input-mask functionality. The default is, of course, 0. *-nospace =>* **0* or 1* If set to true (1), the user may not enter whitespace before, after or between words within that LabPopEntry widget. The default is 0. *-maxwidth =>* int Specifies the maximum number of characters that the user can enter in that particular LabPopEntry widget. Note that this is not the same as the width of the widget itself. *-maxvalue =>* *int or float* If one of the pre-defined numeric patterns is chosen, this specifies the maximum allowable value that may be entered by a user for the widget. *-minvalue =>* *int or float* If one of the pre-defined numeric patterns is chosen, this specifies the minimum allowable value for the first digit (0-9). This should work better. *-menuitems =>* *['string', 'callback', '', 'underline_index']* If specified, this creates a user-defined right-click menu rather than the one that is provided by default. The value specified must be a four element nested anonymous array that contains (in this order): 1. a string that appears on the menu, 2. a callback (in 'package::callback' syntax format), 3. a binding for that option (see below), 4. an index value specifying the character in the string to be underlined. The binding specified need only be in the form, ''. You needn't explicitly bind it yourself. Your callback will automatically be bound to the event sequence you specified. METHODS ------- *$lpe->deleteItem(index, ?index?)* Deletes the menu option at the specified index. A range of values may be deleted as well, e.g. $lpe->deleteItem(3,'end'); Returns an array reference if a single item is deleted, or a reference to an array of references if more than one item is deleted. *$lpe->addItem(?index?, $item)* Adds a menu option at the specified index, where $item is an anonymous array consisting of four elements (see the -menuitems option for details). If no index is specified, the new item will be added at the end of the menu. If an item already exists at that index, the current menu items will be "bumped" down. Returns the list of menuitems. ADVERTISED SUBWIDGETS --------------------- *$lpe->Subwidget('popupmenu')* Returns a reference to the popupmenu (a toplevel widget). KNOWN BUGS ---------- The -minvalue only works for the first digit. There is still potential for odd results if your bind happens to coincide with a binding already used by the Window Manager. In windows, where I did most of my testing, this meant that Control-v would paste twice, once because MS Windows told it to, and once because I told it to. PLANNED CHANGES --------------- Fix the issues mentioned above. Automatically bind the 'Alt' key to the underlined character. Give the option to remove bindings completely. AUTHOR ------ Daniel J. Berger djberg96@hotmail.com SEE ALSO -------- Entry, LabEntry  File: pm.info, Node: Language/Basic, Next: Language/Basic/Expression, Prev: LabPopEntry, Up: Module List Perl Module to interpret BASIC ****************************** NAME ==== Language::Basic - Perl Module to interpret BASIC SYNOPSIS ======== use Language::Basic; my $Program = new Language::Basic::Program; $Program->input("program.bas"); # Read lines from a file $Program->parse; # Parse the Program $Program->implement; # Run the Program $Program->output_perl; # output Program as a Perl program $Program->line("20 PRINT X"); # add one line to existing Program Featured scripts: basic.pl Runs BASIC programs from the command line. termbasic.pl Term::Readline program. Input one line of BASIC at a time, then run the program. basic2pl.pl Outputs a Perl program that does the same thing as the input BASIC program. DESCRIPTION =========== This module lets you run any BASIC programs you may have lying around, or may inspire you to write new ones! The aspects of the language that are supported are described below. Note that I was pretty much aiming for Applesoft BASIC (tm) ca. 1985, not some modern BASIC with real subroutines. Class Language::Basic::Program ------------------------------ This class handles a whole program. A Program is just a bunch of Lines, each of which has one or more Statements on it. Running the program involves moving through the lines, usually in numerical order, and implementing each line. Methods: current_program Returns the program currently being parsed/implemented/whatever set_current_program Sets arg0 to be the Current Program current_line Returns the LB::line currently being parsed/implemented/whatever set_current_line Sets the current line in Program arg0 to be line number arg1 first_line_number Returns (not surprisingly) the first line number in Program arg0 current_line_number What line number in Program arg0 are we currently on? input This method reads in a program from a file, whose name is the string arg0. It doesn't do any parsing, except for taking the line number out of the line. line This method takes a line of BASIC (arg1, already chomped), forms a new LB::Line with it, and adds it to the Program (arg0). It doesn't do any parsing, except for taking the line number out of the line. parse This method parses the program, which just involves looping over the lines in the program and parsing each line. implement This method actually runs the program. That is, it starts on the first line, and implements statements one at a time. It performs the statements on a line in order, and goes from line to line in numerical order, unless a GOTO, NEXT, etc. sends it somewhere else. It stops when it hits an END statement or "falls off" the end of the program. start This method erases program stack and moves line pointer to beginning of program It should be called any time we start going through the program. (Either implement or output_perl.) goto_line Continue Program execution at the first Statement on line number arg1. goto_after_statement Kind of like goto_line, except go to the Statement after Statement arg1. (Or the first statement on the line just after Statement arg1, if it's the last Statement on its line.) E.g., when you RETURN from a GOSUB, you want to return to the GOSUB line but start execution after the GOSUB. Same with FOR. The following methods are called from LB::Statement parse or implement methods to implement various BASIC commands. push_stack (GOSUB) Call a subroutine, i.e. push the current Statement::Gosub onto the Program's calling stack pop_stack (RETURN) Return from a subroutine, i.e., pop the top Statement::Gosub off of the Program's calling stack store_for (FOR) Store a Statement::For arg1, so that when we get to the corresponding Statement::Next, we know where to go back to pop_stack (NEXT) Get the Statement::For corresponding to Statement::Next arg1 add_data (DATA) Add a piece of data to the Program's data storage, to be accessed later. get_data (READ) Get a piece of data that was stored earlier. Finally, there are methods for translating a Program to Perl. output_perl This method translates a program to Perl and outputs it. It does so by looping through the Lines of the program in order, and calling output_perl on each one. It also prints some pre- and post- data, such as any subroutines it needs to declare (e.g., subs that imitate BASIC functionality, as well as subs that correspond to BASIC DEF statements). It attempts to print everything out nicely, with added whitespace et al. to make the code somewhat readable. (Note that all of the subpackages' output_perl methods return strings rather than printing them, so we can handle all of the printing, indenting, etc. here.) need_sub Tells the Program that it needs to use the sub named arg0 (whose definition is in arg1). This is used for outputting a Perl translation of a BASIC program, so that you only write "sub mid_str {...}" if MID$ is used in the BASIC program. Class Language::Basic::Line --------------------------- This class handles one line of a BASIC program, which has one or more Statements on it. This class has no implement method. The reason is that sometimes, you'll jump to the middle of a line. (E.g., returning from the GOSUBs in 10 FOR A=1 TO 10: GOSUB 1000: NEXT A) Methods: get_next Returns the Line's line number get_next Returns the next line number in the Program set_next Sets the next line number in the Program to be arg1. parse This method breaks the line up into Statements (and removes whitespace, except in strings), then parses the Statements in order. output_perl This method simply calls output_perl on each of the Line's Statements in order. BASIC LANGUAGE REFERENCE ======================== This is a (hopefully current) description of what Language::Basic supports. For each command, I give an example use of that command, and possible a comment or two about it. Also see *Note Language/Basic/Syntax: Language/Basic/Syntax,, which describes the exact syntax for each statement, expressions, variable names, etc. Commands -------- DATA DATA 1,2,"HI". These will be read sequentially by READ statements. Note that currently all string constants must be quoted. DEF DEF FNA(X)= INT(X + .5). DIM DIM A(20), B(10,10). Arrays default to size 10 (or actually 11 since they start at zero.) END END. FOR FOR I = 1 TO 10 STEP 3. STEP defaults to 1 if not given, and may be negative. (For loops are always implemented at least once.) GOTO GOTO 30. Note that GOTO 30+(X*3) is also supported. GOSUB GOSUB 10+X. Gosub is just like GOTO, except that when the program gets to a RETURN statement, it will come back to the statement just after the GOSUB. IF IF X > Y THEN 30 ELSE X = X + 1. ELSE is not required. In a THEN or ELSE, a lone number means GOTO that number (also known as an implied GOTO). INPUT INPUT A$, B$. Also allowed is INPUT "FOO"; BAR. This prints "FOO?" instead of just "?" as the input prompt. LET LET X=4. The word "LET" isn't required; i.e. X=4 is just like LET X=4. NEXT NEXT I. Increment I by STEP, test against its limit, go back to the FOR statement if it's not over (or under, for a descending loop) its limit. ON ON X-3 GOSUB 10,20. This is equivalent to: IF X-3 = 1 THEN GOSUB 10 IF X-3 = 2 THEN GOSUB 20 ON ... GOTO is also allowed. PRINT PRINT FOO; BAR$, 6*BLAH. semicolon means no space (or one space after printing numbers!), comma is like a 14-character tab (or \n past column 56). Print \n after the last expression unless there's a semicolon after it. READ READ A, B(I), C$. Reads data from DATA statements into variables REM REM WHATEVER. Anything after the REM is ignored (including colons and succeeding statements!) RETURN RETURN. Return to the statement after the last GOSUB. Intrinsic functions ------------------- The following functions are currently supported: Numeric Functions: INT (like Perl's int), RND (rand), ASC (ord), LEN (length), VAL (turn a string into a number; in Perl you just + 0 :)) RND just calls Perl's rand; you can't seed it or anything. String functions: CHR$, MID$, STR$ Overall Coding Issues --------------------- * Multiple statements can appear on one line, separated by colons. E.g.: 10 FOR I = 1 TO 10: PRINT I: NEXT I, or 20 FOR A = 1 TO 4: GOSUB 3000: NEXT A. Note that after a THEN, all statements are considered part of the THEN, until a statement starting with ELSE, after which all remaining statements are part of the ELSE. A REM slurps up everything until the end of the line, including colons. * Hopefully your code doesn't have many bugs, because there isn't much error checking. * Everything except string constants is converted to upper case, so 'a' and 'A' are the same variable. (But note that the string "Yes" <> "YES", at least for now.) * Spaces are (currently) required around various pieces of the program, like THEN, ELSE, GOTO. That is, GOTO20 won't work. This may or may not change in the future. * When you use basic.pl (&LB::Program::input), the lines in the input file must be in numerical order. When using termbasic.pl (&LB::Program::line), this rule doesn't apply. BUGS ==== This is an alpha release and likely contains many bugs; these are merely the known ones. If you use multiple *Language::Basic::Program* objects in a Perl program, functions and variables can leak over from one to another. It is possible to get some Perl warnings; for example, if you input a string into a numerical variable and then do something with it. PRINT and so forth all go to the select-ed output handle; there really ought to be a way to set for a *Program* the output handle. There needs to be better and consistent error handling, and a more extensive test suite. AUTHOR ====== Amir Karger (akarger@cpan.org) David Glasser gave ideas and feedback, hunted down bugs, and sent in a major patch to help the LB guts. COPYRIGHT ========= Copyright (c) Amir Karger 2000 LICENSE ======= This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. HISTORY ======= BASIC stands for Beginner's All-purpose Symbolic Instruction Code. Since it was considered pretty hot stuff in the early 80's, it's the first language that I and a lot of folks my age learned, so it holds a special place in my heart. Which is the only reason I spent so many hours writing an interpreter for it long after it was superseded by real interpreted languages that had subroutines and didn't rely quite so much on GOTO. I originally wrote this interpreter in C, as the final project for my first C programming class in college. Its name at that point was COMPLEX, which stood for "C-Oriented Major Project which did not use LEX". When I learned Perl, I felt like its string handling capabilities would be much better for an interpreter, so eventually I ported and expanded it. (Incidentally, I was right. I had surpassed the original program's functionality in less than a week, and I was able to run wumpus in 2.) A big goal for the Perl port is to support enough of the language that I can run wumpus, another legacy from my childhood. The interpreter's name could be changed from COMPLEX to "Perl Eclectic Retro interpreter which did not use Parse::LEX", or PERPLEX, but I settled for Language::Basic instead. SEE ALSO ======== All of the `Language::Basic::*' in this nodes associated with Language::Basic sub-modules *Note Language/Basic/Syntax: Language/Basic/Syntax,, which describes the syntax supported by the Language::Basic module perl(1), wump(6)