001package org.gbif.api.service.checklistbank;
002
003import org.gbif.api.exception.UnparsableException;
004import org.gbif.api.model.checklistbank.ParsedName;
005import org.gbif.api.vocabulary.Rank;
006
007import javax.annotation.Nullable;
008
009/**
010 * Interface for parsing scientific names.
011 */
012public interface NameParser {
013
014  /**
015   * Fully parse the supplied name also trying to extract authorships, a conceptual sec reference, remarks or notes
016   * on the nomenclatural status. In some cases the authorship parsing proves impossible and this nameparser will
017   * return null.
018   *
019   * For strings which are no scientific names and scientific names that cannot be expressed by the ParsedName class
020   * the parser will throw an UnparsableException with a given NameType and the original, unparsed name. This is the
021   * case for all virus names and proper hybrid formulas, so make sure you catch and process this exception.
022   *
023   * @param scientificName the full scientific name to parse
024   * @param rank the rank of the name if it is known externally. Helps identifying infrageneric names vs bracket authors
025   *
026   * @return the parsed name
027   *
028   * @throws UnparsableException
029   */
030  ParsedName parse(String scientificName, @Nullable Rank rank) throws UnparsableException;
031
032  /**
033   * Delegate method to parse a scientific name of unknown rank.
034   * @return the parsed name
035   */
036  ParsedName parse(String scientificName) throws UnparsableException;
037
038  /**
039   * Fully parses a name using #parse(String, Rank) but converts names that throw a UnparsableException
040   * into ParsedName objects with the scientific name, rank and name type given.
041   * @return the parsed name
042   */
043  ParsedName parseQuietly(String scientificName, @Nullable Rank rank);
044
045  /**
046   * Delegate method to parse a scientific name of unknown rank quietly.
047   * @return the parsed name
048   */
049  ParsedName parseQuietly(String scientificName);
050
051  /**
052   * Parses the scientific name without authorship and returns the ParsedName.canonicalName() string
053   * @param scientificName the full scientific name to parse
054   * @param rank the rank of the name if it is known externally. Helps identifying infrageneric names vs bracket authors
055   *
056   * @return the canonical name or null for unparsable names
057   */
058  String parseToCanonical(String scientificName, @Nullable Rank rank);
059
060  /**
061   * Delegate method to parse a scientific name of unknown rank and return its canonical form.
062   */
063  String parseToCanonical(String scientificName);
064
065}