001/*
002 * Copyright 2020 Global Biodiversity Information Facility (GBIF)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.gbif.api.service.checklistbank;
017
018import org.gbif.api.exception.UnparsableException;
019import org.gbif.api.model.checklistbank.ParsedName;
020import org.gbif.api.vocabulary.Rank;
021
022import javax.annotation.Nullable;
023
024/**
025 * Interface for parsing scientific names.
026 */
027public interface NameParser {
028
029  /**
030   * Fully parse the supplied name also trying to extract authorships, a conceptual sec reference, remarks or notes
031   * on the nomenclatural status. In some cases the authorship parsing proves impossible and this nameparser will
032   * return null.
033   *
034   * For strings which are no scientific names and scientific names that cannot be expressed by the ParsedName class
035   * the parser will throw an UnparsableException with a given NameType and the original, unparsed name. This is the
036   * case for all virus names and proper hybrid formulas, so make sure you catch and process this exception.
037   *
038   * @param scientificName the full scientific name to parse
039   * @param rank the rank of the name if it is known externally. Helps identifying infrageneric names vs bracket authors
040   *
041   * @return the parsed name
042   *
043   * @throws UnparsableException
044   */
045  ParsedName parse(String scientificName, @Nullable Rank rank) throws UnparsableException;
046
047  /**
048   * Delegate method to parse a scientific name of unknown rank.
049   * @return the parsed name
050   */
051  ParsedName parse(String scientificName) throws UnparsableException;
052
053  /**
054   * Fully parses a name using #parse(String, Rank) but converts names that throw a UnparsableException
055   * into ParsedName objects with the scientific name, rank and name type given.
056   * @return the parsed name
057   */
058  ParsedName parseQuietly(String scientificName, @Nullable Rank rank);
059
060  /**
061   * Delegate method to parse a scientific name of unknown rank quietly.
062   * @return the parsed name
063   */
064  ParsedName parseQuietly(String scientificName);
065
066  /**
067   * Parses the scientific name without authorship and returns the ParsedName.canonicalName() string
068   * @param scientificName the full scientific name to parse
069   * @param rank the rank of the name if it is known externally. Helps identifying infrageneric names vs bracket authors
070   *
071   * @return the canonical name or null for unparsable names
072   */
073  String parseToCanonical(String scientificName, @Nullable Rank rank);
074
075  /**
076   * Delegate method to parse a scientific name of unknown rank and return its canonical form.
077   */
078  String parseToCanonical(String scientificName);
079
080}