NameML (de.mpg.mpi-inf:javatools 1.1 API)

java.lang.Object
- javatools.parsers.NameML

Direct Known Subclasses:

NameML.AbbreviationML, NameML.CompanyNameML, NameML.PersonNameML
```
public class NameML
extends Object
```
Copyright 2016 Fabian M. Suchanek Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. This class is a multi-language extension of the Name class. Its functionality is synonymous to that of the Name class, but given corresponding word lists it supports various languages. The class NameML represents a name. There are three sub-types (subclasses) of names: Abbreviations, person names and company names. These subclasses provide methods to access the components of the name (like the family name). Use the factory method NameML.of to create a NameML-object of the appropriate subclass. However, before you can apply any NameML method, you need to initiate the class with the path to its lanuage dependent configuration files.
Example:
```
 NameML.init();
 NameML.isName("Mouse");
   --> true
   NameML.isAbbreviation("PMM");
   --> true  
   NameML.isPersonName("Mickey Mouse",Language.ENGLISH);
   --> false
   NameML.couldBePersonName("Mickey Mouse",Language.ENGLISH);
   --> true
   NameML.isPersonName("Pope Mickey Mouse",Language.ENGLISH);
   --> true
   NameML.isPersonName("Pope Mickey Mouse",Language.SPANISH);
   --> false
   NameML.isPersonName("Pope Mickey Mouse",Language.GERMAN);
   --> false    
   NameML.isPersonName("Papst Mickey Mouse",Language.GERMAN);
   --> true   
   NameML.of("Prof. Dr. Fabian the Great III of Saarbruecken").describe()
   // equivalent to new PersonName(...) in this case
   -->
   PersonName
     Original: Prof. Dr. Fabian the Great III of Saarbruecken
     Titles: Prof. Dr.
     Given Name: Fabian
     Given Names: Fabian
     Family Name Prefix: null
     Attribute Prefix: the
     Family Name: null
     Attribute: Great
     Family Name Suffix: null
     Roman: III
     City: Saarbruecken
     Normalized: Fabian_Great
 
```
IMPORTANT: !Note that for some recognition methods the class falls back to English as the target language since not all methods have been adapted yet for multi-language support and be aware that the interface might change for methods that are not yet language-dependent! Also note that currently you need to initialize the class first by calling one of the init functions before you can use most of its functions! Otherwise it may throw null pointer errors! TODO: Turn completely into an instantiable object? then we would not need to init nor to load all languages while only using 1

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class NameML.AbbreviationML

static class NameML.CompanyNameML

static class NameML.PersonNameML

Nested Classes
Modifier and Type	Class and Description
`static class`	`NameML.AbbreviationML`
`static class`	`NameML.CompanyNameML`
`static class`	`NameML.PersonNameML`

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`A` Contains characters
`static String`	`ANYNAME` Holds the general default name
`static String`	`attributePrefix` Contains attribute Prefixes (like "the" in "Alexander the Great")
`static Pattern`	`attributePrefixPattern`
`static String`	`B` Contains blank
`static String`	`BC` Contains blank with optional comma
`static String`	`BD` Contains a word boundary
`static String`	`companyNameSuffix` Contains common company name suffixes (like "Inc")
`static Pattern`	`companyNameSuffixPattern`
`static String`	`DG` Contains digits
`static String`	`directFamilyNamePrefix` A direct family name prefix (such as "Mc")
`static String`	`familyName` Name component with an optional familyNamePrefix and postfix
`static String`	`familyNamePrefix` Contains common family name prefixes (like "von")
`static Pattern`	`familyNamePrefixPattern`
`static String`	`familyNameSuffix` Contains common name suffixes (like "Junior")
`static Pattern`	`familyNameSuffixPattern`
`static String`	`givenName` The pattern "Name[-Name]"
`static String`	`givenNameComponent` The pattern "Name."
`static String`	`givenNames` The pattern (personNameComponent+B)+
`static String`	`H` Contains hypens
`protected static boolean`	`hasBeenInitialized`
`static String`	`L` Contains lower case Characters
`static Map<String,String>`	`languageCodes` Language codes
`static Pattern`	`laxAbbreviationPattern` Contains the lax pattern for abbreviations
`static Pattern`	`laxCompanyPattern` Contains the pattern for companies
`static String`	`laxName` Contains the pattern for names.
`static Pattern`	`laxNamePattern` Contains the pattern for names.
`static Pattern`	`laxPersonNamePatternDe`
`static Pattern`	`laxPersonNamePatternEn`
`static Pattern`	`laxPersonNamePatternEs`
`static Pattern`	`laxPersonNamePatternFr`
`static Pattern`	`laxPersonNamePatternIt`
`static Map<String,String>`	`nationality2country`
`static String`	`nickName` Nickname '...'
`protected String`	`normalized` Holds the normalized name
`static String`	`of` Contains the English "of"
`static String`	`or` Contains "\|"
`protected String`	`original` Holds the original name
`static String`	`personNameComponent` The pattern "Name"
`static String`	`prep` Contains prepositions
`static String`	`roman` Contains romam digits
`static Pattern`	`safeAbbreviationPattern` Contains the safe pattern for abbreviations
`static Pattern`	`safeCompanyPattern` Contains the safe pattern for companies
`static String`	`safeName` Contains a pattern that indicates strings that are very likely to be names
`static Pattern`	`safeNamePattern` Contains a pattern that indicates strings that are very likely to be names
`static Pattern`	`safeNamesPattern` Contains a pattern that indicates strings that are very likely to be names
`static Pattern`	`safeNamesPatternNoPrep` Contains a pattern that indicates strings that are very likely to be names
`static Pattern`	`safePersonNamePatternDe`
`static Pattern`	`safePersonNamePatternEn`
`static Pattern`	`safePersonNamePatternEs`
`static Pattern`	`safePersonNamePatternFr`
`static Pattern`	`safePersonNamePatternIt`
`protected static Set<String>`	`stopWordDE`
`protected static Set<String>`	`stopWordEN`
`protected static Set<String>`	`stopWordES`
`protected static Set<String>`	`stopWordFR`
`protected static Set<String>`	`stopWordIT`
`static String`	`teamName` team name
`static Pattern`	`teamNamePattern`
`static Pattern`	`titlePatternDe`
`static Pattern`	`titlePatternEn` Matches common titles (like "Mr.")
`static Pattern`	`titlePatternEs`
`static Pattern`	`titlePatternFr`
`static Pattern`	`titlePatternIt`
`protected static Set<String>`	`titlesForGivenNamesDe`
`protected static Set<String>`	`titlesForGivenNamesEn` Contains those titles that go with the given name (e.g.
`protected static Set<String>`	`titlesForGivenNamesEs`
`protected static Set<String>`	`titlesForGivenNamesFr`
`protected static Set<String>`	`titlesForGivenNamesIt`
`static String`	`U` Contains upper case Characters
`static Map<String,String>`	`usStates`

Constructor Summary

Constructors
Modifier Constructor and Description

protected NameML(String s)
Constructor (for subclasses only; use Name.of instead!)

Constructors
Modifier	Constructor and Description
`protected`	`NameML(String s)` Constructor (for subclasses only; use Name.of instead!)

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static String`	`c(String s)` Capturing group
`static boolean`	`couldBeAbbreviation(String word)` Tells whether a string could be abbreviation.
`static boolean`	`couldBeCompanyName(String s)` Tells if the string could be a company name
`static boolean`	`couldBeName(String s)` Tells whether a String could possibly be a name
`static boolean`	`couldBePersonName(String s, Language lang)` Returns true if it is possible that the string is a person name
`String`	`describe()` Returns a description
`static InputStream`	`getConfigFileStream(String configfile)`
`static void`	`init()` Simply call this function to initialize NameML with the default values
`static void`	`init(NonsharedParameters params)`
`static void`	`init(String configPath)` If you like to use your own stopword lists etc.
`static boolean`	`isAbbreviation(String word)` Tells whether a string is an abbreviation with high probability
`static boolean`	`isAttributePrefix(String s)` Says whether this String is an attribute Prefix (like "the" in "Alexander the Great")
`static boolean`	`isCompanyName(String s)` Tells if the string is a company name with high probability
`static boolean`	`isCompanyNameSuffix(String s)` Says whether this String is a company name suffix
`static boolean`	`isFamilyNamePrefix(String s)` Says whether this String is a family name prefix
`static boolean`	`isLanguage(String s)` Returns TRUE for languages
`static boolean`	`isLanguageCode(String s)` Returns TRUE for language codes
`static boolean`	`isName(String s)` Tells whether a String is a name with high probability
`static boolean`	`isNames(String s)` Tells whether a String is a sequence of names with high probability
`static boolean`	`isNation(String s)` Returns TRUE for nations
`static boolean`	`isNationality(String s)` Returns TRUE for nationalities
`static boolean`	`isPersonName(String m, Language lang)` Returns true if it is highly probable that the string is a person name.
`static boolean`	`isPersonNameSuffix(String s)` Says whether this String is a person name suffix
`static boolean`	`isStopWord(String w, Language l)` TRUE for stopwords
`static boolean`	`isTitle(String s, Language lang)` Says whether this String is a title
`static boolean`	`isUSState(String s)` Returns TRUE for US States
`static boolean`	`isUSStateAbbreviation(String s)` Returns TRUE for US State abbreviations
`static String`	`languageForCode(String s)` Returns the language for a code (or NULL)
`static void`	`main(String[] argv)` Test routine
`static String`	`mul(String s)` Repeats the token with blanks one or more times
`static String`	`mulHyp(String s)` Repeats the token with hyphens one or more times
`static String`	`nationForNationality(String s)` Returns the nation for a nationality (or NULL)
`String`	`normalize()` Returns the letters and digits of the original name (eliminates punctuation)
`static NameML`	`of(String s, Language lang)` Factory pattern
`static String`	`opt(String s)` optional component
`static String`	`optMul(String s)` optional multiple component
`static String`	`or(String s1, String s2)` alternative
`String`	`original()` Returns the original name
`static List<String>`	`readTextFileLines(String configFile, String encoding)` Read an entire text file as a list of strings.
`static Set<String>`	`readTextFileLinesSet(String configFile)` Read set from an UTF-8 text file, ignoring lines starting with "##"
`String`	`toString()` Returns the original name
`static String`	`unabbreviateUSState(String s)` Returns the US sate for an abbreviation (or NULL)

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - ANYNAME
```
public static final String ANYNAME
```
    Holds the general default name
    
    See Also:
    
    Constant Field Values
  - hasBeenInitialized
```
protected static boolean hasBeenInitialized
```
  - roman
```
public static String roman
```
    Contains romam digits
  - of
```
public static String of
```
    Contains the English "of"
  - U
```
public static final String U
```
    Contains upper case Characters
    
    See Also:
    
    Constant Field Values
  - L
```
public static final String L
```
    Contains lower case Characters
    
    See Also:
    
    Constant Field Values
  - A
```
public static final String A
```
    Contains characters
    
    See Also:
    
    Constant Field Values
  - B
```
public static final String B
```
    Contains blank
    
    See Also:
    
    Constant Field Values
  - BD
```
public static final String BD
```
    Contains a word boundary
    
    See Also:
    
    Constant Field Values
  - BC
```
public static final String BC
```
    Contains blank with optional comma
    
    See Also:
    
    Constant Field Values
  - DG
```
public static final String DG
```
    Contains digits
    
    See Also:
    
    Constant Field Values
  - H
```
public static final String H
```
    Contains hypens
    
    See Also:
    
    Constant Field Values
  - or
```
public static final String or
```
    Contains "|"
    
    See Also:
    
    Constant Field Values
  - familyNamePrefix
```
public static final String familyNamePrefix
```
    Contains common family name prefixes (like "von")
    
    See Also:
    
    Constant Field Values
  - familyNamePrefixPattern
```
public static final Pattern familyNamePrefixPattern
```
  - attributePrefix
```
public static String attributePrefix
```
    Contains attribute Prefixes (like "the" in "Alexander the Great")
  - attributePrefixPattern
```
public static Pattern attributePrefixPattern
```
  - familyNameSuffix
```
public static final String familyNameSuffix
```
    Contains common name suffixes (like "Junior")
    
    See Also:
    
    Constant Field Values
  - familyNameSuffixPattern
```
public static final Pattern familyNameSuffixPattern
```
  - titlePatternEn
```
public static Pattern titlePatternEn
```
    Matches common titles (like "Mr.")
  - titlePatternDe
```
public static Pattern titlePatternDe
```
  - titlePatternFr
```
public static Pattern titlePatternFr
```
  - titlePatternEs
```
public static Pattern titlePatternEs
```
  - titlePatternIt
```
public static Pattern titlePatternIt
```
  - titlesForGivenNamesEn
```
protected static Set<String> titlesForGivenNamesEn
```
    Contains those titles that go with the given name (e.g. "Queen" in "Queen Elisabeth"), lowercase
  - titlesForGivenNamesDe
```
protected static Set<String> titlesForGivenNamesDe
```
  - titlesForGivenNamesEs
```
protected static Set<String> titlesForGivenNamesEs
```
  - titlesForGivenNamesFr
```
protected static Set<String> titlesForGivenNamesFr
```
  - titlesForGivenNamesIt
```
protected static Set<String> titlesForGivenNamesIt
```
  - stopWordDE
```
protected static Set<String> stopWordDE
```
  - stopWordFR
```
protected static Set<String> stopWordFR
```
  - stopWordES
```
protected static Set<String> stopWordES
```
  - stopWordEN
```
protected static Set<String> stopWordEN
```
  - stopWordIT
```
protected static Set<String> stopWordIT
```
  - companyNameSuffix
```
public static final String companyNameSuffix
```
    Contains common company name suffixes (like "Inc")
    
    See Also:
    
    Constant Field Values
  - companyNameSuffixPattern
```
public static final Pattern companyNameSuffixPattern
```
  - teamName
```
public static final String teamName
```
    team name
    
    See Also:
    
    Constant Field Values
  - teamNamePattern
```
public static final Pattern teamNamePattern
```
  - prep
```
public static final String prep
```
    Contains prepositions
    
    See Also:
    
    Constant Field Values
  - laxName
```
public static final String laxName
```
    Contains the pattern for names. Practically everything is a name if it starts with an uppercase letter
    
    See Also:
    
    Constant Field Values
  - laxNamePattern
```
public static final Pattern laxNamePattern
```
    Contains the pattern for names. Practically everything is a name if it starts with an uppercase letter
  - safeName
```
public static final String safeName
```
    Contains a pattern that indicates strings that are very likely to be names
    
    See Also:
    
    Constant Field Values
  - safeNamePattern
```
public static final Pattern safeNamePattern
```
    Contains a pattern that indicates strings that are very likely to be names
  - safeNamesPattern
```
public static final Pattern safeNamesPattern
```
    Contains a pattern that indicates strings that are very likely to be names
  - safeNamesPatternNoPrep
```
public static final Pattern safeNamesPatternNoPrep
```
    Contains a pattern that indicates strings that are very likely to be names
  - original
```
protected String original
```
    Holds the original name
  - normalized
```
protected String normalized
```
    Holds the normalized name
  - laxAbbreviationPattern
```
public static final Pattern laxAbbreviationPattern
```
    Contains the lax pattern for abbreviations
  - safeAbbreviationPattern
```
public static final Pattern safeAbbreviationPattern
```
    Contains the safe pattern for abbreviations
  - laxCompanyPattern
```
public static final Pattern laxCompanyPattern
```
    Contains the pattern for companies
  - safeCompanyPattern
```
public static final Pattern safeCompanyPattern
```
    Contains the safe pattern for companies
  - directFamilyNamePrefix
```
public static final String directFamilyNamePrefix
```
    A direct family name prefix (such as "Mc")
    
    See Also:
    
    Constant Field Values
  - personNameComponent
```
public static final String personNameComponent
```
    The pattern "Name"
    
    See Also:
    
    Constant Field Values
  - givenNameComponent
```
public static final String givenNameComponent
```
    The pattern "Name."
  - givenName
```
public static final String givenName
```
    The pattern "Name[-Name]"
  - givenNames
```
public static final String givenNames
```
    The pattern (personNameComponent+B)+
  - familyName
```
public static final String familyName
```
    Name component with an optional familyNamePrefix and postfix
  - nickName
```
public static final String nickName
```
    Nickname '...'
    
    See Also:
    
    Constant Field Values
  - laxPersonNamePatternEn
```
public static Pattern laxPersonNamePatternEn
```
  - laxPersonNamePatternDe
```
public static Pattern laxPersonNamePatternDe
```
  - laxPersonNamePatternEs
```
public static Pattern laxPersonNamePatternEs
```
  - laxPersonNamePatternFr
```
public static Pattern laxPersonNamePatternFr
```
  - laxPersonNamePatternIt
```
public static Pattern laxPersonNamePatternIt
```
  - safePersonNamePatternEn
```
public static Pattern safePersonNamePatternEn
```
  - safePersonNamePatternDe
```
public static Pattern safePersonNamePatternDe
```
  - safePersonNamePatternEs
```
public static Pattern safePersonNamePatternEs
```
  - safePersonNamePatternFr
```
public static Pattern safePersonNamePatternFr
```
  - safePersonNamePatternIt
```
public static Pattern safePersonNamePatternIt
```
  - usStates
```
public static Map<String,String> usStates
```
  - languageCodes
```
public static Map<String,String> languageCodes
```
    Language codes
  - nationality2country
```
public static Map<String,String> nationality2country
```
- Constructor Detail
  - NameML
```
protected NameML(String s)
```
    Constructor (for subclasses only; use Name.of instead!)
- Method Detail
  - init
```
public static final void init(NonsharedParameters params)
```
  - init
```
public static final void init(String configPath)
```
    If you like to use your own stopword lists etc. (see javatools.resources.parsing) then you can set a path where NameML will look for such files instead of the default resource location (javatools.resources.parsing). (To make sure that you cover all files necessary in your own word list set, best start by copying the files from src/javatools/resources/parsing/.)
    
    Parameters:
    
    configPath - The path that contains all word lists.
  - init
```
public static final void init()
```
    Simply call this function to initialize NameML with the default values
  - mul
```
public static String mul(String s)
```
    Repeats the token with blanks one or more times
  - mulHyp
```
public static String mulHyp(String s)
```
    Repeats the token with hyphens one or more times
  - opt
```
public static String opt(String s)
```
    optional component
  - optMul
```
public static String optMul(String s)
```
    optional multiple component
  - or
```
public static String or(String s1,
                        String s2)
```
    alternative
  - c
```
public static String c(String s)
```
    Capturing group
  - isFamilyNamePrefix
```
public static boolean isFamilyNamePrefix(String s)
```
    Says whether this String is a family name prefix
  - isAttributePrefix
```
public static boolean isAttributePrefix(String s)
```
    Says whether this String is an attribute Prefix (like "the" in "Alexander the Great")
  - isPersonNameSuffix
```
public static boolean isPersonNameSuffix(String s)
```
    Says whether this String is a person name suffix
  - isTitle
```
public static boolean isTitle(String s,
                              Language lang)
```
    Says whether this String is a title
  - isCompanyNameSuffix
```
public static boolean isCompanyNameSuffix(String s)
```
    Says whether this String is a company name suffix
  - isName
```
public static boolean isName(String s)
```
    Tells whether a String is a name with high probability
  - isNames
```
public static boolean isNames(String s)
```
    Tells whether a String is a sequence of names with high probability
  - couldBeName
```
public static boolean couldBeName(String s)
```
    Tells whether a String could possibly be a name
  - isStopWord
```
public static boolean isStopWord(String w,
                                 Language l)
```
    TRUE for stopwords
  - toString
```
public String toString()
```
    Returns the original name
    
    Overrides:
    
    toString in class Object
  - normalize
```
public String normalize()
```
    Returns the letters and digits of the original name (eliminates punctuation)
  - describe
```
public String describe()
```
    Returns a description
  - original
```
public String original()
```
    Returns the original name
  - readTextFileLines
```
public static List<String> readTextFileLines(String configFile,
                                             String encoding)
                                      throws IOException
```
    Read an entire text file as a list of strings. The strings do not include a terminating new line character.
    
    Parameters:
    
    configFile - text file to open
    
    encoding - character encoding name (as used by Java) or null for UTF-8
    
    Returns:
    
    contents of file
    
    Throws:
    
    IOException
  - getConfigFileStream
```
public static InputStream getConfigFileStream(String configfile)
                                       throws FileNotFoundException
```
    Throws:
    
    FileNotFoundException
  - readTextFileLinesSet
```
public static Set<String> readTextFileLinesSet(String configFile)
```
    Read set from an UTF-8 text file, ignoring lines starting with "##"
    
    Parameters:
    
    configFile -
    
    Returns:
    
    set of strings
  - isAbbreviation
```
public static boolean isAbbreviation(String word)
```
    Tells whether a string is an abbreviation with high probability
  - couldBeAbbreviation
```
public static boolean couldBeAbbreviation(String word)
```
    Tells whether a string could be abbreviation.
  - isCompanyName
```
public static boolean isCompanyName(String s)
```
    Tells if the string is a company name with high probability
  - couldBeCompanyName
```
public static boolean couldBeCompanyName(String s)
```
    Tells if the string could be a company name
  - couldBePersonName
```
public static boolean couldBePersonName(String s,
                                        Language lang)
```
    Returns true if it is possible that the string is a person name
  - isPersonName
```
public static boolean isPersonName(String m,
                                   Language lang)
```
    Returns true if it is highly probable that the string is a person name.
  - isUSState
```
public static boolean isUSState(String s)
```
    Returns TRUE for US States
  - isUSStateAbbreviation
```
public static boolean isUSStateAbbreviation(String s)
```
    Returns TRUE for US State abbreviations
  - unabbreviateUSState
```
public static String unabbreviateUSState(String s)
```
    Returns the US sate for an abbreviation (or NULL)
  - isLanguage
```
public static boolean isLanguage(String s)
```
    Returns TRUE for languages
  - isLanguageCode
```
public static boolean isLanguageCode(String s)
```
    Returns TRUE for language codes
  - languageForCode
```
public static String languageForCode(String s)
```
    Returns the language for a code (or NULL)
  - isNation
```
public static boolean isNation(String s)
```
    Returns TRUE for nations
  - isNationality
```
public static boolean isNationality(String s)
```
    Returns TRUE for nationalities
  - nationForNationality
```
public static String nationForNationality(String s)
```
    Returns the nation for a nationality (or NULL)
  - of
```
public static NameML of(String s,
                        Language lang)
```
    Factory pattern
  - main
```
public static void main(String[] argv)
                 throws Exception
```
    Test routine
    
    Throws:
    
    Exception

Class NameML

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ANYNAME

hasBeenInitialized

roman

of

U

L

A

B

BD

BC

DG

H

or

familyNamePrefix

familyNamePrefixPattern

attributePrefix

attributePrefixPattern

familyNameSuffix

familyNameSuffixPattern

titlePatternEn

titlePatternDe

titlePatternFr

titlePatternEs

titlePatternIt

titlesForGivenNamesEn

titlesForGivenNamesDe

titlesForGivenNamesEs

titlesForGivenNamesFr

titlesForGivenNamesIt

stopWordDE

stopWordFR

stopWordES

stopWordEN

stopWordIT

companyNameSuffix

companyNameSuffixPattern

teamName

teamNamePattern

prep

laxName

laxNamePattern

safeName

safeNamePattern

safeNamesPattern

safeNamesPatternNoPrep

original

normalized

laxAbbreviationPattern

safeAbbreviationPattern

laxCompanyPattern

safeCompanyPattern

directFamilyNamePrefix

personNameComponent

givenNameComponent

givenName

givenNames

familyName

nickName

laxPersonNamePatternEn

laxPersonNamePatternDe

laxPersonNamePatternEs

laxPersonNamePatternFr

laxPersonNamePatternIt

safePersonNamePatternEn

safePersonNamePatternDe

safePersonNamePatternEs

safePersonNamePatternFr

safePersonNamePatternIt

usStates

languageCodes

nationality2country

Constructor Detail

NameML