This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: News/Scan/Thread, Next: Newt, Prev: News/Scan/Poster, Up: Module List keep track of threads in a Usenet newsgroup ******************************************* NAME ==== News::Scan::Thread - keep track of threads in a Usenet newsgroup SYNOPSIS ======== use News::Scan::Thread; my $thr = News::Scan::Thread->new($news_scan_article_obj); DESCRIPTION =========== This module provides a class whose objects can be used to keep track of threads of discussion in a Usenet newsgroup. CONSTRUCTOR =========== new ( ARTICLE ) `ARTICLE' should be a `News::Scan::Article' object or an object of some class derived from `News::Scan::Article'. new performs some initialization and returns a `News::Scan::Thread'. METHODS ======= subject Returns this thread's subject. volume Returns the volume in bytes generated in this thread. articles Returns the number of posts to this thread. header_volume Returns the volume in bytes of the headers in this thread's articles. header_lines Returns the number of header lines in this thread's articles. body_volume Returns the volume in bytes of the message bodies of this thread's articles. body_lines Returns the number of lines in this thread's message bodies. orig_volume Returns the volume in bytes of the original content of this thread's articles. orig_lines Returns the number of original lines in this thread's articles. sig_volume Returns the volume in bytes of the signatures of this thread's articles. sig_lines Returns the number of signature lines in this thread's articles. SEE ALSO ======== *Note News/Scan: News/Scan,, *Note News/Scan/Article: News/Scan/Article, AUTHOR ====== Greg Bacon COPYRIGHT ========= Copyright (c) 1997 Greg Bacon. All Rights Reserved. This library is free software. You may distribute and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Newt, Next: No/Dato, Prev: News/Scan/Thread, Up: Module List Perl bindings for RedHat newt library ************************************* NAME ==== Newt - Perl bindings for RedHat newt library SYNOPSIS ======== use Newt; Newt::Init(); Newt::Cls(); #A lot of Newt operations... Newt::Finished(); DESCRIPTION =========== The Newt module implements perl bindings for the RedHat newt windowing system, a terminal-based window and widget library for writing applications with a simple, but user friendly, interface. Basic Newt functions ==================== `Newt::Init()' Starts Newt services. You must use this command first. `Newt::Finished()' Ends Newt services. `Newt::Cls()' Clears the background. `Newt::Refresh()' Foreces an inmediate update of the modified portions of the screen. `Newt::Bell()' Sends a beep to the terminal. `Newt::GetScreenSize()' Returns a tuple containing the screen dimensions. Keyboard input ============== `Newt::WaitForKey()' Stops program execution until a key is pressed. `Newt::ClearKeyBuffer()' Discards the contents of the terminal's input buffer without waiting for additional input. Drawing text on the root window =============================== `Newt::DrawRootText($left, $top, $text)' Displays the text in the indicated position. `Newt::PushHelpLine($text)' Saves the current help line on a stack and displays the new line. If the text is null, Newt's default help line is displayed. If text is a string of length 0, the help line is cleared. `Newt::PopHelpLine()' Replaces the current help line with the previous one. It is important not to pop more lines than the ones pushed. Suspending Newt applications ============================ By default, Newt programs cannot be suspended by the user. Instead, programs can specify a callback function which gets invoked whe the user presses the suspend key. To register such function, you can do something like this: sub my_cb { ... } Newt::SetSuspendCallback(\&my_cb); If the application should suspend and continue like most user applications, the suspend callback needs two other newt functions: Newt::Suspend(); Newt::Resume(); The first one tells Newt to return the terminal to its initial state. Once this is done, the application can suspend itself by sending SIGSTP, fork a child program or whatever. When it wants to resume using the Newt interface, is must call `Newt::Resume()' before doing so. For more information on suspending newt applications, read the original newt documentation. Components ========== Components are the basic blocks for construction of Newt interfaces. They all are created in a similar manner. You just have to call the constructor to receive a blessed object of the specified class: $object = Newt::Foo(); Once you have a component, you can add it to a panel to create a complex user input interface. General component manipulation ------------------------------ You can attach a callback for a component like this: sub comp_cb { ... } $component->AddCallback(\%comp_cb); Exactly when (if ever) the callback is invoked depens on the type of the component. Yo can tell if a component takes or not focus when traversing a form with the following function: $component->TakesFocus($true_or_false); It is handy to set some arbitrary information on a component for later retrieval. You do this by setting its tag: $button->Tag("OK"); If you call this function without an argument, it replies with the actual tag for that component. In general when the return value of any method of a component isn't described the method returns the component itself to allow contructions like: $panel ->Add(0,0, $componet1->Set( .... ) ) ->Add(0,1, Newt::Label( .... ) ) ->Add(0,2, Newt::Panel( .... ) ->Add( .... ) ->Add( .... ) ) ->Add( .... ); Buttons ------- There are two kinds of buttons: full and compact: $normal_button = Newt::Button($text); $compact_button = Newt::CompactButton($text); Labels ------ Labels are quite simple: $label = Newt::Label($text); You can set the text of an existing label like this: $label->Set($text); Entry boxes ----------- Entry boxes are used to enter text: $entry = Newt::Entry($width, $flags, $initial_text); The initial text is optional. After an entry has been created, it's contents can be set by using: $entry->Set($text, $cursor_at_end); The last parameter is optional, and signals if the cursor should be moved to the end of the new value. To get the current value of the entry box, you do this: $entry->Get(); You can filter the characters that may be entered by using a callback filter like this: sub my_filter { my ($proposed_char, $cursor_position) = @_; ... return(0) if $char_shoud_be_ignored; return($proposed_char) # Accept the char } $entry->SetFilter(\&my_filter); As can be seen, filter callbacks receive a char and an integer which indicates the position that the proposed char would take on the entry. The filter function can return the very same char to indicate that it was accepted, but it can also return another char, to actually substitute the original one. If the filter wants to simply reject the keystroke, it only returns 0. When an entry is created, some flags may be specified. The flags are the following and may be `OR'ed: `NEWT::NEWT_ENTRY_SCROLL' If not specified, the user cannot enter text into the entry box which is wider than the entry box itself. This flag removes this limitation, and lets the user enter data of an arbitrary length. `NEWT::NEWT_FLAG_HIDDEN' If specified, the value of the entry is not displayed. Useful when an applications needs a password. `NEWT::NEWT_FLAG_RETURNEXIT' When specified, the entry will cause the form to stop running if the user pressed return inside the entry box. Nice shortcut for users. Checkboxes ---------- Newt checkboxes are peculiar, since may have more than two states. To create a normal one (checked or unchecked), do this: $check = Newt::Checkbox("Normal checkbox"); But you can create, for example, a checkbox that switches form not checked to checked with an asterisk and then to checked with an 'M': $check = Newt::Checkbox("Normal checkbox", " ", " *M"); As you can see, you can use the two optional parameters to tell the default char first and then the possible chars. To know if a checkbox is checked after the for is ran, you use the following: print "Is checked\n" if $check->Checked(); And you can always get the actual state like this: $state = $check->Get(); Radio groups ------------ You create two kinds of radio button groups, vertical and horizontal, by doing this: $radio_group1 = Newt::VRadiogroup('Red', 'Green', 'Blue'); $radio_group2 = Newt::HRadiogroup('Red', 'Green', 'Blue'); You can put any number of options and the first one will always be preselected. To know the index of the selected option after the form has run, you do this: $index = $radio_group->Get(); Listboxes --------- Listboxes are the most complicated components Newt provides. They can allow single or multiple selection, and are easy to update. They are created as follows: $listbox = Newt::Listbox($height, $flags); A listbox is created at a certain position and a given height. The $height is used for two things. First of all, it is the minimum height the listbox will use. If there are less items in the listbox then the height, suggests the listbox will still take up that minimum amount of space. Secondly, if the listbox is set to be scrollable (by setting the `NEWT_FLAG_SCROLL' flag, $height is also the maximum height of the listbox. If the listbox may not scroll, it increases its height to display all of its items. The following flags may be used when creating a listbox: `NEWT_FLAG_SCROLL' The listbox should scroll to display all of the items it contains. `NEWT_FLAG_RETURNEXIT' When the user presses return on an item in the list, the form should return. `NEWT_FLAG_BORDER' A frame is drawn around the listbox, which can make it easier to see which listbox has the focus when a form contains multiple listboxes. `NEWT_FLAG_MULTIPLE' By default, a listbox only lets the user select one item in the list at a time. When this flag is specified, they may select multiple items from the list. Once a listbox has been created, items are appended to the bottom like this: $listbox->Append($item1, $item2, ...); Appending is not the only way to add items to the list. You can insert items in any position by telling the item that should be before with the following command: $listbox->Insert($before, $item1, $item2, ...); And you can change any item just by telling: $listbox->Set($original, $new); Of course you can delete entries: $listbox->Delete($item1, $item2, ...); Or just clear out the listbox: $listbox->Clear(); You can select and unselect items, with the following: $listbox->Select($item1, $item2, ...); $listbox->Unselect($item1, $item2, ...); $listbox->ClearSelection(); but if you did not sepecify the flag `NEWT_FLAG_MULTIPLE' when constructing your listbox, only the last item on the argument list of `Unselect()' will remain selected. To get a list of the selected items, just issue: @selected_items = $listbox->Get(); Scales ------ Scales provide an easy way for telling the user the advance on some lengthy operation. It is a horizontal bar graph which the application updates as the operation continues: $scale = Newt::Scale($width, $fullvalue); It is set as expected: $scale->Set($amount); Textboxes --------- A text box is used for displaying large amounts of text. They are created as follows: $textbox = Newt::Textbox($width, $height, $flags, $text, ...); The $text parameter is optional, and if not supplied, the textbox is created only, but it does not fill it with data. To do so, use: $textbox->Set($text, ...); All the arguments are simply concatenated using the double quote operator. The flags that can be passed to the cronstuctor are the following: `NEWT_FLAG_WRAP' All text in the textbox should be wrapped to fit the width of the textbox. If this flag is not specified, each newline delimited line in the text is truncated if it is too long to fit. When Newt wraps text, it tries not to break lines on spaces or tabs. Literal newline characters are respected, and may be used to force line breaks. `NEWT_FLAG_SCROLL' The text shoud be scrollable. When this option is used, the scrollbar which is added increases the width of the area used by the textbox by 2 characters. Reflowing text -------------- When applications need to display large amounts of text, it is common not to know exactly where the linebreaks should go. While textboxes are quite willing to scroll the text, the programmer still must know what width the text will look "best" at (where "best" means most exactly rectangular; no lines much shorter or much longer then the rest). This common is specially prevalent in internationalized programs, which need to make a wide variety of message string look good on a screen. To help with this, Newt provides routines to reformat text to look good. It tries different widths to figure out which one will look "best" to the user. As these commons are almost always used to format text for textbox components, Newt makes it easy to construct a textbox with reflowed text. The following function reflows the provided text to a target width. the actual width of the longest line in the returned text is between `$width - $flexdown' and `$width + $flexup'; the actual maximum line length is chosen to make displayed text look rectangular. The function returns a tuple consisting of the reflowed text and the actual width and height of it. ($r_text, $width, $height) = Newt::ReflowText($width, $flexdown, $flexup, $text); When the reflowed text is being placed in a textbox it may be easier to use the following: $textbox = Newt::TextboxReflowed($width, $flexdown, $flexup, $flags, $text, ...); which creates a textbox, reflows the text, and places the reflowed text in the listbox. Its parameters consist of the position of the final textbox, the width and flex values for the text (which are identical to the parameters passed to `Newt::Reflow()', and the flags for the textbox (which are the same as the flags for CAdd(0, 0, $mycomponent); Several optional parameters my however be used when adding components: $panel1->Add($col, $row, $mycomponent, $anchor, $padleft, $padtop, $padright, $padbottom, $flag); You can specify the side of the cell to which the component will be aligned by specifying an anchor. The anchor values avalaible are `NEWT_ANCHOR_LEFT', `NEWT_ANCHOR_RIGHT', `NEWT_ANCHOR_TOP', `NEWT_ANCHOR_BOTTOM'. You can ask for more space on the sides of the component, perhaps to get a cleaner, less cluttered presentation using the padding parameters, and specifiying an integer value. Panels may be nested. For this to be done you only have to add a panel to another as you would with any other component. To run a panel as a toplevel and get user input, you may do the following: ($reason, $data) = $panel->Run(); if ($reason eq NEWT_EXIT_HOTKEY) { if ($data eq NEWT_KEY_F12) { print "F12 hotkey was pressed\n"; } else { print "Some hotkey other than F12 was pressed\n"; } } else { print 'Form terminated by button ', $data->Tag(), "\n"; } As can be seen on the example, when called in a list context `Run()' returns two values, one is the reason why the form terminated and the other is an associated data. In a scalar context only the data is returned. Posible values for the reason are: `NEWT_EXIT_HOTKEY' The form exited because a hotkey was pressed. The associated data contains the key pressed, that is, one of NEWT_KEY_* values. See Hotkeys later for more information. `NEWT_EXIT_COMPONENT' The form exited because a component was activated, a button, for instance a button. The associated data is a reference to the component involved. Hotkeys ------- Normally, a panel terminates when the user presses a button, but you can define some keys as "hotkeys" that will make the `Run()' function return with `NEWT_EXIT_HOTKEY'. Yo do this by issuing the folowing: $panel->AddHotKey(NEWT_KEY_F11); F12 is always defined to be a hotkey. Drawing panels instead uf running them -------------------------------------- When you run a panel the terminal is blocked until the user presses a component or a key that causes the panel to exit. Sometimes is useful to present the interface to the user without blocking the execution of code. This can be done by only drawing the panel, not running it. It is easy to show an advance status for a lengthy operation liek this: $i = 1; foreach (@items) { $label->Set("Processing item $i"); $panel->Draw(); $scale->Set($i); process_item($_); $i++ } Hiding panels ------------- Panels can be hidden in case you want by using the following: $panel->Hide() Constants ========= You can import all the constants exported by this package as needed qor using several predefined tags, with the folowing syntax: use Newt qw(:exits :keys); exits NEWT_EXIT_* constants keys NEWT_KEY_* constants anchors NEWT_ANCHOR_* constants colorsets NEWT_COLORSET_* constanst flags NEWT_FLAG_* constants entry NEWT_ENTRY_* constants fd NEWT_FD_* constants grid NEWT_GRID_* constants textbox NEWT_TEXTBOX_* constants macros macros to make useful buttons and panels: OK_BUTTON, CANCEL_BUTTON, QUIT_BUTTON, BACK_BUTTON, OK_CANCEL_PANEL, OK_BACK_PANEL. this macros only create componetnts which are properly tagged. TO DO ===== Scrollable panels. Some forms stuff, like watching file descriptors. SEE ALSO ======== *Writing programs using Newt*, by Eric Troan. THANKS TO ========= Eric Troan, for writing this useful library. Thanks for his tutorial, too, from where I stole complete paragraphs for this documentation, I'm afraid. AUTHOR ====== The original author of the RedHat newt library is Erik Troan, <*ewt@redhat.com*> The author of this Perl bindings is Alejandro Escalante Medina, <*amedina@msg.com.mx*> DATE ==== Version 0.1, 5th Nov 1998  File: pm.info, Node: No/Dato, Next: No/KontoNr, Prev: Newt, Up: Module List Norwegian dates *************** NAME ==== No::Dato - Norwegian dates SYNOPSIS ======== use No::Dato qw(tekstdato helligdag helligdager); print tekstdato(time), "\n"; if (helligdag(time)) { print "Idag er det ", helligdag(time), "\n"; } for (helligdager()) { print "$_\n"; } DESCRIPTION =========== *This documentation is written in Norwegian.* Denne modulen tilbyr funksjoner for å håndtere det som er spesielt med datoer på norsk. Dette gjelder blandt annet å finne fram til de norske helligdagene. Følgende funksjoner er tilgjengelig: tekstdato($time) Denne rutinen returnerer en dato formatert på formen: Fredag, 7. februar 1997 Argumentet er en vanlig perl $time verdi. Hvis argumentet utelates så benyttes dagens dato. helligdag($time) Rutinen avgjør om en gitt dato er en norsk helligdag eller ikke. Hvis det er en helligdag så vil navnet på helligdagen bli returnert. Hvis det er en vanlig hverdag så vil en tom streng (som er FALSE i perl) bli returnert. Argumentet kan være en vanlig $time verdi eller en streng på formen "ÅÅÅÅ-MM-DD". helligdager($year) Denne rutinen vil returnere en liste av datostrenger, én for hver helligdag i året gitt som argument. Hvis argumentet mangler vil vi bruke inneværende år. Datostrengene er på formen: "ÅÅÅÅ-MM-DD Skjærtorsdag" Dvs. datoen formattert i henhold til ISO 8601 etterfulgt av navnet på helligdagen. Listen vil være sortert på dato. SEE ALSO ======== *Note HTTP/Date: HTTP/Date,, som kan konvertere til og fra ISO 8601 formaterte datoer (ÅÅÅÅ-MM-DD). AUTHOR ====== Gisle Aas  File: pm.info, Node: No/KontoNr, Next: No/PersonNr, Prev: No/Dato, Up: Module List Check Norwegian bank account numbers ************************************ NAME ==== No::KontoNr - Check Norwegian bank account numbers SYNOPSIS ======== use No::KontoNr qw(kontonr_ok); if (personnr_ok($nr)) { # ... } DESCRIPTION =========== *This documentation is written in Norwegian.* Denne modulen kan brukes for å sjekke norske bankontonumre. Det siste sifferet i et banknummer er kontrollsiffer og må stemme overens med resten for at det skal være et gyldig nummer. Modulen inneholder også funksjoner for å regne ut modulus 10 og modulus 11 kontrollsiffer. Disse algoritmene brukes blandt annet hvis du vil generere KID når du skal fylle ut giroblanketter. De finnes også en fuksjon som kan brukes for å formatere kronebeløp. Ingen av funksjonene eksporteres implisitt. Du må be om dem. Følgende funksjoner er tilgjengelig: kontonr_ok($nr) Funksjonen kontonr_ok() vil returnere FALSE hvis kontonummeret gitt som argument ikke er gyldig. Hvis nummeret er gyldig så vil funksjonen returnere $nr på standard form (11 siffer for bankkontonummer og 7 siffer for gamle postgironummer) . Nummeret som gis til kontonr_ok() kan inneholde blanke eller punktumer. kontonr_f($nr) Funksjonen kontonr_f() vil formattere et kontonummer på standard form ("####.##.#####"). Hvis kontonummeret ikke er gyldig så byttes alle sifferene ut med "?". kredittkortnr_ok($nr) Funksjonen kredittkortnr_ok() vil returnere FALSE hvis kredittkortnummeret gitt som argument ikke er gyldig. Hvis nummeret er gyldig så vil funksjonen returnere kortselskapets navn. Nummeret som gis til kredittkortnr_ok() kan inneholde blanke eller punktumer. nok_f($tall) Denne funksjonen vil formatere tall på formen: 300,50 4.300,- Det skulle passe bra når man skal skrive ut kronebeløp. Ørebeløpet "00" byttes ut med strengen "- ", dvs. at tallene laines opp korrekt hvis du høyrejusterer dem. mod_10($tall) Denne funksjonen regner ut modulus 10 kontrollsifferet til tallet gitt som argument. Hvis argumentet inneholder tegn som ikke er siffer så ignoreres de. Modulus 10 algoritmen benyttes blandt annet for å generere kontrollsiffer til de fleste internasjonale kredittkortnummer. mod_11($tall) Denne funksjonen regner ut modulus 11 kontrollsifferet til tallet gitt som argument. Hvis argumentet inneholder tegn som ikke er siffer så ignoreres de. Når denne algoritmen benyttes så kan det være tall som det ikke finnes noe gyldig kontrollsiffer for, og da vil mod_11() returnere verdien undef. Modulus 11 algoritmen benyttes blandt annet for å generere kontrollsiffer til norske bankkontonummer. SEE ALSO ======== `Business::CreditCard' in this node AUTHOR ====== Gisle Aas  File: pm.info, Node: No/PersonNr, Next: No/Sort, Prev: No/KontoNr, Up: Module List Check Norwegian Social security numbers *************************************** NAME ==== No::PersonNr - Check Norwegian Social security numbers SYNOPSIS ======== use No::PersonNr qw(personnr_ok); if (personnr_ok($nr)) { # ... } DESCRIPTION =========== *This documentation is written in Norwegian.* Denne modulen kan brukes for å sjekke norske personnummer. De 2 siste siffrene i personnummerene er kontrollsiffre og må stemme overens med resten for at det skal være et gyldig nummer. Modulen inneholder også funksjoner for å bestemme personens kjønn og personens fødselsdato. Ingen av rutinene eksporteres implisitt. Du må be om dem. Følgende funksjoner er tilgjengelig: personnr_ok($nr) Funksjonen personnr_ok() vil returnere FALSE hvis personnummeret gitt som argument ikke er gyldig. Hvis nummeret er gyldig så vil funksjonen returnere $nr på standard form. Nummeret som gis til personnr_ok() kan inneholde ' ' eller '-'. er_mann($nr) Vil returnere TRUE hvis $nr tilhører en mann. Rutinen vil croake hvis nummeret er ugyldig. er_kvinne($nr) Vil returnere TRUE hvis $nr tilhører en kvinne. Rutinen vil croake hvis nummeret er ugyldig. fodt_dato($nr) Vil returnere personens fødselsdato på formen "ÅÅÅÅ-MM-DD". Rutinen returnerer "" hvis nummeret er ugyldig. BUGS ==== Denne koden vil få problemer for personer født etter år 2054. AUTHOR ====== Gisle Aas  File: pm.info, Node: No/Sort, Next: No/Telenor, Prev: No/PersonNr, Up: Module List Norwegian sorting ***************** NAME ==== No::Sort - Norwegian sorting SYNOPSIS ======== use No::Sort; @sortert = no_sort @norske_ord; DESCRIPTION =========== This module provde the function no_sort() which sort a ISO-8859/1 encoded string according to Norwegian practice. The routine works like the normal perl sort routine, but the optional first argument is special. It can either be a reference to the strxfrm() function to use while sorting or a reference to a hash used to transform the words while sorting. You can also import the no_xfrm() function which is used for standard sorting. It can be useful to base your custom transformation function on it. If we for instance would like to sort "Aa" as "Å" we could implement it like this: use No::Sort qw(no_sort no_xfrm); sub my_xfrm { my $word = shift; $word =~ s/A[aA]/Å/g; $word =~ s/aa/å/g; no_xfrm($word); } @sorted = no_sort \&my_xfrm, @names; By the way, the my_xfrm shown in this example can be imported from this module under the name 'no_aa_xfrm': use No::Sort qw(no_sort no_aa_xfrm); @sorted = no_sort \&no_aa_xfrm, @names; If you set the $No::Sort::DEBUG variable to a TRUE value, then we will make some extra noise on STDOUT while sorting. The module can also export functions for up/down casing ISO-8859/1 strings. These functions are called latin1_uc(), latin1_lc(), latin1_ucfirst(), latin1_lcfirst(). SEE ALSO ======== *Note Perllocale: (perl.info)perllocale, AUTHORS ======= Hallvard B Furuseth , Gisle Aas  File: pm.info, Node: No/Telenor, Next: Number/Encode, Prev: No/Sort, Up: Module List Calculate telephone call prices in Norway ***************************************** NAME ==== No::Telenor - Calculate telephone call prices in Norway SYNOPSIS ======== use No::Telenor qw(samtale_pris); $kr = samtale_pris($time, 3600, "N"); DESCRIPTION =========== *This documentation is written in Norwegian.* Denne modulen inneholder funksjonen samtale_pris(). Denne funksjonen vil beregne prisen på en telefonsamtale gitt tidspunkt, varighet og takst som parameter. Funksjonen kjenner til Telenors sanntidstakster som gjelder fra 1. juni 1999. Forhåpentligvis vil jeg klare å oppdater funksjonen etterhvert som Telenor finner på nye sprell. samtale_pris($start, $varighet, $takst) Rutinen vil beregne samtale prisen i NOK. Argumentet $start er starttidspunktet gitt som en standard perl 'time' verdi. Argumentet $varighet er samtalens varighet i sekunder. Argumentet $takst er en kort streng som forteller hvilken takst som skal brukes. Følgende takser er støttet: N Norgespris TM Telenor Mobil NC NetCom Mobil 180 Opplysningen 180 181 UtenlandsOpplysningen 181 BUGS ==== Prisberegningen kan bli unøyaktig hvis samtalen foregikk i overgangen mellom vinter- og sommertid eller omvendt. Prisberegningen tar ikke hensyn til at helgetakst skal benyttes på bevegelige helligdager. AUTHOR ====== Gisle Aas  File: pm.info, Node: Number/Encode, Next: Number/Format, Prev: No/Telenor, Up: Module List Encode bit strings into digit strings ************************************* NAME ==== Number::Encode - Encode bit strings into digit strings SYNOPSIS ======== use Number::Encode qw(nonuniform uniform); DESCRIPTION =========== Provides a mechanism to convert arbitrary bit-strings into numeric digit strings. The transformation can be uniform or non-uniform depending on the type of distribution of the numeric digits achieved. The former approach is useful for security-related applications such as calling cards and the such, which require a uniform digit distribution. The algorythm used to generate uniform distributions, while deterministic, is more constly than the non-uniform variant. This module is distributed under the same terms and warranty as Perl itself. EXPORT ------ This module provides the following exports: `my $number = nonuniform($data)' Converts a bit-string represented in the example by the scalar $data to a numeric string representation returned at `$number'. The probabilistic distribution of the digits in the resulting number is not uniform. Some digits will have up to twice the chance of others of appearing at a given position. `my $number = uniform($data)' Performs a transformation from the bit-string provided in $data to a numeric string returned at `$number'. This transformation is a bit more costly but has the advantage that the digit distribution is uniform. This function is adequate for applications that require a uniform composition of the numeric strings, such as password or PIN number generators. HISTORY ======= 1. Original version; created by h2xs 1.20 with options -ACOXfn Number::Encode -v 1.00 AUTHOR ====== Luis E. Munoz SEE ALSO ======== perl(1).  File: pm.info, Node: Number/Format, Next: Number/Latin, Prev: Number/Encode, Up: Module List Perl extension for formatting numbers ************************************* NAME ==== Number::Format - Perl extension for formatting numbers SYNOPSIS ======== use Number::Format; my $x = new Number::Format %args; $formatted = $x->round($number, $precision); $formatted = $x->format_number($number, $precision, $trailing_zeroes); $formatted = $x->format_negative($number, $picture); $formatted = $x->format_picture($number, $picture); $formatted = $x->format_price($number, $precision); $formatted = $x->format_bytes($number, $precision); $number = $x->unformat_number($formatted); use Number::Format qw(:subs); $formatted = round($number, $precision); $formatted = format_number($number, $precision, $trailing_zeroes); $formatted = format_negative($number, $picture); $formatted = format_picture($number, $picture); $formatted = format_price($number, $precision); $formatted = format_bytes($number, $precision); $number = unformat_number($formatted); REQUIRES ======== Perl, version 5.003 or higher. POSIX.pm will be used if present to determine locale settings. Carp.pm is used for some error reporting. DESCRIPTION =========== These functions provide an easy means of formatting numbers in a manner suitable for displaying to the user. There are two ways to use this package. One is to declare an object of type Number::Format, which you can think of as a formatting engine. The various functions defined here are provided as object methods. The constructor new() can be used to set the parameters of the formatting engine. Valid parameters are: THOUSANDS_SEP - character inserted between groups of 3 digits DECIMAL_POINT - character separating integer and fractional parts MON_THOUSANDS_SEP - like THOUSANDS_SEP, but used for format_price MON_DECIMAL_POINT - like DECIMAL_POINT, but used for format_price INT_CURR_SYMBOL - character(s) denoting currency (see format_price()) DECIMAL_DIGITS - number of digits to the right of dec point (def 2) DECIMAL_FILL - boolean; whether to add zeroes to fill out decimal NEG_FORMAT - format to display negative numbers (def ``-x'') KILO_SUFFIX - suffix to add when format_bytes formats kilobytes MEGA_SUFFIX - suffix to add when format_bytes formats megabytes They may be specified in upper or lower case, with or without a leading hyphen ( - ). The defaults for `THOUSANDS_SEP', `DECIMAL_POINT', `MON_THOUSANDS_SEP', `MON_DECIMAL_POINT', and `INT_CURR_SYMBOL' come from the POSIX locale information (see *Note Perllocale: (perl.info)perllocale,), if available. If your POSIX locale does not provide `MON_THOUSANDS_SEP' and/or `MON_DECIMAL_POINT' fields, then the `THOUSANDS_SEP' and/or `DECIMAL_POINT' values are used for those parameters. Some systems (e.g. Win32 ports of Perl) do not include POSIX support. In those systems, the POSIX system is bypassed. If any of the above parameters are not specified when you invoke new(), then the values are taken from package global variables of the same name (e.g. `$DECIMAL_POINT' is the default for the `DECIMAL_POINT' parameter). If you use the `:vars' keyword on your `use Number::Format' line (see non-object-oriented example below) you will import those variables into your namesapce and can assign values as if they were your own local variables. The default values for all the parameters are: THOUSANDS_SEP = ',' DECIMAL_POINT = '.' MON_THOUSANDS_SEP = ',' MON_DECIMAL_POINT = '.' INT_CURR_SYMBOL = 'USD ' DECIMAL_DIGITS = 2 DECIMAL_FILL = 0 NEG_FORMAT = '-x' KILO_SUFFIX = 'K' MEGA_SUFFIX = 'M' Note however that when you first call one of the functions in this module *without* using the object-oriented interface, further setting of those global variables will have no effect on non-OO calls. It is recommended that you use the object-oriented interface instead for fewer headaches and a cleaner design. The `DECIMAL_FILL' and `DECIMAL_DIGITS' values are not set by the Locale system, but are definable by the user. They affect the output of `format_number()'. Setting `DECIMAL_DIGITS' is like giving that value as the $precision argument to that function. Setting `DECIMAL_FILL' to a true value causes `format_number()' to append zeroes to the right of the decimal digits until the length is the specified number of digits. `NEG_FORMAT' is only used by `format_negative()' and is a string containing the letter 'x', where that letter will be replaced by a positive representation of the number being passed to that function. `format_number()' and `format_price()' utilize this feature by calling `format_negative()' if the number was less than 0. `KILO_SUFFIX' and `MEGA_SUFFIX' are used by `format_bytes()' when the value is over 1024 or 1024*1024, respectively. The default values are "K" and "M". The only restrictions on `DECIMAL_POINT' and `THOUSANDS_SEP' are that they must not be digits, must not be identical, and must each be one character. There are no restrictions on `INT_CURR_SYMBOL'. For example, a German user might include this in their code: use Number::Format; my $de = new Number::Format(-thousands_sep => '.', -decimal_point => ',', -int_curr_symbol => 'DEM'); my $formatted = $de->format_number($number); Or, if you prefer not to use the object oriented interface, you can do this instead: use Number::Format qw(:subs :vars); $THOUSANDS_SEP = '.'; $DECIMAL_POINT = ','; $INT_CURR_SYMBOL = 'DEM'; my $formatted = format_number($number); EXPORTS ======= Nothing is exported by default. To export the functions or the global variables defined herein, specify the function name(s) on the import list of the `use Number::Format' statement. To export all functions defined herein, use the special tag `:subs'. To export the variables, use the special tag `:vars'; to export both subs and vars you can use the tag :all. METHODS ======= new( %args ) Creates a new Number::Format object. Valid keys for %args are any of the parameters described above. Keys may be in all uppercase or all lowercase, and may optionally be preceded by a hyphen (-) character. Example: my $de = new Number::Format(-thousands_sep => '.', -decimal_point => ',', -int_curr_symbol => 'DEM'); round($number, $precision) Rounds the number to the specified precision. If $precision is omitted, the value of the `DECIMAL_DIGITS' parameter is used (default value 2). Both input and output are numeric (the function uses math operators rather than string manipulation to do its job), The value of $precision may be any integer, positive or negative. Examples: round(3.14159) yields 3.14 round(3.14159, 4) yields 3.1416 round(42.00, 4) yields 42 round(1234, -2) yields 1200 Since this is a mathematical rather than string oriented function, there will be no trailing zeroes to the right of the decimal point, and the `DECIMAL_POINT' and `THOUSANDS_SEP' variables are ignored. To format your number using the `DECIMAL_POINT' and `THOUSANDS_SEP' variables, use `format_number()' instead. format_number($number, $precision, $trailing_zeroes) Formats a number by adding `THOUSANDS_SEP' between each set of 3 digits to the left of the decimal point, substituting `DECIMAL_POINT' for the decimal point, and rounding to the specified precision using `round()'. Note that $precision is a maximum precision specifier; trailing zeroes will only appear in the output if `$trailing_zeroes' is provided, or the parameter `DECIMAL_FILL' is set, with a value that is true (not zero, undef, or the empty string). If $precision is omitted, the value of the `DECIMAL_DIGITS' parameter (default value of 2) is used. Examples: format_number(12345.6789) yields '12,345.68' format_number(123456.789, 2) yields '123,456.79' format_number(1234567.89, 2) yields '1,234,567.89' format_number(1234567.8, 2) yields '1,234,567.8' format_number(1234567.8, 2, 1) yields '1,234,567.80' format_number(1.23456789, 6) yields '1.234568' Of course the output would have your values of `THOUSANDS_SEP' and `DECIMAL_POINT' instead of ',' and '.' respectively. format_negative($number, $picture) Formats a negative number. Picture should be a string that contains the letter x where the number should be inserted. For example, for standard negative numbers you might use "-x", while for accounting purposes you might use "`(x)'". If the specified number begins with a "-" character, that will be removed before formatting, but formatting will occur whether or not the number is negative. format_picture($number, $picture) Returns a string based on `$picture' with the `#' characters replaced by digits from `$number'. If the length of the integer part of $number is too large to fit, the `#' characters are replaced with asterisks (*) instead. Examples: format_picture(100.023, 'USD ##,###.##') yields 'USD 100.02' format_picture(1000.23, 'USD ##,###.##') yields 'USD 1,000.23' format_picture(10002.3, 'USD ##,###.##') yields 'USD 10,002.30' format_picture(100023, 'USD ##,###.##') yields 'USD **,***.**' format_picture(1.00023, 'USD #.###,###') yields 'USD 1.002,300' The comma (,) and period (.) you see in the picture examples should match the values of `THOUSANDS_SEP' and `DECIMAL_POINT', respectively, for proper operation. However, the `THOUSANDS_SEP' characters in `$picture' need not occur every three digits; the *only* use of that variable by this function is to remove leading commas (see the first example above). There may not be more than one instance of `DECIMAL_POINT' in `$picture'. The value of `NEG_FORMAT' is used to determine how negative numbers are displayed. The result of this is that the output of this function my have unexpected spaces before and/or after the number. This is necessary so that positive and negative numbers are formatted into a space the same size. If you are only using positive numbers and want to avoid this problem, set NEG_FORMAT to "x". format_price($number, $precision) Returns a string containing `$number' formatted similarly to `format_number()', except that the decimal portion may have trailing zeroes added to make it be exactly $precision characters long, and the currency string will be prefixed. If the `INT_CURR_SYMBOL' attribute of the object is the empty string, no currency will be added. If $precision is not provided, the default of 2 will be used. Examples: format_price(12.95) yields 'USD 12.95' format_price(12) yields 'USD 12.00' format_price(12, 3) yields '12.000' The third example assumes that `INT_CURR_SYMBOL' is the empty string. format_bytes($number, $precision) Returns a string containing `$number' formatted similarly to `format_number()', except that if the number is over 1024, it will be divided by 1024 and "K" appended to the end; or if it is over 1048576 (1024*1024), it will be divided by 1048576 and "M" appended to the end. Negative values will result in an error. If $precision is not provided, the default of 2 will be used. Examples: format_bytes(12.95) yields '12.95' format_bytes(2048) yields '2K' format_bytes(1048576) yields '1M' unformat_number($formatted) Converts a string as returned by `format_number()', `format_price()', or `format_picture()', and returns the corresponding value as a numeric scalar. Returns undef if the number does not contain any digits. Examples: unformat_number('USD 12.95') yields 12.95 unformat_number('USD 12.00') yields 12 unformat_number('foobar') yields undef unformat_number('1234-567@.8') yields 1234567.8 The value of `DECIMAL_POINT' is used to determine where to separate the integer and decimal portions of the input. All other non-digit characters, including but not limited to `INT_CURR_SYMBOL' and `THOUSANDS_SEP', are removed. If the number matches the pattern of `NEG_FORMAT' or there is a "-" character before any of the digits, then a negative number is returned. If the number ends with the `KILO_SUFFIX' or `MEGA_SUFFIX' characters, then the number returned will be multiplied by 1024 or 1024*1024 as appropriate. BUGS ==== No known bugs at this time. Please report any problems to the author. AUTHOR ====== William R. Ward, wrw@bayview.com SEE ALSO ======== perl(1).  File: pm.info, Node: Number/Latin, Next: Number/Phone/US, Prev: Number/Format, Up: Module List convert to/from the number system "a,b,...z,aa,ab..." ***************************************************** NAME ==== Number::Latin - convert to/from the number system "a,b,...z,aa,ab..." SYNOPSIS ======== use Number::Latin; print join(' ', map int2latin($_), 1 .. 30), "\n"; # # Prints: # a b c d e f g h i j k l m n o p q r s t u v w x y z aa ab ac ad DESCRIPTION =========== Some applications, notably the numbering of points in outlines, use a scheme that starts with the letter "a", goes to "z", and then starts over with "aa" thru "az", then "ba", and so on. (The W3C refers to this numbering system as "lower-latin"/"upper-latin" or "lower alpha"/"upper alpha", in discussions of HTML/CSS options for rendering of list elements (OL/LI).) This module provides functions that deal with that numbering system, converting between it and integer values. FUNCTIONS --------- This module exports four functions, `int2latin', `int2Latin', `int2LATIN', and `latin2int': $latin = int2latin( INTEGER ) This returns the INTEGERth item in the sequence `('a' .. 'z', 'aa', 'ab', etc)'. For example, `int2latin(1)' is `"a"', `int2latin(2)' is `"b"', `int2latin(26)' is `"z"', `int2latin(30)' is `"ad"', and so for any nonzero integer. $latin = int2Latin( INTEGER ) This is just like `int2latin', except that the return value is has an initial capital. E.g., `int2Latin(30)' is `"Ad"'. $latin = int2LATIN( INTEGER ) This is just like `int2latin', except that the return value is in all uppercase. E.g., `int2LATIN(30)' is `"AD"'. $latin = latin2int( INTEGER ) This converts back from latin number notation (regardless of capitalization!) to an integer value. E.g., `latin2int("ad")' is 30. NOTES ===== The latin numbering system is not to be confused with Roman numerals, in spite of their names. The latin numbering system isn't a normal base-N number system (thus making this module necessary), as evidenced by the fact that the item after "z" is "aa". If you considered this to be a base-26 numbering system (running from a-z for 0-25), then after "z" would be "ba"; if you considered it a base-27 numbering system (running from a-z for 1-26), then after "z" would be "a" followed by some sort of placeholder zero. But it's neither. I vaguely remember reading, years ago, of some languages (in New Guinea?) with count-number systems that work like the latin number system - i.e., where either the number after "nine" is "one-MULT one", or the number after "ten" is "one-MULT one". However, I haven't been able to find a reference for exactly what language(s) those were number system; I welcome email on the subject. COPYRIGHT ========= Copyright (c) 1997- by Abigail, and 2001- Sean M. Burke. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== `Roman' in this node `http://www.w3.org/TR/REC-CSS2/generate.html#lists' `http://people.netscape.com/ftang/i18n.html' `http://people.netscape.com/ftang/number/draft.html' AUTHOR ====== Initial implementation in a `comp.lang.perl.misc' post by Abigail (`abigail@foad.org') in 1997. Documentation, further doings, and current maintenance by Sean M. Burke, `sburke@cpan.org'