This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: LibWeb/HTML/Error, Next: LibWeb/HTML/Site, Prev: LibWeb/HTML/Default, Up: Module List Displaying error messages in html for libweb applications ********************************************************* NAME ==== LibWeb::HTML::Error - Displaying error messages in html for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * No non-standard Perl's library is required. ISA === * None. SYNOPSIS ======== You do not use this class directly; use LibWeb::HTML::Default instead. See *Note LibWeb/HTML/Default: LibWeb/HTML/Default,. ABSTRACT ======== This class defines a method for displaying error messages in HTML. Several basic error messages are also defined. The current version of LibWeb::HTML::Error is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net DESCRIPTION =========== METHODS ------- *display_error()* Params: caller, *error_msg*, error_input, *help_msg* Pre: * caller is a reference to the calling object. All other parameters are scalars except *help_msg* which must be a SCALAR reference. Post: * Display a HTML page with the error message, error input and help message. NOTE: Do not call this method directly, call LibWeb::Core::fatal() instead. See *Note LibWeb/Core: LibWeb/Core, for details. All of the following methods return a SCALAR reference to an error message in HTML. *mysterious_error()* *special_characters_not_allowed()* *hit_back_and_edit()* *post_too_large()* *database_error()* *login_failed()* *logout_failed()* *login_expired()* *exceeded_max_login_attempt()* *registration_failed()* *cookie_error()* AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= BUGS ==== SEE ALSO ======== *Note LibWeb/Core: LibWeb/Core,, *Note LibWeb/HTML/Standard: LibWeb/HTML/Standard,, *Note LibWeb/HTML/Default: LibWeb/HTML/Default,.  File: pm.info, Node: LibWeb/HTML/Site, Next: LibWeb/HTML/Standard, Prev: LibWeb/HTML/Error, Up: Module List AN INTERFACE FOR LIBWEB APPLICATIONS' HTML DISPLAY ************************************************** NAME ==== LibWeb::HTML::Site - AN INTERFACE FOR LIBWEB APPLICATIONS' HTML DISPLAY SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * No non-standard Perl's library is required. ISA === * LibWeb::Core SYNOPSIS ======== This is an interface and actual implementation is done by LibWeb::HTML::Default. ABSTRACT ======== This is an interface describing how a HTML page should be displayed. Please see *Note LibWeb/HTML/Default: LibWeb/HTML/Default, for the actual implementation. The current version of LibWeb::HTML::Site is available at http://libweb.sourceforge.net ftp://libweb.sourceforge/pub/libweb Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net ftp://leaps.sourceforge.net/pub/leaps DESCRIPTION =========== See *Note LibWeb/HTML/Default: LibWeb/HTML/Default,. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= BUGS ==== SEE ALSO ======== *Note LibWeb/HTML/Default: LibWeb/HTML/Default,.  File: pm.info, Node: LibWeb/HTML/Standard, Next: LibWeb/Session, Prev: LibWeb/HTML/Site, Up: Module List An interface defining HTML display for libweb applications ********************************************************** NAME ==== LibWeb::HTML::Standard - An interface defining HTML display for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * No non-standard Perl's library is required. ISA === * LibWeb::Core SYNOPSIS ======== This is an interface and actual implementation is done by LibWeb::HTML::Default. ABSTRACT ======== This is an interface describing how a HTML page should be displayed. Please see *Note LibWeb/HTML/Default: LibWeb/HTML/Default, for the actual implementation. The current version of LibWeb::HTML::Standard is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net DESCRIPTION =========== See *Note LibWeb/HTML/Default: LibWeb/HTML/Default,. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= BUGS ==== SEE ALSO ======== *Note LibWeb/HTML/Default: LibWeb/HTML/Default,, *Note LibWeb/HTML/Error: LibWeb/HTML/Error,  File: pm.info, Node: LibWeb/Session, Next: LibWeb/Themes/Default, Prev: LibWeb/HTML/Standard, Up: Module List Sessions management for libweb applications ******************************************* NAME ==== LibWeb:: - Sessions management for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * LibWeb::CGI * LibWeb::Crypt * LibWeb::Database * LibWeb::Digest ISA === * LibWeb::Core SYNOPSIS ======== use LibWeb::Session; my $s = new LibWeb::Session(); my ($user_name, $user_id) = $s->get_user(); #or my ($user_name, $user_id) = $s->get_user( -is_update_db => 1 ); ABSTRACT ======== This class manages session authentication after the remote user has logged in. The current version of LibWeb::Session is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net TYPOGRAPHICAL CONVENTIONS AND TERMINOLOGY ========================================= Variables in all-caps (e.g. MAX_LOGIN_ATTEMPT_ALLOWED) are those variables set through LibWeb's rc file. Please read *Note LibWeb/Core: LibWeb/Core, for more information. All `error/help messages' mentioned can be found at *Note LibWeb/HTML/Error: LibWeb/HTML/Error, and they can be customized by ISA (making a sub-class of) LibWeb::HTML::Default. Please see *Note LibWeb/HTML/Default: LibWeb/HTML/Default, for details. Method's parameters in square brackets means optional. DESCRIPTION =========== METHODS ------- *get_user()* Check to see if the viewing Web browser has logged in by checking expiration time, IP and MAC in the authentication cookie, and return the user name and the user ID if it passes all the authentication checks. Params: [ -no_auth=>, -mac_mismatch=>, -ip_mismatch=>, -expired=>, -is_update_db=> ] Pre: * *-no_auth* is a CODE reference for callback if the viewing browser does not return an authentication cookie. * *-mac_mismatch* is a CODE reference for callback if the authentication cookie has been tampered with. * *-ip_mismatch* is a CODE reference for callback if the IP in the authentication cookie does not correspond to the IP address of the viewing browser. * *-expired* is a CODE reference for callback if the authentication cookie is expired. * *-is_update_db* is either 1 or 0 (default). Use this to indicate whether this is the first login check. This parameter should be 1 in order to update database's *NUM_LOGIN_ATTEMPT* when a user first logged in. Post: * Retrieve authentication cookies from the viewing Web browser, * All *-no_auth*, *-mac_mismatch*, *-ip_mismatch* and *-expired* default to the following actions if you do not provide the callbacks: * Nullify and delete all authentication cookies resided on the viewing Web browser, * send an alert e-mail to *ADMIN_EMAIL*, * log that event in *FATAL_LOG*, * redirect the remote user to the login page (*LM_IN*), and * abort the current running program. * Check to see If cookie values are null/zero, call *-no_auth* if no authentication cookie is retrieved, * Check to see If MAC matches, call *-mac_mismatch* if not, * Check to see if If IP matches, call *-ip_mismatch* if not, * update database: Set *NUM_LOGIN_ATTEMPT* to 0 and call *-expired* if the login has expired, * If the retrieved cookie passes all the above authentication checks, set database's *NUM_LOGIN_ATTEMPT* to *LOGIN_INDICATOR* if parameter *-is_update_db* is defined and is equal to 1. This helps indicate that the user is online (currently login), * and finally return an array (user name and uid) in plain text. Note: *USER_LOG_TABLE.NUM_LOGIN_ATTEMPT* != 0 && != *LOGIN_INDICATOR* means there were several attempts to login but unsuccessful solely because incorrect password were entered by the remote user. You need to re-flush database's *USER_LOG_TABLE.NUM_LOGIN_ATTEMPT* to 0 manually after receiving the alert e-mail if this value == *MAX_LOGIN_ATTEMPT_ALLOWED*; otherwise, the user will never be able to sign into your site even he/she enters the correct password afterwards. DEPRECATED METHODS ------------------ *is_login()* Note: This method is deprecated as of LibWeb-0.02. You are encouraged to use *get_user()* instead. *is_login()* is mainly for backward compatible with client codes written using LibWeb-0.01. Params: [ is_just_logged_in ] Pre: * Parameter `is_just_logged_in' is either 1 or undef. This is to indicate whether this is the first login check. This parameter should be defined in order to update database's USER_LOG_TABLE.NUM_LOGIN_ATTEMPT when user first logged in; possibly in the first script invoked after the user has been authenticated. Post: * Retrieve authentication cookies from client Web browser, * if cookie values are null/zero, send an alert e-mail to ADMIN_EMAIL and redirect the remote user to the login page (LM_IN), * if MAC mis-match (this means possible spoofing from remote host), send an alert e-mail to ADMIN_EMAIL and redirect the remote user to the login page (LM_IN), * if IP mis-match (this means possible spoofing from remote host), send an alert e-mail to ADMIN_EMAIL and redirect the remote user to the login page (LM_IN), * login is expired if expiration time reached. Update database: set USER_LOG_TABLE.NUM_LOGIN_ATTEMPT to 0, send an alert e-mail to ADMIN_EMAIL and redirect the remote user to the login page (LM_IN), * nullify and delete all cookies reside on client Web browser immediately if any of item 2, 3, 4 or 5 happens. Send an alert e-mail to ADMIN_EMAIL and redirect the remote user to the login page (LM_IN), * if client has officially logged in and none of item 2, 3, 4 or 5 happens, set USER_LOG_TABLE.NUM_LOGIN_ATTEMPT to LOGIN_INDICATOR if parameter `is_just_logged_in' is defined. This helps to indicate that the user is online (currently logged in), and * finally return an array (user name and uid) in plain text. Note: USER_LOG_TABLE.NUM_LOGIN_ATTEMPT != 0 && != LOGIN_INDICATOR means there were several attempts to login but unsuccessful solely because incorrect password were entered by the remote user. You need to re-flush NUM_LOGIN_ATTEMPT to 0 manually after 24 hours (no rigorous reason why it should be 24 hours) of receiving the alert e-mail if this value == MAX_LOGIN_ATTEMPT_ALLOWED. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= BUGS ==== SEE ALSO ======== *Note LibWeb/Admin: LibWeb/Admin,, *Note LibWeb/Core: LibWeb/Core,, *Note LibWeb/Crypt: LibWeb/Crypt, *Note LibWeb/Digest: LibWeb/Digest,.  File: pm.info, Node: LibWeb/Themes/Default, Next: LibWeb/Time, Prev: LibWeb/Session, Up: Module List Default HTML widgets and theme for libweb applications ****************************************************** NAME ==== LibWeb::Themes::Default - Default HTML widgets and theme for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * No non-standard Perl's library is required. ISA === * LibWeb::Core SYNOPSIS ======== use LibWeb::Themes::Default; my $theme = new LibWeb::Themes::Default(); my $tabs = [ 'Home', 'Featured reports', 'Best buy', 'Login' ]; my $tabbed_navigation_bar = $theme->tabber( -tabs => $tabs, -active => 2 ); my $stock_quotes = $theme->bordered_table( -content => [ $fetched_stock_quotes ] ); my $weather = $theme->bordered_titled_table( -title => "Today's weather", -content => [ $fetched_weather ] ); my $back_issues = $theme->titled_table( -title => "Looking for back issues?", -content => [ $back_issues_archive_list ] ); my $news = $theme->enlighted_titled_table( -title => "Today's news", -content => [ $fetched_news ] ); Please see the synopsis of *Note LibWeb/HTML/Default: LibWeb/HTML/Default, to see how those HTML constructs can be displayed. ABSTRACT ======== This class provides several common table templates for HTML display. This allows Web application designers focus their efforts on the logic of programs; while Web page designers spend their efforts on customizing this default by ISAing this class, say LibWeb::Themes::Futuristic, and writing different themes. A sample MyTheme.pm is included in the distribution for your hacking pleasure. The current version of LibWeb::Themes::Default is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net TYPOGRAPHICAL CONVENTIONS AND TERMINOLOGY ========================================= Variables in all-caps (e.g. SITE_BG_COLOR) are those variables set through LibWeb's rc file. Please read *Note LibWeb/Core: LibWeb/Core, for more information. Method's parameters in square brackets means optional. DESCRIPTION =========== *bordered_table()* Params: -content=> [, -border_color=>, -bg_color=>, align=>, -valign=>, -cellpadding=>, -width=> ] Pre: * `-content' must be an ARRAY reference to elements which are scalars/SCALAR references/ARRAY references to plain HTML. * `-border_color' default is SITE_LIQUID_COLOR2, * `-bg_color' default is SITE_BG_COLOR, * `-align' is the content's horizontal alignment; default is `left', * `-valign' is the content's vertical alignment; default is `top', * `-cellpadding' is the distance between the content and the `border' of table, default is 2, * `-width' default is 100%. Post: * Return a SCALAR reference to a formatted table in HTML. *bordered_titled_table()* Params: -title=>, -content=> [, -title_space=>, -title_align=>, -border_color=>, -title_txt_color=>, -bg_color=>, -align=>, -valign=>, -cellpadding=>, -width=> ] Pre: * -title is a scalar, * `-content' must be an ARRAY reference to elements which are scalars/SCALAR references/ARRAY references to plain HTML. * `-title_space' is the space ( ) prepended before (if `-title_align' is `left') or append after (if `-title_align' is `right') the title; default is 2, i.e. `  '. If `-title_align' is `center', -title_space is always 0, * `-title_align' default is `center', * `-border_color' default is SITE_1ST_COLOR, * `-title_txt_color' default is SITE_BG_COLOR, * `-bg_color' default is SITE_BG_COLOR, * `-align' is the content's horizontal alignment; default is `left', * `-valign' is the content's vertical alignment; default is `top', * `-cellpadding' is the distance between the content and the `border' of table, default is 1, * `-width' default is 100%. Post: * Return a SCALAR reference to a formatted table in HTML. *enlighted_titled_table()* Params: -title=>, -content=> [, -title_space=>, -title_align=>, -title_bg_color=>, -title_txt_color=>, -title_border_color=>, -bg_color=>, -align=>, -valign=>, -cellpadding=>, -width=> ] Pre: * `-title' is a scalar, * `-content' must be an ARRAY reference to elements which are scalars/SCALAR references/ARRAY references to plain HTML, * `-title_space' is the space ( ) prepended before (if `-title_align' is `left') or append after (if `-title_align' is `right') the title; default is 2, i.e. `  '. It is always 0 if `-title_align' is `center', * `-title_align' default is `center', * `-title_bg_color' default is SITE_LIQUID_COLOR3, * `-title_txt_color' default is SITE_LIQUID_COLOR5, * `-title_border_color' default is SITE_LIQUID_COLOR5, * `-bg_color' default is SITE_BG_COLOR, * `-align' is the content's horizontal alignment; default is `left', * `-valign' is the content's vertical alignment; default is `top', * `-cellpadding' is the distance between the content and the `border' of table, default is 1. * `-width' default is 100%. Post: * Return a SCALAR reference to a formatted table in HTML. *tabber()* Params: -tabs=>, -active=> [, -active_color=>, -fade_color=>, -tab_padding=>, -tab_width=>, -gap_width=>, -total_width=>, -base=>, -base_height=>, -base_align, -left_stub=>, -right_stub=>, -left_stub_align=>, -right_stub_align=>, -left_stub_width=>, -right_stub_width=> ] Pre: * `-tabs' is an ARRAY reference to scalar or SCALAR reference * `-active' is a number indicating which tab is currently active (count from 0) * `-active_color' is the color for the active tab; default is SITE_1ST_COLOR * `-fade_color' is the color for non-active tabs; default is SITE_LIQUID_COLOR3 * `-tab_padding' is the distance between a tab's content to its border, either in pixel or percentage; default is 0 * `-tab_width' is the width of each tab, either in pixel or percentage; default is ( total_width / (2 * number of tabs) ) * `-gap_width' is the distance between two adjacent tabs, either in pixel or percentage; default if 1% * `-total_width' is the width of the whole tabber, either in pixel or percentage; default is 100% * `-base' is a SCALAR reference to HTML to be put under the tabs * `-base_height' is the height of -base, either in pixel or percentage; default is 5. You do not want to specify this if you specify `-base' * `-base_align' default is `left' * `-left_stub' is a SCALAR reference to HTML to be put to the left of the tabs * `-right_stub' is a SCALAR reference to HTML to be put to the right of the tabs * `-left_stub_align' is 'left', 'center' or 'right'; default is 'left' * `-right_stub_align' is 'left', 'center' or 'right'; default is 'right' * `-left_stub_width' is either in pixel or percentage, you may want to specify this if you specify `-left_stub' * `-right_stub_width' is either in pixel or percentage Post: * Return a SCALAR reference to a formatted tabbing navigation bar in HTML format. table() Params: -content=> [, -bg_color=>, -align=>, -valign=>, -width=> ] Pre: * `-content' must be an ARRAY reference to elements which are scalars/SCALAR references/ARRAY references to plain HTML, * `-bg_color' default is SITE_BG_COLOR, * `-align' is the content's horizontal alignment; default is `left', * `-valign' is the content's vertical alignment; default is `top', * `-width' default is 100%. Post: * Return a SCALAR reference to a formatted table in HTML. *titled_table()* Params: -title=>, -content=> [, -title_space=>, -title_align=>, -title_bg_color=>, -title_txt_color=>, -bg_color=>, align=>, -valign=>, -cellpadding=>, -width=> ] Pre: * -title is a scalar, * `-content' must be an ARRAY reference to elements which are scalars/SCALAR references/ARRAY references to plain HTML, * `-title_space' is the space ( ) prepended before (if `-title_align' is `left') or append after (if `-title_align' is `right') the title. It is always 0 if `-title_align' is `center'. Default is 2, i.e. `  ', * `-title_align' default is `center', * `-title_bg_color' default is SITE_1ST_COLOR, * `-title_txt_color' default is SITE_BG_COLOR, * `-bg_color' default is SITE_BG_COLOR, * `-align' is the content's horizontal alignment; default is `left', * `-valign' is the content's vertical alignment; default is `top', * `-cellpadding' is the distance between the content and the `border' of table, default is 1. * `-width' default is 100%. Post: * Return a SCALAR reference to a formatted table in HTML. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= BUGS ==== This release does not provide a lot of table templates and only a default theme is available. Hopefully more people can write more themes for LibWeb and make them available at http://libweb.sourceforge.net. SEE ALSO ======== *Note LibWeb/HTML/Error: LibWeb/HTML/Error,, *Note LibWeb/HTML/Site: LibWeb/HTML/Site,, *Note LibWeb/HTML/Default: LibWeb/HTML/Default,  File: pm.info, Node: LibWeb/Time, Next: LinePrinter, Prev: LibWeb/Themes/Default, Up: Module List Various time formats for libweb applications ******************************************** NAME ==== LibWeb::Time - Various time formats for libweb applications SUPPORTED PLATFORMS =================== BSD, Linux, Solaris and Windows. REQUIRE ======= * No non-standard Perl's library is required. ISA === * None. SYNOPSIS ======== use LibWeb::Time(); my $time = new LibWeb::Time(); my $wday_mon_mday = $time->get_date(); my $hh_mm_ss = $time->get_time(); my $wday_mon_dd_hh_mm_ss_yyyy = $time->get_datetime(); my $yyyymmddhhmmss = $time->get_timestamp(); my $yyyy = $time->get_year(); ABSTRACT ======== This class uses the perl's localtime() routine to provide several methods which return time in several formats. The current version of LibWeb::Time is available at http://libweb.sourceforge.net Several LibWeb applications (LEAPs) have be written, released and are available at http://leaps.sourceforge.net DESCRIPTION =========== METHODS ------- *get_date()* Return 'wday mon mday' as a string, e.g. 'Sun May 28'. *get_time()* Return 'hh:mm:ss' as a string, e.g. '14:35:47'. *get_datetime()* Return 'wday mon dd hh:mm:ss yyyy' as a string, e.g. 'Sun May 28 14:35:47 2000'. This is the same as using the perl's localtime() directly in scalar context. *get_timestamp()* Return 'yyyymmddhhmmss' as a string, e.g. '20000528133547'. *get_year()* Return 'yyyy' as a string, e.g. '2000'. AUTHORS ======= Colin Kong (colin.kong@toronto.edu) CREDITS ======= BUGS ==== SEE ALSO ========  File: pm.info, Node: LinePrinter, Next: Lingua/AM/Abbreviate, Prev: LibWeb/Time, Up: Module List Perl extension for direct-to-lpd printing. ****************************************** NAME ==== LinePrinter - Perl extension for direct-to-lpd printing. SYNOPSIS ======== use LinePrinter; # Create new LinePrinter $lineprinter = new LinePrinter( filename => "/home/jdoe/myfile.txt", printer => "lp", server => "printserver", port => 515, lineconvert => "YES" ); # Print the file $result = $lineprinter->printfile(); # Print a string $result = $lineprinter->printstring("Smoke me a kipper, I'll be back for breakfast."); # Get Queue Status $result = $lineprinter->queuestatus(); DESCRIPTION =========== Perl module for directly printing to a print server/printer without having to create a pipe to either lpr or lp. This essentially mimics what the BSD LPR program does by connecting directly to the line printer printer port (almost always 515), and transmitting the data and control information to the print server. Please note that this module only talks to print servers that speak BSD. It will not talk to printers using SMB or SysV unless they are set up as BSD printers. Parameters ---------- filename - [optional] absolute path to the file you wish to print. printer - [optional] Name of the printer you wish to print to. Default "lp". server - [optional] Name of the server that is running lpd/lpsched. Default "localhost". port - [optional] The port you wish to connect to. Default "515". lineconvert - [optional] Perform LF -> LF/CR translation. Default "NO" Functions --------- I prints a specified file to the printer. Returns a 1 on success, otherwise returns a string containing the error. I prints a specified string to the printer. Returns a 1 on success, otherwise returns a string containing the error. I returns the current status of the print queue. I recommend waiting a short period of time between printing and issueing a queuestatus to give your spooler a chance to do it's thing. 5 seconds tends to work for me. NOTES ===== When printing text, if you have the infamous "stair-stepping" problem, try setting lineconvert to "YES". This should, in most cases, rectify the problem. AUTHOR ====== C. M. Fuhrman, cfuhrman@tfcci.com SEE ALSO ======== Socket, lpr(1), lp(1), perl(1).  File: pm.info, Node: Lingua/AM/Abbreviate, Next: Lingua/Conjunction, Prev: LinePrinter, Up: Module List Expand or Contract Amharic Abbreviations **************************************** NAME ==== AM::Abbreviate - Expand or Contract Amharic Abbreviations SYNOPSIS ======== use Lingua::AM::Abbreviate; while ( $string = <> ) { # some UTF8 string if ( $contracted = Contract ( $string ) ) { print "$string => $contracted\n"; } elsif ( $expanded = Expand ( $string ) ) { print "$string => $expanded\n"; } } DESCRIPTION =========== AM::Abbreviate provides two routines, "Expand" and "Contract", to assist in Amharic translation or spell checking. Each routine expects an Amharic string in UTF8 encoding as an argument and returns an expansion or contraction if found. AUTHOR ====== Daniel Yacob, `LibEth@EthiopiaOnline.Net|mailto:LibEth@EthiopiaOnline.Net' in this node SEE ALSO ======== perl(1). Ethiopic(3), `http:' in this node  File: pm.info, Node: Lingua/Conjunction, Next: Lingua/DetectCharset, Prev: Lingua/AM/Abbreviate, Up: Module List Convert Perl lists into linguistic conjunctions *********************************************** NAME ==== Lingua::Conjunction - Convert Perl lists into linguistic conjunctions SYNOPSIS ======== use Lingua::Conjunction; # emits "Jack" $name_list = conjunction('Jack'); # emits "Jack and Jill" $name_list = conjunction('Jack', 'Jill'); # emits "Jack, Jill, and Spot" $name_list = conjunction('Jack', 'Jill', 'Spot'); # emits "Jack, a boy; Jill, a girl; and Spot, a dog" $name_list = conjunction('Jack, a boy', 'Jill, a girl', 'Spot, a dog'); # emits "Jacques, un garcon; Jeanne, une fille; et Spot, un chien" Lingua::Enlist->lang('fr'); $name_list = conjunction('Jacques, un garcon', 'Jeanne, une fille', 'Spot, un chien'); DESCRIPTION =========== Lingua::Conjunction exports a single subroutine, `conjunction', that converts a list into a properly punctuated text string. You can cause `conjunction' to use the connectives of other languages, by calling the appropriate subroutine: Lingua::Conjunction->lang('en'); # use 'and' (default) Lingua::Conjunction->lang('es'); # use 'y' Supported languages in this version are English, Spanish, French, Italian, German, Portuguese, Norwiegian, and Danish. You can also set connectives individually: Lingua::Conjunction->separator("..."); Lingua::Conjunction->separator_phrase("--"); Lingua::Conjunction->connector_type("or"); # emits "Jack... Jill... or Spot" $name_list = conjunction('Jack', 'Jill', 'Spot'); The "separator_phrase" is used whenever the separator already appears in an item of the list. For example: # emits "Doe, a deer; Ray; and Me" $name_list = conjunction('Doe, a deer', 'Ray', 'Me'); REVISION HISTORY ================ Originally this modules was uploaded to CPAN as `Text::List'. After some criticism, this module was renamed. As per suggestions, other features were added. Probably too many features for what amounts to a simple hack. SEE ALSO ======== Locale::Language AUTHORS ======= Robert Rothenberg Damian Conway  File: pm.info, Node: Lingua/DetectCharset, Next: Lingua/EN/AddressParse, Prev: Lingua/Conjunction, Up: Module List Routine for automatically detecting cyrillic charset. ***************************************************** NAME ==== Lingua::DetectCharset - Routine for automatically detecting cyrillic charset. SYNOPSIS ======== use Lingua::DetectCharset; $Charset = Lingua::DetectCharset::Detect ($Buffer); The returned $Ecoding is either 'WIN', 'KOI8' or 'ENG'. The last is return when no single cyrillic token are found in buffer. DESCRIPTION =========== This package implements routine for detection charset of the given text snippet. Snippet may contain anything from few words to many kilobytes of text, and may have line breaks, English text and html tags embedded. This routine is implemented using algorithm of statistical analysis of text, which was proved to be very efficient and showed around *99.98% acccuracy* in tests. AUTHOR ====== John Neystadt SEE ALSO ======== perl(1), Convert::Cyrillic(3). NOTES ===== Part of "WWW Cyrillic Encoding Suite" Get docs and newest version from http://www.neystadt.org/cyrillic/ Copyright (c) 1997-98, John Neystadt You may install this script on your web site for free To obtain permision for redistribution or any other usage contact john@neystadt.org. Drop me a line if you deploy this script on your site.  File: pm.info, Node: Lingua/EN/AddressParse, Next: Lingua/EN/Fathom, Prev: Lingua/DetectCharset, Up: Module List manipulate geographical addresses ********************************* NAME ==== Lingua::EN::AddressParse - manipulate geographical addresses SYNOPSIS ======== use Lingua::EN::AddressParse; my %args = ( country => 'Australia', auto_clean => 1, force_case => 1 ); my $address = new Lingua::EN::AddressParse(%args); $error = $address->parse("14A MAIN RD. ST JOHNS WOOD NSW 2000"); %my_address = $address->components; $suburb = $my_address{suuburb}; $correct_casing = $address->case_all; REQUIRES ======== Perl, version 5.001 or higher, Lingua::EN::NameParse and Parse::RecDescent DESCRIPTION =========== This module takes as input an address or post box in free format text such as, 12/3-5 AUBREY ST VERMONT VIC 3133 "OLD REGRET" WENTWORTH FALLS NSW 2782 AUSTRALIA 2A LOW ST. KEW NSW 2123 GPO Box K318, HAYMARKET, NSW 2000 and attempts to parse it. If successful, the address is broken down into components and useful functions can be performed such as : converting upper or lower case values to name case (2 Low St. Kew NSW 2123 ) extracting the addresses individual components (2,Low St.,KEW,NSW,2123 ) determining the type of format the address is in ('suburban') If the address cannot be parsed you have the option of cleaning the address of bad characters, or extracting any portion that was parsed and the portion that failed. This module can be used for analysing and improving the quality of lists of addresses. DEFINITIONS =========== The following terms are used by AddressParse to define the components that can make up an address or post box. Post Box - GP0 Box K123, LPO 2345, RMS 23 ... Property Identifier Sub property description - Level, Unit, Apartment, Lot ... Property number - 12/66A, 24-34, 2A, 23B/12C, 12/42-44 Property name - "Old Regret" Street Street name - O'Hare, New South Head, The Causeway Street type - Road, Rd., St, Lane, Highway, Crescent, Circuit ... Suburb - Dee Why, St. John's Wood ... State - NSW, ACT, NY, AZ ... Post code - 2062, 34532, SG12A 9ET Country - Australia, UK, Papua New Guinea .... Refer to the component grammar defined within the code for a complete list of combinations. The following address formats are currently supported : 'suburban' - property_identifier street suburb state post_code country(?) 'post_box' - post_box suburb_subcountry post_code country(?) 'rural' - property_name suburb_subcountry post_code country(?) METHODS ======= new --- The new method creates an instance of an address object and sets up the grammar used to parse addresses. This must be called before any of the following methods are invoked. Note that the object only needs to be created once, and can be reused with new input data. Various setup options may be defined in a hash that is passed as an optional argument to the new method. my %args = ( country => 'Australia', auto_clean => 1, force_case => 1 ); my $address = new Lingua::EN::AddressParse(%args); country ....... The country argument must be specified. It determines the possible list of valid subcountries (states, counties etc, defined in the Locale::SubCountry module) and post code formats.The current list of coutries is Australia Brazil Canada Netherlands UK USA All forms of upper/lower case are acceptable in the country's spelling. If a country name is supplied that the module doesn't recognise, it will die. =head3 force_case This option will force the case_all method to address case the entire input string, including any unmatched sections that failed parsing. This option is useful when you know you data has invalid addresses, but you cannot filter out or reject them. auto_clean .......... When this option is set to a positive value, any call to the parse method that fails will attempt to 'clean' the address and then reparse it. See the clean method for details. This is useful for dirty data with embedded unprintable or non alphabetic characters. parse ----- $error = $address->parse("12/3-5 AUBREY ST VERMONT VIC 3133"); The parse method takes a single parameter of a text string containing a address. It attempts to parse the address and break it down into the components described above. If the address was parsed successfully, a 0 is returned, otherwise a 1. This step is a prerequisite for the following functions. case_all -------- $correct_casing = $address->case_all; The case_all method converts the first letter of each component to capitals and the remainder to lower case, with the following exceptions- Proper names capitalisation such as MacNay and O'Brien are observed The method returns the entire cased address as text. case_components --------------- %my_address = $address->components; $cased_suburb = $my_address{suburb}; The case_components method does the same thing as the case_all method, but returns the addresses cased components in a hash. The following keys are used for each component- post_box property_identifier property_name street suburb post_code country Entries only occur in the hash for each component that the currently parsed address contains, meaning there are no keys with undefined values. components ---------- %address = $address->components; $surburb = $address{suburb}; The components method does the same thing as the case_components method, but each component is returned as it appears in the input string, with no case conversion. properties ---------- The properties method return several properties of the address as a hash. type .... The type of format a name is in, as one of the following strings: suburban rural post_box unknown non_matching ............ Returns any unmatched section that was found. LIMITATIONS =========== The huge number of character combinations that can form a valid address makes it is impossible to correctly identify them all. Valid addresses must contain a suburb, subcountry (state) and post code, in that order. This format is widely accepted in Australia and the US. UK addresses will often include suburb, town, city and county, formats that are very difficult to parse. Subcountries must be in abbreviated form such as NSW, VIC, NY, CA, LEICS. I could add a pre-parse step to detect and abbreivate subcountry names, so data sych as "New South Wales" can be parsed. Property names must be enclosed in quotes like "Old Regret" Because of the large combination of possible addresses defined in the grammar, the program is not very fast. REFERENCES ========== "The Wordsworth Dictionary of Abbreviations & Acronyms" (1997) Australian Standard AS4212-1994 "Geographic Information Systems - Data Dictionary for transfer of street addressing information" FUTURE DIRECTIONS ================= Define grammar for other languages. Hopefully, all that would be needed is to specify a new module with its own grammar, and inherit all the existing methods. I don't have the knowledge of the naming conventions for non-english languages. SEE ALSO ======== Locale::Subcountry Lingua::EN::NameParse Parse::RecDescent TO DO ===== BUGS ==== CHANGES ======= 0.01 28 Dec 1999: First Release =head1 COPYRIGHT Copyright (c) 2000 Kim Ryan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html). AUTHOR ====== AddressParse was written by Kim Ryan in 2000.  File: pm.info, Node: Lingua/EN/Fathom, Next: Lingua/EN/Gender, Prev: Lingua/EN/AddressParse, Up: Module List readability and general measurements of English text **************************************************** NAME ==== Lingua::EN::Fathom - readability and general measurements of English text SYNOPSIS ======== use Lingua::EN::Fathom; my $text = new Lingua::EN::Fathom; $text->analyse_file("sample.txt"); $accumulate = 1; $text->analyse_block($text_string,$accumulate); $num_chars = $text->num_chars; $num_words = $text->num_words; $num_sentences = $text->num_sentences; $num_text_lines = $text->num_text_lines; $num_blank_lines = $text->num_blank_lines; $num_paragraphs = $text->num_paragraphs; %words = $text->unique_words; foreach $word ( sort keys %words ) { print("$words{$word} :$word\n"); } $fog = $text->fog; $flesch = $text->flesch; $kincaid = $text->kincaid; print($text->report); REQUIRES ======== Perl, version 5.001 or higher, Lingua::EN::Syllable DESCRIPTION =========== This module analyses English text in either a string or file. Totals are then calculated for the number of characters, words, sentences, blank and non blank (text) lines and paragraphs. Three common readability statistics are also derived, the Fog, Flesch and Kincaid indices. All of these properties can be accessed through individual methods, or by generating a text report. A hash of all unique words and the number of times they occur is generated. METHODS ======= new --- The new method creates an instance of an text object This must be called before any of the following methods are invoked. Note that the object only needs to be created once, and can be reused with new input data. my $text = new Lingua::EN::Fathom; analyse_file ------------ The analyse_file method takes as input the name of a text file. Various text based statistics are calculated for the file. This method and analyse_block are prerequisites for all the following methods. An optional argument may be supplied to control accumualtion of statisitics. If set to a non zero value, all statistics are accumulated with each successive call. analyse_block ------------- The analyse_block method takes as input the name of a text file. Various text based statistics are calculated for the file. This method and analyse_file are prerequisites for all the following methods. An optional argument may be supplied to control accumualtion of statisitics. If set to a non zero value, all statistics are accumulated with each successive call. num_chars --------- Returns the number of characters in the analysed text file or block. This includes characters such as spaces, and punctuation marks. num_words --------- Returns the number of words in the analysed text file or block. A word must consist of letters a-z with at least one vowel sound, and optionally an apostrophe or hyphen. Items such as "&, K108, NSW" are not counted as words. num_sentences ------------- Returns the number of sentences in the analysed text file or block. A sentence is any group of words and non words terminated with a single full stop. Spaces may occur before and after the full stop. num_text_lines -------------- Returns the number of lines containing some text in the analysed text file or block. num_blank_lines --------------- Returns the number of lines NOT containing any text in the analysed text file or block. num_paragraphs -------------- Returns the number of paragraphs in the analysed text file or block. READABILITY ----------- Three indices of text readability are calculated. They all measure complexity as a function of syllables per word and words per sentence. They assume the text is well formed and logical. You could analyse a passage of nonsensical English and find the readability is quite good, provided the words are not too complex and the sentences not too long. For more information see: http://www.plainlanguage.com/Resources/readability.html fog --- Returns the Fog index for the analysed text file or block. words_per_sentence + percent_complex_words ) * 0.4 The Fog index, developed by Robert Gunning, is a well known and simple formula for measuring readability. The index indicates the number of years of formal education a reader of average intelligence would need to read the text once and understand that piece of writing with its word sentence workload. 18 unreadable 14 difficult 12 ideal 10 acceptable 8 childish flesch ------ Returns the Flesch reading ease score for the analysed text file or block. 206.835 - (1.015 * words_per_sentence) - (84.6 * syllables_per_word) This score rates text on a 100 point scale. The higher the score, the easier it is to understand the text. A score of 60 to 70 is considered to be optimal. kincaid ------- Returns the Flesch-Kincaid grade level score for the analysed text file or block. (11.8 * syllables_per_word) + (0.39 * words_per_sentence) - 15.59; This score rates text on U.S. grade school level. So a score of 8.0 means that the document can be understood by an eighth grader. A score of 7.0 to 8.0 is considered to be optimal. unique_words ------------ Returns a hash of unique words. The words (in lower case) are held in the hash keys while the number of occurrences are held in the hash values. report ------ print($text->report); Produces a text based report containing the following statistics for the currently analysed text block or file: Number of characters Number of words Average syllables per word Number of sentences Average words per sentence Number of text lines Number of blank lines Number of paragraphs Fog Index Flesch Index Flesch-Kincaid Index The return value is a string containing the report contents SEE ALSO ======== Lingua::EN::Syllable B::Fathom POSSIBLE EXTENSIONS =================== Analyse many files at once Analyse HTML and other formats Allow user control over what strictly defines a word Provide a density measure of white space to characters LIMITATIONS =========== Common abbreviations such as St. or Pty. Ltd. will trick the module into inflating the number of sentences it finds. The syllable count provided in Lingua::EN::Syllable is about 90% accurate Acronyms that contain vowels, like GPO, will be counted as words. The fog index should exclude proper names BUGS ==== COPYRIGHT ========= Copyright (c) 2000-1 Kim Ryan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html). AUTHOR ====== Lingua::EN::Fathom was written by Kim Ryan in 2000.  File: pm.info, Node: Lingua/EN/Gender, Next: Lingua/EN/Hyphenate, Prev: Lingua/EN/Fathom, Up: Module List Inflect pronouns for gender *************************** NAME ==== Lingua::EN::Gender - Inflect pronouns for gender SYNOPSIS ======== use Lingua::EN::Gender; print &genders(); if (&is_valid_gender("male")) { ... DESCRIPTION =========== Small module for inflecting pronouns for a bunch of different genders. Genders currently supported are: neuter male female either spivak splat plural egotistical royal 2nd sie/hir zie/zir FUNCTIONS ========= pronoun ( TYPE, GENDER ) Returns the appropriate pronoun word for that pronoun type and gender. The types (examples for the male gender in brackets) are: subjective ("he") objective ("him") posessive-subjective ("his") posessive-objective ("his") reflexive ("himself") Simply returns an array containing all the valid genders. Returns true/false depending if the argument is a gender we know about. Case is not significant. AUTHOR ====== Bek Oberin COPYRIGHT ========= Copyright (c) 1999 Bek Oberin. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Lingua/EN/Hyphenate, Next: Lingua/EN/Infinitive, Prev: Lingua/EN/Gender, Up: Module List Perl extension for syllable-based hyphenation ********************************************* NAME ==== Lingua::En::Hyphenate - Perl extension for syllable-based hyphenation SYNOPSIS ======== use Lingua::En::Hyphenate; DESCRIPTION =========== AUTHOR ======  File: pm.info, Node: Lingua/EN/Infinitive, Next: Lingua/EN/Inflect, Prev: Lingua/EN/Hyphenate, Up: Module List Determine the infinitive form of a conjugated word ************************************************** NAME ==== `Lingua::EN::Infinitive' - Determine the infinitive form of a conjugated word SYNOPSIS ======== use Lingua::EN::Infinitive; my($spell) = Lingua::EN::Infinitive -> new(); my($word) = 'rove'; # Method 1: my($word1, $word2, $suffix, $rule) = $spell -> stem($word); # Method 2: $spell -> stem($word); my($word1, $word2, $suffix, $rule) = ( $spell -> {'word1'}, # A possibility. $spell -> {'word2'}, # A possibility, or ''. $spell -> {'suffix'}, $spell -> {'rule'}, ); print "Conjugated: $word. Infinitive: $word1. \n"; DESCRIPTION =========== Determine the infinitive form of a conjugated word. Also, determine the suffix used to identify which rule to apply to transform the conjugated word into the infinitive form. Either 1 or 2 possible infinitives are returned. You must check that the first is really an English word. If it is, then it is the result. If it is not valid, then check the second. Failure to deconjugate is indicated by $word1 eq ". In general, you can ignore the 3rd and 4th values returned from stem(). The algorithm is based on McIlroy's article (see below), after first checking for irregular words. In the hash 'suffix2Rule', you'll see the key 'order'. This specifies the sort order in which to check McIlroy's rules. I've changed his ordering in a number of places. INSTALLATION ============ You install `Lingua::EN::Infinitive', as you would install any perl module library, by running these commands: perl Makefile.PL make make test make install If you want to install a private copy of `Lingua::EN::Infinitive' in your home directory, then you should try to produce the initial Makefile with something like this command: perl Makefile.PL LIB=~/perl or perl Makefile.PL LIB=C:/Perl/Site/Lib If, like me, you don't have permission to write man pages into unix system directories, use: make pure_install instead of make install. This option is secreted in the middle of p 414 of the second edition of the dromedary book. WARNING ======= Don't make the false assumption that "$word1$suffix" eq $word or "$word2$suffix" eq $word REFERENCE ========= Title: Development of a Spelling List Author: M. Douglas McIlroy Journal: IEEE Transactions on Communications Issue: Vol COM-30, No 1, January 1982 AUTHOR ====== `Lingua::EN::Infinitive' was written by Ron Savage ** in 1998. LICENCE ======= This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.