This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Lingua/EN/Inflect, Next: Lingua/EN/MatchNames, Prev: Lingua/EN/Infinitive, Up: Module List Convert singular to plural. Select "a" or "an". *********************************************** NAME ==== Lingua::EN::Inflect - Convert singular to plural. Select "a" or "an". VERSION ======= This document describes version 1.86 of Lingua::EN::Inflect, released October 20, 2000. SYNOPSIS ======== use Lingua::EN::Inflect qw ( PL PL_N PL_V PL_ADJ NO NUM PL_eq PL_N_eq PL_V_eq PL_ADJ_eq A AN PART_PRES ORD NUMWORDS inflect classical def_noun def_verb def_adj def_a def_an ); # UNCONDITIONALLY FORM THE PLURAL print "The plural of ", $word, " is ", PL($word), "\n"; # CONDITIONALLY FORM THE PLURAL print "I saw $cat_count ", PL("cat",$cat_count), "\n"; # FORM PLURALS FOR SPECIFIC PARTS OF SPEECH print PL_N("I",$N1), PL_V("saw",$N1), PL_ADJ("my",$N2), PL_N("saw",$N2), "\n"; # DEAL WITH "0/1/N" -> "no/1/N" TRANSLATION: print "There ", PL_V("was",$errors), NO(" error",$errors), "\n"; # USE DEFAULT COUNTS: print NUM($N1,""), PL("I"), PL_V(" saw"), NUM($N2), PL_N(" saw"); print "There ", NUM($errors,''), PL_V("was"), NO(" error"), "\n"; # COMPARE TWO WORDS "NUMBER-INSENSITIVELY": print "same\n" if PL_eq($word1, $word2); print "same noun\n" if PL_eq_N($word1, $word2); print "same verb\n" if PL_eq_V($word1, $word2); print "same adj.\n" if PL_eq_ADJ($word1, $word2); # ADD CORRECT "a" OR "an" FOR A GIVEN WORD: print "Did you want ", A($thing), " or ", AN($idea), "\n"; # CONVERT NUMERALS INTO ORDINALS (i.e. 1->1st, 2->2nd, 3->3rd, etc.) print "It was", ORD($position), " from the left\n"; # CONVERT NUMERALS TO WORDS (i.e. 1->"one", 101->"one hundred and one", etc.) # IN A SCALAR CONTEXT: GET BACK A SINGLE STRING... $words = NUMWORDS(1234); # "one thousand, two hundred and thirty-four" # IN A LIST CONTEXT: GET BACK A LIST OF STRINGSi, ONE FOR EACH "CHUNK"... @words = NUMWORDS(1234); # ("one thousand","two hundred and thirty-four") # OPTIONAL PARAMETERS CHANGE TRANSLATION: $words = NUMWORDS(12345, group=>1); # "one, two, three, four, five" $words = NUMWORDS(12345, group=>2); # "twelve, thirty-four, five" $words = NUMWORDS(12345, group=>3); # "one twenty-three, forty-five" $words = NUMWORDS(1234, 'and'=>''); # "one thousand, two hundred thirty-four" $words = NUMWORDS(1234, 'and'=>', plus'); # "one thousand, two hundred, plus thirty-four" $words = NUMWORDS(555_1202, group=>1, zero=>'oh'); # "five, five, five, one, two, oh, two" $words = NUMWORDS(123.456, group=>1, decimal=>'mark'); # "one two three mark four five six" # REQUIRE "CLASSICAL" PLURALS (EG: "focus"->"foci", "cherub"->"cherubim") classical; # USE CLASSICAL PLURALS classical 1; # USE CLASSICAL PLURALS classical 0; # USE MODERN PLURALS (DEFAULT) # INTERPOLATE "PL()", "PL_N()", "PL_V()", "PL_ADJ()", A()", "AN()" # "NUM()" AND "ORD()" WITHIN STRINGS: print inflect("The plural of $word is PL($word)\n"); print inflect("I saw $cat_count PL("cat",$cat_count)\n"); print inflect("PL(I,$N1) PL_V(saw,$N1) PL(a,$N2) PL_N(saw,$N2)"); print inflect("NUM($N1,)PL(I) PL_V(saw) NUM($N2,)PL(a) PL_N(saw)"); print inflect("I saw NUM($cat_count) PL("cat")\nNUM()"); print inflect("There PL_V(was,$errors) NO(error,$errors)\n"); print inflect("There NUM($errors,) PL_V(was) NO(error)\n"; print inflect("Did you want A($thing) or AN($idea)\n"); print inflect("It was ORD($position) from the left\n"); # ADD USER-DEFINED INFLECTIONS (OVERRIDING INBUILT RULES): def_noun "VAX" => "VAXen"; # SINGULAR => PLURAL def_verb "will" => "shall", # 1ST PERSON SINGULAR => PLURAL "will" => "will", # 2ND PERSON SINGULAR => PLURAL "will" => "will", # 3RD PERSON SINGULAR => PLURAL def_adj "hir" => "their", # SINGULAR => PLURAL def_a "h" # "AY HALWAYS SEZ 'HAITCH'!" def_an "horrendous.*" # "AN HORRENDOUS AFFECTATION" DESCRIPTION =========== The exportable subroutines of Lingua::EN::Inflect provide plural inflections, "a"/"an" selection for English words, and manipulation of numbers as words Plural forms of all nouns, most verbs, and some adjectives are provided. Where appropriate, "classical" variants (for example: "brother" -> "brethren", "dogma" -> "dogmata", etc.) are also provided. Pronunciation-based "a"/"an" selection is provided for all English words, and most initialisms. It is also possible to inflect numerals (1,2,3) to ordinals (1st, 2nd, 3rd) and to english words ("one", "two", "three). In generating these inflections, Lingua::EN::Inflect follows the Oxford English Dictionary and the guidelines in Fowler's Modern English Usage, preferring the former where the two disagree. The module is built around standard British spelling, but is designed to cope with common American variants as well. Slang, jargon, and other English dialects are not explicitly catered for. Where two or more inflected forms exist for a single word (typically a "classical" form and a "modern" form), Lingua::EN::Inflect prefers the more common form (typically the "modern" one), unless "classical" processing has been specified (see `"MODERN VS CLASSICAL INFLECTIONS"' in this node). FORMING PLURALS =============== Inflecting Plurals ------------------ All of the `PL_...' plural inflection subroutines take the word to be inflected as their first argument and return the corresponding inflection. Note that all such subroutines expect the *singular* form of the word. The results of passing a plural form are undefined (and unlikely to be correct). The `PL_...' subroutines also take an optional second argument, which indicates the grammatical "number" of the word (or of another word with which the word being inflected must agree). If the "number" argument is supplied and is not 1 (or `"one"' or `"a"', or some other adjective that implies the singular), the plural form of the word is returned. If the "number" argument *does* indicate singularity, the (uninflected) word itself is returned. If the number argument is omitted, the plural form is returned unconditionally. The various subroutines are: `PL_N($;$)' The exportable subroutine `PL_N()' takes a *singular* English noun or pronoun and returns its plural. Pronouns in the nominative ("I" -> "we") and accusative ("me" -> "us") cases are handled, as are possessive pronouns ("mine" -> "ours"). `PL_V($;$)' The exportable subroutine `PL_V()' takes the *singular* form of a conjugated verb (that is, one which is already in the correct "person" and "mood") and returns the corresponding plural conjugation. `PL_ADJ($;$)' The exportable subroutine `PL_ADJ()' takes the *singular* form of certain types of adjectives and returns the corresponding plural form. Adjectives that are correctly handled include: "numerical" adjectives ("a" -> "some"), demonstrative adjectives ("this" -> "these", "that" -> "those"), and possessives ("my" -> "our", "cat's" -> "cats'", "child's" -> "childrens'", etc.) `PL($;$)' The exportable subroutine `PL()' takes a *singular* English noun, pronoun, verb, or adjective and returns its plural form. Where a word has more than one inflection depending on its part of speech (for example, the noun "thought" inflects to "thoughts", the verb "thought" to "thought"), the (singular) noun sense is preferred to the (singular) verb sense. Hence `PL("knife")' will return "knives" ("knife" having been treated as a singular noun), whereas `PL("knifes")' will return "knife" ("knifes" having been treated as a 3rd person singular verb). The inherent ambiguity of such cases suggests that, where the part of speech is known, `PL_N', `PL_V', and `PL_ADJ' should be used in preference to `PL'. Note that all these subroutines ignore any whitespace surrounding the word being inflected, but preserve that whitespace when the result is returned. For example, `PL(" cat ")' returns " cats ". Numbered plurals ---------------- The `PL_...' subroutines return only the inflected word, not the count that was used to inflect it. Thus, in order to produce "I saw 3 ducks", it is necessary to use: print "I saw $N ", PL_N($animal,$N), "\n"; Since the usual purpose of producing a plural is to make it agree with a preceding count, Lingua::EN::Inflect provides an exportable subroutine (`NO($;$)') which, given a word and a(n optional) count, returns the count followed by the correctly inflected word. Hence the previous example can be rewritten: print "I saw ", NO($animal,$N), "\n"; In addition, if the count is zero (or some other term which implies zero, such as `"zero"', `"nil"', etc.) the count is replaced by the word "no". Hence, if `$N' had the value zero, the previous example would print the somewhat more elegant: I saw no animals rather than: I saw 0 animals Note that the name of the subroutine is a pun: the subroutine returns either a number (a *No.*) or a "no", in front of the inflected word. Reducing the number of counts required -------------------------------------- In some contexts, the need to supply an explicit count to the various `PL_...' subroutines makes for tiresome repetition. For example: print PL_ADJ("This",$errors), PL_N(" error",$errors), PL_V(" was",$errors), " fatal.\n"; Lingua::EN::Inflect therefore provides an exportable subroutine (`NUM($;$)') which may be used to set a persistent "default number" value. If such a value is set, it is subsequently used whenever an optional second "number" argument is omitted. The default value thus set can subsequently be removed by calling `NUM()' with no arguments. Hence we could rewrite the previous example: NUM($errors); print PL_ADJ("This"), PL_N(" error"), PL_V(" was"), "fatal.\n"; NUM(); Normally, `NUM()' returns its first argument, so that it may also be "inlined" in contexts like: print NUM($errors), PL_N(" error"), PL_V(" was"), " detected.\n" print PL_ADJ("This"), PL_N(" error"), PL_V(" was"), "fatal.\n" if $severity > 1; However, in certain contexts (see `"INTERPOLATING INFLECTIONS IN STRINGS"' in this node) it is preferable that `NUM()' return an empty string. Hence `NUM()' provides an optional second argument. If that argument is supplied (that is, if it is defined) and evaluates to false, `NUM' returns an empty string instead of its first argument. For example: print NUM($errors,0), NO("error"), PL_V(" was"), " detected.\n"; print PL_ADJ("This"), PL_N(" error"), PL_V(" was"), "fatal.\n" if $severity > 1; Number-insensitive equality --------------------------- Lingua::EN::Inflect also provides a solution to the problem of comparing words of differing plurality through the exportable subroutines `PL_eq($$)', `PL_N_eq($$)', `PL_V_eq($$)', and `PL_ADJ_eq($$)'. Each of these subroutines takes two strings, and compares them using the corresponding plural-inflection subroutine (`PL()', `PL_N()', `PL_V()', and `PL_ADJ()' respectively). The comparison returns true if: * the strings are eq-equal, or * one string is eq-equal to a plural form of the other, or * the strings are two different plural forms of the one word. Hence all of the following return true: PL_eq("index","index") # RETURNS "eq" PL_eq("index","indexes") # RETURNS "s:p" PL_eq("index","indices") # RETURNS "s:p" PL_eq("indexes","index") # RETURNS "p:s" PL_eq("indices","index") # RETURNS "p:s" PL_eq("indices","indexes") # RETURNS "p:p" PL_eq("indexes","indices") # RETURNS "p:p" PL_eq("indices","indices") # RETURNS "eq" As indicated by the comments in the previous example, the actual value returned by the various `PL_eq_...' subroutines encodes which of the three equality rules succeeded: "eq" is returned if the strings were identical, "s:p" if the strings were singular and plural respectively, "p:s" for plural and singular, and "p:p" for two distinct plurals. Inequality is indicated by returning an empty string. It should be noted that two distinct singular words which happen to take the same plural form are not considered equal, nor are cases where one (singular) word's plural is the other (plural) word's singular. Hence all of the following return false: PL_eq("base","basis") # ALTHOUGH BOTH -> "bases" PL_eq("syrinx","syringe") # ALTHOUGH BOTH -> "syringes" PL_eq("she","he") # ALTHOUGH BOTH -> "they" PL_eq("opus","operas") # ALTHOUGH "opus" -> "opera" -> "operas" PL_eq("taxi","taxes") # ALTHOUGH "taxi" -> "taxis" -> "taxes" Note too that, although the comparison is "number-insensitive" it is not case-insensitive (that is, `PL("time","Times")' returns false. To obtain both number and case insensitivity, prefix both arguments with lc (that is, `PL(lc "time", lc "Times")' returns true). OTHER VERB FORMS ================ Present participles ------------------- `Lingua::EN::Inflect' also provides the `PART_PRES' subroutine, which can take a 3rd person singular verb and correctly inflect it to its present participle: PART_PRES("runs") # "running" PART_PRES("loves") # "loving" PART_PRES("eats") # "eating" PART_PRES("bats") # "batting" PART_PRES("spies") # "spying" PROVIDING INDEFINITE ARTICLES ============================= Selecting indefinite articles ----------------------------- Lingua::EN::Inflect provides two exportable subroutines (`A($;$)' and `AN($;$)') which will correctly prepend the appropriate indefinite article to a word, depending on its pronunciation. For example: A("cat") # -> "a cat" AN("cat") # -> "a cat" A("euphemism") # -> "a euphemism" A("Euler number") # -> "an Euler number" A("hour") # -> "an hour" A("houri") # -> "a houri" The two subroutines are *identical* in function and may be used interchangeably. The only reason that two versions are provided is to enhance the readability of code such as: print "That is ", AN($errortype), " error\n; print "That is ", A($fataltype), " fatal error\n; Note that in both cases the actual article provided depends *only* on the pronunciation of the first argument, not on the name of the subroutine. `A()' and `AN()' both take an optional second argument. As with the `PL_...' subroutines, this second argument is a "number" specifier. If its value is 1 (or some other value implying singularity), `A()' and `AN()' insert "a" or "an" as appropriate. If the number specifier implies plurality, (`A()' and `AN()' insert the actual second argument instead. For example: A("cat",1) # -> "a cat" A("cat",2) # -> "2 cat" A("cat","one") # -> "one cat" A("cat","no") # -> "no cat" Note that, as implied by the previous examples, `A()' and `AN()' both assume that their job is merely to provide the correct qualifier for a word (that is: "a", "an", or the specified count). In other words, they assume that the word they are given has already been correctly inflected for plurality. Hence, if `$N' has the value 2, then: print A("cat",$N); prints "2 cat", instead of "2 cats". The correct approach is to use: print A(PL("cat",$N),$N); or, better still: print NO("cat",$N); Note too that, like the various `PL_...' subroutines, whenever `A()' and `AN()' are called with only one argument they are subject to the effects of any preceding call to `NUM()'. Hence, another possible solution is: NUM($N); print A(PL("cat")); Indefinite articles and initialisms ----------------------------------- "Initialisms" (sometimes inaccurately called "acronyms") are terms which have been formed from the initial letters of words in a phrase (for example, "NATO", "NBL", "S.O.S.", "SCUBA", etc.) Such terms present a particular challenge when selecting between "a" and "an", since they are sometimes pronounced as if they were a single word ("nay-tow", "sku-ba") and sometimes as a series of letter names ("en-eff-ell", "ess-oh-ess"). `A()' and `AN()' cope with this dichotomy using a series of inbuilt rules, which may be summarized as: 1. If the word starts with a single letter, followed by a period or dash (for example, "R.I.P.", "C.O.D.", "e-mail", "X-ray", "T-square"), then choose the appropriate article for the sound of the first letter ("an R.I.P.", "a C.O.D.", "an e-mail", "an X-ray", "a T-square"). 2. If the first two letters of the word are capitals, consonants, and do not appear at the start of any known English word, (for example, "LCD", "XML", "YWCA"), then once again choose "a" or "an" depending on the sound of the first letter ("an LCD", "an XML", "a YWCA"). 3. Otherwise, assume the string is a capitalized word or a pronounceable initialism (for example, "LED", "OPEC", "FAQ", "UNESCO"), and therefore takes "a" or "an" according to the (apparent) pronunciation of the entire word ("a LED", "an OPEC", "a FAQ", "a UNESCO"). Note that rules 1 and 3 together imply that the presence or absence of punctuation may change the selection of indefinite article for a particular initialism (for example, "a FAQ" but "an F.A.Q."). Indefinite articles and "soft H's" ---------------------------------- Words beginning in the letter 'H' present another type of difficulty when selecting a suitable indefinite article. In a few such words (for example, "hour", "honour", "heir") the 'H' is not voiced at all, and so such words inflect with "an". The remaining cases ("voiced H's") may be divided into two categories: "hard H's" (such as "hangman", "holograph", "hat", etc.) and "soft H's" (such as "hysterical", "horrendous", "holy", etc.) Hard H's always take "a" as their indefinite article, and soft H's normally do so as well. But some English speakers prefer "an" for soft H's (although the practice is now generally considered an affectation, rather than a legitimate grammatical alternative). At present, the `A()' and `AN()' subroutines ignore soft H's and use "a" for any voiced 'H'. The author would, however, welcome feedback on this decision (envisaging a possible future "soft H" mode). INFLECTING ORDINALS =================== Occasionally it is useful to present an integer value as an ordinal rather than as a numeral. For example: Enter password (1st attempt): ******** Enter password (2nd attempt): ********* Enter password (3rd attempt): ********* No 4th attempt. Access denied. To this end, Lingua::EN::Inflect provides the `ORD()' subroutine. takes a single argument and forms its ordinal equivalent. If the argument isn't a numerical integer, it just adds "-th". CONVERTING NUMBERS TO WORDS =========================== The exportable subroutine `NUMWORDS' takes a number and returns an English representation of that number. In a scalar context a string is returned. Hence: use Lingua::EN::Inflect qw( NUMWORDS ); $words = NUMWORDS(1234567); puts the string: "one million, two hundred and thirty-four thousand, five hundred and sixty-seven" into $words. In a list context each comma-separated chunk is returned as a separate element. Hence: @words = NUMWORDS(1234567); puts the list: ("one million", "two hundred and thirty-four thousand", "five hundred and sixty-seven") into @words. Non-digits (apart from an optional leading plus or minus sign and any decimal points) are silently ignored, so the following all produce identical results: NUMWORDS(5551202); NUMWORDS(5_551_202); NUMWORDS("5,551,202"); NUMWORDS("555-1202"); That last case is a little awkward since it's almost certainly a phone number, and "five million, five hundred and fifty-one thousand, two hundred and two" probably isn't what's wanted. To overcome this, `NUMWORDS()' takes an optional named argument, 'group', which changes how numbers are translated. The argument must be a positive integer less than four, which indicated how the digits of the number are to be grouped. If the argument is 1, then each digit is translated separately. If the argument is 2, pairs of digits (starting from the left) are grouped together. If the argument is 3, triples of numbers (again, from the left) are grouped. Hence: NUMWORDS("555-1202", group=>1) returns `"five, five, five, one, two, zero, two"', whilst: NUMWORDS("555-1202", group=>2) returns `"fifty-five, fifty-one, twenty, two"', and: NUMWORDS("555-1202", group=>3) returns `"five fifty-five, one twenty, two"'. Phone numbers are often written in words as `"five..five..five..one..two..zero..two"', which is also easy to achieve: join '..', NUMWORDS("555-1202", group=>1) `NUMWORDS' also handles decimal fractions. Hence: NUMWORDS("1.2345") returns `"one point two three four five"' in a scalar context and `("one","point","two","three","four","five")') in an array context. Exponent form (`"1.234e56"') is not yet handled. Multiple decimal points are only translated in one of the "grouping" modes. Hence: NUMWORDS(101.202.303) returns `"one hundred and one point two zero two three zero three"', whereas: NUMWORDS(101.202.303, group=>1) returns `"one zero one point two zero two point three zero three"'. The digit `'0'' is unusual in that in may be translated to English as "zero", "oh", or "nought". To cater for this diversity, `NUMWORDS' may be passed a named argument, 'zero', which may be set to the desired translation of `'0''. For example: print join "..", NUMWORDS("555-1202", group=>3, zero=>'oh') prints `"five..five..five..one..two..oh..two"'. By default, zero is rendered as "zero". Another major regional variation in number translation is the use of "and" in certain contexts. The named argument 'and' allows the programmer to specify how "and" should be handled. Hence: print scalar NUMWORDS("765", 'and'=>'') prints "seven hundred sixty-five", instead of "seven hundred and sixty-five". By default, the "and" is included. The translation of the decimal point is also subject to variation (with "point", "dot", and "decimal" being the favorites). The named argument 'decimal' allows the programmer to how the decimal point should be rendered. Hence: print scalar NUMWORDS("666.124.64.101", group=>3, decimal=>'dot') prints "six sixty-six, dot, one twenty-four, dot, sixty-four, dot, one zero one" By default, the decimal point is rendered as "point". INTERPOLATING INFLECTIONS IN STRINGS ==================================== By far the commonest use of the inflection subroutines is to produce message strings for various purposes. For example: print NUM($errors), PL_N(" error"), PL_V(" was"), " detected.\n"; print PL_ADJ("This"), PL_N(" error"), PL_V(" was"), "fatal.\n" if $severity > 1; Unfortunately the need to separate each subroutine call detracts significantly from the readability of the resulting code. To ameliorate this problem, Lingua::EN::Inflect provides an exportable string-interpolating subroutine (`inflect($)'), which recognizes calls to the various inflection subroutines within a string and interpolates them appropriately. Using `inflect' the previous example could be rewritten: print inflect "NUM($errors) PL_N(error) PL_V(was) detected.\n"; print inflect "PL_ADJ(This) PL_N(error) PL_V(was) fatal.\n" if $severity > 1; Note that `inflect' also correctly handles calls to the `NUM()' subroutine (whether interpolated or antecedent). The `inflect()' subroutine has a related extra feature, in that it *automatically* cancels any "default number" value before it returns its interpolated string. This means that calls to `NUM()' which are embedded in an `inflect()'-interpolated string do not "escape" and interfere with subsequent inflections. MODERN VS CLASSICAL INFLECTIONS =============================== Certain words, mainly of Latin or Ancient Greek origin, can form plurals either using the standard English "-s" suffix, or with their original Latin or Greek inflections. For example: PL("stigma") # -> "stigmas" or "stigmata" PL("torus") # -> "toruses" or "tori" PL("index") # -> "indexes" or "indices" PL("millennium") # -> "millenniums" or "millennia" PL("ganglion") # -> "ganglions" or "ganglia" PL("octopus") # -> "octopuses" or "octopodes" Lingua::EN::Inflect caters to such words by providing an "alternate state" of inflection known as "classical mode". By default, words are inflected using their contemporary English plurals, but if classical mode is invoked, the more traditional plural forms are returned instead. The exportable subroutine `classical()' controls this feature. If `classical()' is called with no arguments, it unconditionally invokes classical mode. If it is called with an argument, it invokes classical mode only if that argument evaluates to true. If the argument is false, classical mode is switched off. Thus: classical; # SWITCH ON CLASSICAL MODE print PL("formula"); # -> "formulae" classical 0; # SWITCH OFF CLASSICAL MODE print PL("formula"); # -> "formulas" classical $cmode; # CLASSICAL MODE IFF $cmode print PL("formula"); # -> "formulae" (IF $cmode) # -> "formulas" (OTHERWISE) Note however that `classical()' has no effect on the inflection of words which are now fully assimilated. Hence: PL("forum") # ALWAYS -> "forums" PL("criterion") # ALWAYS -> "criteria" USER-DEFINED INFLECTIONS ======================== Adding plurals at run-time -------------------------- Lingua::EN::Inflect provides five exportable subroutines which allow the programmer to override the module's behaviour for specific cases: `def_noun($$)' The `def_noun' subroutine takes a pair of string arguments: the singular and plural forms of the noun being specified. The singular form specifies a pattern to be interpolated (as `m/^(?:$first_arg)$/i'). Any noun matching this pattern is then replaced by the string in the second argument. The second argument specifies a string which is interpolated after the match succeeds, and is then used as the plural form. For example: def_noun 'cow' => 'kine'; def_noun '(.+i)o' => '$1i'; def_noun 'spam(mer)?' => '\\$\\%\\@#\\$\\@#!!'; Note that both arguments should usually be specified in single quotes, so that they are not interpolated when they are specified, but later (when words are compared to them). As indicated by the last example, care also needs to be taken with certain characters in the second argument, to ensure that they are not unintentionally interpolated during comparison. The second argument string may also specify a second variant of the plural form, to be used when "classical" plurals have been requested. The beginning of the second variant is marked by a '|' character: def_noun 'cow' => 'cows|kine'; def_noun '(.+i)o' => '$1os|$1i'; def_noun 'spam(mer)?' => '\\$\\%\\@#\\$\\@#!!|varmints'; If no classical variant is given, the specified plural form is used in both normal and "classical" modes. If the second argument is undef instead of a string, then the current user definition for the first argument is removed, and the standard plural inflection(s) restored. Note that in all cases, later plural definitions for a particular singular form replace earlier definitions of the same form. For example: # FIRST, HIDE THE MODERN FORM.... def_noun 'aviatrix' => 'aviatrices'; # LATER, HIDE THE CLASSICAL FORM... def_noun 'aviatrix' => 'aviatrixes'; # FINALLY, RESTORE THE DEFAULT BEHAVIOUR... def_noun 'aviatrix' => undef; Special care is also required when defining general patterns and associated specific exceptions: put the more specific cases after the general pattern. For example: def_noun '(.+)us' => '$1i'; # EVERY "-us" TO "-i" def_noun 'bus' => 'buses'; # EXCEPT FOR "bus" This "try-most-recently-defined-first" approach to matching user-defined words is also used by `def_verb', `def_a' and `def_an'. `def_verb($$$$$$)' The `def_verb' subroutine takes three pairs of string arguments (that is, six arguments in total), specifying the singular and plural forms of the three "persons" of verb. As with `def_noun', the singular forms are specifications of run-time-interpolated patterns, whilst the plural forms are specifications of (up to two) run-time-interpolated strings: def_verb 'am' => 'are', 'are' => 'are|art", 'is' => 'are'; def_verb 'have' => 'have', 'have' => 'have", 'ha(s|th)' => 'have'; Note that as with `def_noun', modern/classical variants of plurals may be separately specified, subsequent definitions replace previous ones, and undef'ed plural forms revert to the standard behaviour. `def_adj($$)' The `def_adj' subroutine takes a pair of string arguments, which specify the singular and plural forms of the adjective being defined. As with `def_noun' and `def_adj', the singular forms are specifications of run-time-interpolated patterns, whilst the plural forms are specifications of (up to two) run-time-interpolated strings: def_adj 'this' => 'these', def_adj 'red' => 'red|gules', As previously, modern/classical variants of plurals may be separately specified, subsequent definitions replace previous ones, and undef'ed plural forms revert to the standard behaviour. `def_a($)' and `def_an($)' The `def_a' and `def_an' subroutines each take a single argument, which specifies a pattern. If a word passed to `A()' or `AN()' matches this pattern, it will be prefixed (unconditionally) with the corresponding indefinite article. For example: def_a 'error'; def_a 'in.+'; def_an 'mistake'; def_an 'error'; As with the other `def_...' subroutines, such redefinitions are sequential in effect so that, after the above example, "error" will be inflected with "an". The `$HOME/.inflectrc' file --------------------------- When it is imported, Lingua::EN::Inflect executes (as Perl code) the contents of any file named `.inflectrc' which it finds in the in the directory where `Lingua/EN/Inflect.pm' is installed, or in the current home directory (`$ENV{HOME}'), or in both. Note that the code is executed within the Lingua::EN::Inflect namespace. Hence the user or the local Perl guru can make appropriate calls to `def_noun', `def_verb', etc. in one of these `.inflectrc' files, to permanently and universally modify the behaviour of the module. For example > cat /usr/local/lib/perl5/Text/Inflect/.inflectrc def_noun "UNIX" => "UN*X|UNICES"; def_verb "teco" => "teco", # LITERALLY: "to edit with TECO" "teco" => "teco", "tecos" => "teco"; def_a "Euler.*"; # "Yewler" TURNS IN HIS GRAVE Note that calls to the `def_...' subroutines from within a program will take precedence over the contents of the home directory `.inflectrc' file, which in turn takes precedence over the system-wide `.inflectrc' file. DIAGNOSTICS =========== On loading, if the Perl code in a `.inflectrc' file is invalid (syntactically or otherwise), an appropriate fatal error is issued. A common problem is not ending the file with something that evaluates to true (as the five `def_...' subroutines do). Using the five `def_...' subroutines directly in a program may also result in fatal diagnostics, if a (singular) pattern or an interpolated (plural) string is somehow invalid. Specific diagnostics related to user-defined inflections are: `"Bad user-defined singular pattern:\n\t %s"' The singular form of a user-defined noun or verb (as defined by a call to `def_noun', `def_verb', `def_adj', `def_a' or `def_an') is not a valid Perl regular expression. The actual Perl error message is also given. `"Bad user-defined plural string: '%s'"' The plural form(s) of a user-defined noun or verb (as defined by a call to `def_noun', `def_verb' or `def_adj') is not a valid Perl interpolated string (usually because it interpolates some undefined variable). `"Bad .inflectrc file (%s):\n %s"' Some other problem occurred in loading the named local or global `.inflectrc' file. The Perl error message (including the line number) is also given. There are no diagnosable run-time error conditions for the actual inflection subroutines, except `NUMWORDS' and hence no run-time diagnostics. If the inflection subroutines are unable to form a plural via a user-definition or an inbuilt rule, they just "guess" the commonest English inflection: adding "-s" for nouns, removing "-s" for verbs, and no inflection for adjectives. `Lingua::EN::Inflect::NUMWORDS()' can die with the following messages: `"Bad grouping option: %s"' The optional argument to `NUMWORDS()' wasn't 1, 2 or 3. `"Number out of range"' `NUMWORDS()' was passed a number larger than 999,999,999,999,999,999,999,999,999,999,999,999 (that is: nine hundred and ninety-nine decillion, nine hundred and ninety-nine nonillion, nine hundred and ninety-nine octillion, nine hundred and ninety-nine septillion, nine hundred and ninety-nine sextillion, nine hundred and ninety-nine quintillion, nine hundred and ninety-nine quadrillion, nine hundred and ninety-nine trillion, nine hundred and ninety-nine billion, nine hundred and ninety-nine million, nine hundred and ninety-nine thousand, nine hundred and ninety-nine :-) The problem is that `NUMWORDS' doesn't know any words for number components bigger than "decillion". OTHER ISSUES ============ 2nd Person precedence --------------------- If a verb has identical 1st and 2nd person singular forms, but different 1st and 2nd person plural forms, then when its plural is constructed, the 2nd person plural form is always preferred. The author is not currently aware of any such verbs in English, but is not quite arrogant enough to assume *ipso facto* that none exist. Nominative precedence --------------------- The singular pronoun "it" presents a special problem because its plural form can vary, depending on its "case". For example: It ate my homework -> They ate my homework It ate it -> They ate them I fed my homework to it -> I fed my homework to them As a consequence of this ambiguity, `PL()' or `PL_N' have been implemented so that they always return the *nominative* plural (that is, "they"). However, when asked for the plural of an unambiguously *accusative* "it" (namely, `PL("to it")', `PL_N("from it")', `PL("with it")', etc.), both subroutines will correctly return the accusative plural ("to them", "from them", "with them", etc.) The plurality of zero --------------------- The rules governing the choice between: There were no errors. and There was no error. are complex and often depend more on *intent* rather than content. Hence it is infeasible to specify such rules algorithmically. Therefore, Lingua::EN::Text contents itself with the following compromise: If the governing number is zero, inflections always return the plural form unless "classical" inflections are in effect, in which case the singular form is always returned. Thus, the sequence: NUM(0); print inflect "There PL(was) NO(choice)"; produces "There were no choices", unless `classical(1)' has been called, in which case it will print "There was no choice". Homographs with heterogeneous plurals ------------------------------------- Another context in which intent (and not content) sometimes determines plurality is where two distinct meanings of a word require different plurals. For example: Three basses were stolen from the band's equipment trailer. Three bass were stolen from the band's aquarium. I put the mice next to the cheese. I put the mouses next to the computers. Several thoughts about leaving crossed my mind. Several thought about leaving across my lawn. Lingua::EN::Inflect handles such words in two ways: * If both meanings of the word are the *same* part of speech (for example, "bass" is a noun in both sentences above), then one meaning is chosen as the "usual" meaning, and only that meaning's plural is ever returned by any of the inflection subroutines. * If each meaning of the word is a different part of speech (for example, "thought" is both a noun and a verb), then the noun's plural is returned by `PL()' and `PL_N()' and the verb's plural is returned only by `PL_V()'. Such contexts are, fortunately, uncommon (particularly "same-part-of-speech" examples). An informal study of nearly 600 "difficult plurals" indicates that `PL()' can be relied upon to "get it right" about 98% of the time (although, of course, ichthyophilic guitarists or cyber-behaviouralists may experience higher rates of confusion). If the choice of a particular "usual inflection" is considered inappropriate, it can always be reversed with a preliminary call to the corresponding `def_...' subroutine. AUTHORS ======= Damian Conway (damian@conway.org) Matthew Persico (ORD inflection) BUGS AND IRRITATIONS ==================== The endless inconsistencies of English. (Please report words for which the correct plural or indefinite article is not formed, so that the reliability of Lingua::EN::Inflect can be improved.) COPYRIGHT ========= Copyright (c) 1997-2000, Damian Conway. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)  File: pm.info, Node: Lingua/EN/MatchNames, Next: Lingua/EN/NameCase, Prev: Lingua/EN/Inflect, Up: Module List Smart matching for human names. ******************************* NAME ==== Lingua::EN::MatchNames - Smart matching for human names. SYNOPSIS ======== use Lingua::EN::MatchNames qw(matchnames); $score= name_eq( $firstn_0, $lastn_0, $firstn_1, $lastn_1 ); DESCRIPTION =========== You have two databases of person records that need to be synchronized or matched up, but they use different keys-maybe one uses SSN and the other uses employee id. The only fields you have to match on are first and last name. That's what this module is for. Just feed the first and last names to the `name_eq()' function, and it returns undef for no possible match, and a percentage of certainty (rank) otherwise. The ranking system isn't very scientific, and gender isn't considered, though it probably should be. The `name_eq()' function, checks for: * inconsistent case (MacHenry = Machenry = MACHENRY) * inconsistent symbols (O'Brien = Obrien = O BRIEN) * misspellings (Grene = Green) * last name hyphenation (Smith-Curry = Curry) * similar phonetics (Hanson = Hansen) * nicknames (Midge = Peggy = Margaret) * extraneous initials (H. Ross = Ross) * extraneous suffixes (Reed, Jr. = Reed II = Reed) * and more... Preliminary Tests: ------------------ Homer Simpson HOMER SIMPOSN: 77 Marge Simpson MIDGE SIMPSON: 81 Brian Lalonde BRYAN LA LONDE: 82 Brian Lalonde RYAN LALAND: 72 Peggy MacHenry Midge Machenry: 81 Liz Grene Elizabeth Green: 72 Chuck Reed, Jr. Charles Reed II: 82 Kathy O'Brien Catherine Obrien: 81 Lizzie Hanson Lisa Hanson: 91 H. Ross Perot Ross PEROT: 88 Kathy Smith-Curry KATIE CURRY: 81 Dina Johnson-Warner Dinah J-Warner: 80 Leela Miles-Conrad Leela MilesConrad: 86 C. Renee Smythe Cathy Smythe: 71 Victoria (Honey) Rider HONEY RIDER: 88 Bart Simpson El Barto Simpson: 80 Bart Simpson Lisa Simpson: (no match) Arthur Dent Zaphod Beeblebrox: (no match) WARNING ======= The scoring in this version is utterly arbitrary. I made all of the numbers up. The certainty percentages should be OK relative to each other, but would be better if someone could give me some statistical data. Be sure and test this against your data first! Your data may not look like my test data. And although I hope this is useful to many, I do not provide any kind of warranty (expressed or implied), and do not suggest the suitability of this module to any particular purpose. This module probably should not be used for life support or military purposes, and it must not be used for unsolicited commercial email or other bulk advertising. AUTHOR ====== Brian Lalonde, REQUIREMENTS ============ Lingua::EN::NameParse, Lingua::EN::Nickname, Parse::RecDescent, String::Approx, Text::Metaphone, Text::Soundex SEE ALSO ======== perl(1), *Note Lingua/EN/NameParse: Lingua/EN/NameParse,, *Note Lingua/EN/Nickname: Lingua/EN/Nickname,, *Note String/Approx: String/Approx,, *Note Text/Metaphone: Text/Metaphone,, *Note Text/Soundex: Text/Soundex,  File: pm.info, Node: Lingua/EN/NameCase, Next: Lingua/EN/NameGrammar, Prev: Lingua/EN/MatchNames, Up: Module List Perl module to fix the case of people's names. ********************************************** NAME ==== NameCase - Perl module to fix the case of people's names. SYNOPSIS ======== # Working with scalars; complementing lc and uc. use Lingua::EN::NameCase qw( nc ) ; $FixedCasedName = nc( $OriginalName ) ; $FixedCasedName = nc( \$OriginalName ) ; # Working with arrays or array references. use Lingua::EN::NameCase 'NameCase' ; $FixedCasedName = NameCase( $OriginalName ) ; @FixedCasedNames = NameCase( @OriginalNames ) ; $FixedCasedName = NameCase( \$OriginalName ) ; @FixedCasedNames = NameCase( \@OriginalNames ) ; NameCase( \@OriginalNames ) ; # In-place. # NameCase will not change a scalar in-place, i.e. NameCase( \$OriginalName ) ; # WRONG: null operation. DESCRIPTION =========== Forenames and surnames are often stored either wholly in UPPERCASE or wholly in lowercase. This module allows you to convert names into the correct case where possible. Although forenames and surnames are normally stored separately if they do appear in a single string, whitespace separated, NameCase and nc deal correctly with them. NameCase currently correctly name cases names which include any of the following: Mc, Mac, al, el, ap, da, de, delle, della, di, du, del, der, la, le, lo, van and von. It correctly deals with names which contain apostrophies and hyphens too. EXAMPLE FIXES ------------- Original Name Case -------- --------- KEITH Keith LEIGH-WILLIAMS Leigh-Williams MCCARTHY McCarthy O'CALLAGHAN O'Callaghan ST. JOHN St. John plus "son (daughter) of" etc. in various languages, e.g.: VON STREIT von Streit VAN DYKE van Dyke AP LLWYD DAFYDD ap Llwyd Dafydd etc. plus names with roman numerals (up to 89, LXXXIX), e.g.: henry viii Henry VIII louis xiv Louis XIV BUGS ==== The module covers the rules that I know of. There are probably a lot more rules, exceptions etc. for "Western"-style languages which could be incorporated. We don't fix "ben" - for hebrew names this means son of, but it can mean "Ben" as a name in itself or as a form of "Benjamin". However we do fix "al" - for arabic names this means son of, even though it can also mean "Al" as a name in itself. There are probably lots of exceptions and problems - but as a general data 'cleaner' it may be all you need. Use Kim Ryan's NameParse.pm for any really sophisticated name parsing. CHANGES ======= 1998/04/20 First release. 1998/06/25 First public release. 1999/01/18 Second public release. 1999/02/08 Added Mac with Mack as an exception, thanks to Kim Ryan for this. 1999/05/05 Copied Kim Ryan's Mc/Mac solution from his NameParse.pm and replaced my Mc/Mac solution with his. 1999/05/08 nc can now use $_ as its default argument e.g. "$ans = nc ;" and "nc ;", both of which set $_, with the first one setting $ans also. 1999/07/30 Modified for CPAN and automatic testing. Stopped using $_ as the default argument. 1999/08/08 Changed licence to LGPL. 1999/09/07 Minor change to packaging for CPAN. 1999/09/09 Renamed package Lingua::EN::NameCase.pm as per John Porter's (CPAN) suggestion. 1999/11/13 Added code for names with roman numerals, thanks to David Lynn Rice for this suggestion. (If you need to go beyond LXXXIX let me know.) 2000/11/22 Added use locale at the suggestion of Eric Kolve. It should have been there in the first place. AUTHOR ====== Mark Summerfield. I can be contacted as - please include the word 'namecase' in the subject line. Thanks to Kim Ryan for his Mc/Mac solution. COPYRIGHT ========= Copyright (c) Mark Summerfield 1998-2000. All Rights Reserved. This module may be used/distributed/modified under the LGPL.  File: pm.info, Node: Lingua/EN/NameGrammar, Next: Lingua/EN/NameParse, Prev: Lingua/EN/NameCase, Up: Module List Lingua::EN::NameGrammar *********************** NAME ==== Lingua::EN::NameGrammar DESCRIPTION =========== Grammar tree of personal name syntax for Lingua::EN::NameParse module. The grammar defined here is for use with the Parse::RecDescent module. Note that parsing is done depth first, meaning match the shortest string first. To avoid premature matches, when one rule is a sub set of another longer rule, it must appear after the longer rule. See the Parse::RecDescent documentation for more details. COPYRIGHT ========= Copyright (c) 1999-2001 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 ====== NameGrammar was written by Kim Ryan in 1999.  File: pm.info, Node: Lingua/EN/NameParse, Next: Lingua/EN/Nickname, Prev: Lingua/EN/NameGrammar, Up: Module List routines for manipulating a persons name **************************************** NAME ==== Lingua::EN::NameParse - routines for manipulating a persons name SYNOPSIS ======== use Lingua::EN::NameParse qw(clean case_surname); # optional configuration arguments my %args = ( salutation => 'Dear', sal_default => 'Friend', auto_clean => 1, force_case => 1, lc_prefix => 1, initials => 3, allow_reversed => 1 ); my $name = new Lingua::EN::NameParse(%args); $error = $name->parse("MR AC DE SILVA"); %name_comps = $name->components; $surname = $name_comps{surname_1}; # DE SILVA $correct_casing = $name->case_all; # Mr AC de Silva $good_name = &clean("Bad Na9me "); # "Bad Name" $name->salutation; # Dear Mr de Silva %my_properties = $name->properties; $number_surnames = $my_properties{number}; # 1 $bad_input = $my_properties{non_matching}; $lc_prefix = 0; $correct_case = &case_surname("DE SILVA-MACNAY",$lc_prefix); # De Silva-MacNay REQUIRES ======== Perl, version 5.001 or higher and Parse::RecDescent DESCRIPTION =========== This module takes as input a person or persons name in free format text such as, Mr AB & M/s CD MacNay-Smith MR J.L. D'ANGELO Estate Of The Late Lieutenant Colonel AB Van Der Heiden and attempts to parse it. If successful, the name is broken down into components and useful functions can be performed such as : converting upper or lower case values to name case (Mr AB MacNay ) creating a personalised greeting or salutation (Dear Mr MacNay ) extracting the names individual components (Mr,AB,MacNay ) determining the type of format the name is in (Mr_A_Smith ) If the name cannot be parsed you have the option of cleaning the name 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 names. DEFINITIONS =========== The following terms are used by NameParse to define the components that can make up a name. Precursor - Estate of (The Late), Right Honourable ... Title - Mr, Mrs, Ms., Sir, Dr, Major, Reverend ... Conjunction - word to separate names or initials, such as "And" Initials - 1-3 letters, each with an optional space and/or dot Surname - De Silva, Van Der Heiden, MacNay-Smith, O'Reilly ... Suffix - Senior, Jnr, III, V ... Refer to the component grammar defined within the code for a complete list of combinations. 'Name casing' refers to the correct use of upper and lower case letters in peoples names, such as Mr AB McNay. To describe the formats supported by NameParse, a short hand representation of the name is used. The following formats are currently supported : Mr_A_Smith_&_Ms_B_Jones Mr_&_Ms_A_&_B_Smith Mr_A_&_Ms_B_Smith Mr_&_Ms_A_Smith Mr_A_&_B_Smith Mr_John_A_Smith Mr_John_Smith Mr_A_Smith John_Adam_Smith John_A_Smith John_Smith A_Smith Precursors are only applied to the Mr_John_A_Smith, Mr_John_Smith, John_Adam_Smith, Mr_A_Smith, Mr_John_Smith, John_Smith and A_Smith formats. Suffixes are only applied to the Mr_John_A_Smith,Mr_John_Smith, Mr_A_Smith, John_Adam_Smith, John_A_Smith and John_Smith formats. METHODS ======= new --- The new method creates an instance of a name object and sets up the grammar used to parse names. 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. Calling new repeatedly will significantly slow your program down. Various setup options may be defined in a hash that is passed as an optional argument to the new method. Note that all the arguments are optional. You need to define the combination of arguments that are appropriate for your usage. my %args = ( salutation => 'Dear', sal_default => 'Friend', auto_clean => 1, force_case => 1, lc_prefix => 1, initials => 3, allow_reversed => 1 ); my $name = new Lingua::EN::NameParse(%args); =item salutation The option defines the salutation word, such as "Dear" or "Greetings". It must be defined if you are planning to use the salutation method. sal_default This option defines the defaulting word to substitute for the title and surname(s), when parsing fails to identify them. It is also used when a precursor occurs. Examples are "Friend" or "Member". It must be defined if you are planning to use the salutation method. If an '&' or 'and' occurs in the unmatched section then it is assumed that we are dealing with more than one person, and an 's' is appended to the defaulting word. force_case This option will force the case_all method to name case the entire input string, including any unmatched sections that failed parsing. For example, in "MR A JONES & ASSOCIATES", "& ASSOCIATES" will also be name cased. The casing rules for unmatched sections are the same as for surnames. This is usually the best option, although any initials in the unmatched section will not be correctly cased. This option is useful when you know you data has invalid names, 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 name and then reparse it. See the clean method for details. This is useful for dirty data with embedded unprintable or non alphabetic characters. =item lc_prefix When this option is set to a positive value, it will force the case_all and `case_component' methods to lower case the first letter of each word that occurs in the prefix portion of a surname. For example, Mr AB de Silva, or Ms AS von der Heiden. initials Allows the user to control the number of letters that can occur in the initials. Valid settings are 1,2 or 3. If no value is supplied a default of 2 is used. allow_reversed When this option is set to a positive value, names in reverse order will be processed. The only valid format is the surname followed by a comma and the rest of the name, which can be in any of the combinations allowed by non reversed names. Some examples are: Smith, Mr AB Jones, Jim De Silva, Professor A.B. The program change the order of the name back to the non reversed format, and then performs the normal parsing. Note that if the name can be parsed, the fact that it's order was originally reversed, is not recorded as a property of the name object. parse ----- $error = $name->parse("MR AC DE SILVA"); The parse method takes a single parameter of a text string containing a name. It attempts to parse the name and break it down into the components described above. If the name was parsed successfully, a 0 is returned, otherwise a 1. This step is a prerequisite for the following functions. case_all -------- $correct_casing = $name->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- initials remain capitalised surname spelling such as MacNay-Smith, O'Brien and Van Der Heiden are preserved - see C for user defined exceptions A complete definition of the capitalising rules can be found by studying the component grammar defined within the code. The method returns the entire cased name as text. case_components --------------- %my_name = $name->components; $cased_surname = $my_name{surname_1}; The case_components method does the same thing as the case_all method, but returns the name cased components in a hash. The following keys are used for each component- precursor title_1 title_2 given_name_1 initials_1 initials_2 middle_name conjunction_1 conjunction_2 surname_1 surname_2 suffix Entries only occur in the hash for each component that the currently parsed name contains, meaning there are no keys with undefined values. components ---------- %name = $name->components; $surname = $my_name{surname_1}; 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. case_surname ------------ $correct_casing = &case_surname("DE SILVA-MACNAY" [,$lc_prefix]); case_surname is a stand alone function that does not require a name object. The input is a text string and the output is a string converted to the correct casing for surnames. An optional argument controls the casing rules for prefix portions of a surname, as described above in the `lc_prefix' section. See surname_prefs.txt for user defined exceptions This function is useful when you know you are only dealing with names that do not have initials like "Mr John Jones". It is much faster than the case_all method, but does not understand context, and cannot detect errors on strings that are not personal names. surname_prefs.txt ----------------- Some surnames can have more than one form of valid capitalisation, such as MacQuarie or Macquarie. Where the user wants to specify one form as the default, a text file called surname_prefs.txt should be created and placed in the same location as the NameParse module. The text file should contain one surname per line, in the capitalised form you want, such as Macquarie MacHado NameParse will still operate if the file does not exist salutation ---------- The salutation method converts a name into a personal greeting, such as "Dear Mr & Mrs O'Brien". If an error is detected during parsing, such as with the name "AB Smith & Associates", the title (if it occurs) and the surname(s) are replaced with a default word like "Friend" or "Member". If the input string contains a conjunction, an 's' is added to the default. If the name contains a precursor, a default salutation is also produced. clean ----- $good_name = &clean("Bad Na9me"); clean is a stand alone function that does not require a name object. The input is a text string and the output is the string with: all repeating spaces removed all characters not in the set (A-Z a-z - ' , . &) removed properties ---------- The properties method returns all the properties of the name, non_matching, number and type, as a hash. type The type of format a name is in, as one of the following strings: Mr_A_Smith_&_Ms_B_Jones Mr_&_Ms_A_&_B_Smith Mr_A_&_Ms_B_Smith Mr_&_Ms_A_Smith Mr_A_&_B_Smith Mr_John_A_Smith Mr_John_Smith Mr_A_Smith John_Adam_Smith John_A_Smith John_Smith A_Smith unknown =item non_matching Returns any unmatched section that was found. LIMITATIONS =========== The huge number of character combinations that can form a valid names makes it is impossible to correctly identify them all. Firstly, there are many ambiguities, which have no right answer. Macbeth or MacBeth, are both valid spellings Is ED WOOD E.D. Wood or Edward Wood Is 'Mr Rapid Print' a name or a company One approach is to have large lookup files of names and words, statistical rules and fuzzy logic to attempt to derive context. This approach gives high levels of accuracy but uses a lot of your computers time and resources. NameParse takes the approach of using a limited set of rules, based on the formats that are commonly used by business to represent peoples names. This gives us fairly high accuracy, with acceptable speed and program size. NameParse will accept names from many countries, like Van Der Heiden, De La Mare and Le Fontain. Having said that, it is still biased toward English, because the precursors, titles and conjunctions are based on English usage. Names with two or more words, but no separating hyphen are not recognized. This is a real quandary as Indian, Chinese and other names can have several components. If these are allowed for, any component after the surname will also be picked up. For example in "Mr AB Jones Trading As Jones Pty Ltd" will return a surname of "Jones Trading". Because of the large combination of possible names defined in the grammar, the program is not very fast, except for the more limited case_surname subroutine. See the "Future Directions" section for possible speed ups. 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 ================= Add filtering of very long names Add diagnostic messages explaining why parsing failed Add transforming methods to do things like remove dots from initials Try to derive gender (Mr... is male, Ms, Mrs... is female) Let the user select what level of complexity of grammar they need for their data. For example, if you know most of your names are in a "John Smith" format, you can avoid the ambiguity between two letter given names and initials. Using a limited grammar subset will also be much faster. 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 ======== Lingua::EN::AddressParse Lingua::EN::MatchNames Lingua::EN::NickNames Lingua::EN::NameCase Parse::RecDescent TO DO ===== Add regression tests for all combinations of each component BUGS ==== COPYRIGHT ========= Copyright (c) 1999-2001 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 ====== NameParse was written by Kim Ryan in 1999. Thanks to all the people who provided ideas and suggestions, including - QM Industries Damian Conway author of Parse::RecDescent , author of Lingua::EN::NameCase, Ron Savage , Adam Huffman, Douglas Wilson