ari.ucidy

Class UCDParser

java.lang.Object

ari.ucidy.UCDParser

public class UCDParser
extends java.lang.Object

Object that lets parse a UCD (parseUCD(String)) or a list of UCD word (parseWordList(Reader, boolean)).

Default parser

Though the static function parseUCD(String) is using a UCDParser already initialized with the list of all official IVOA UCD words (see defaultParser), it is possible to create an instance of UCDParser with a custom list of UCD words.

Default main program

The main function of this parser prompts for a UCD, parses this UCD and finally returns some information about it.

Versions

To get more information about the version of the parser and/or the words lists, use the following functions:

• UCIDY_VERSION
• knownWords.getVersion()
• deprecatedWords.getVersion()

Version:

1.2 (11/2021)

Author:

Grégory Mantelet (CDS)

Field Summary

Fields

Modifier and Type	Field and Description
static UCDParser	defaultParser Default UCD parser which is initialized with a list of only the official IVOA UCD words and the deprecated ones (for better error messages and suggestions).
DeprecatedUCDWordList	deprecatedWords List of all deprecated words.
static java.lang.String	FILE_UCD_DEPRECATED Default path to the file listing all deprecated UCD words and their replacement.
static java.lang.String	FILE_UCD_WORDS Default path to the PSV file listing all official IVOA UCDs.
UCDWordList	knownWords List of all known words.
protected static java.util.logging.Logger	LOGGER Logger used to report errors during the initialization of the default UCDParser.
protected static int	NB_MAX_ERRORS Maximum number of consecutive errors while parsing a PSV file, before stopping the parsing.
static java.lang.String	UCIDY_VERSION Current version of this Ucidy instance.
static java.lang.String	VERSION_UCD_WORDS Version of the UCD words listed in FILE_UCD_WORDS and FILE_UCD_DEPRECATED.

Constructor Summary

Constructors

Constructor and Description
UCDParser() Create a UCD parser with an empty list of known words.
UCDParser(java.lang.String wordsListVersion) Create a UCD parser with an empty list of known words with a declared version.
UCDParser(UCDWordList words) Build a UCD parser with the given list of known words.
UCDParser(UCDWordList words, DeprecatedUCDWordList deprecatedWords) Build a UCD parser with the given list of known words and a given list of deprecated UCD words.

Method Summary

Modifier and Type	Method and Description
java.lang.String	getFullVersion() Get a paragraph giving the version of this parser and the version of all used lists.
static java.lang.String	getVersion() Get the Ucidy/parser version.
static void	main(java.lang.String[] args)
UCD	parse(java.lang.String ucdStr) Parse the given string representing a UCD into an object representation: UCD.
static java.lang.String[]	parseDeprecatedFileLine(java.lang.String line) Parse a line of a file listing the deprecated UCD words.
static DeprecatedUCDWordList	parseDeprecatedWordList(java.io.Reader reader, UCDWordList lstWords) Create a DeprecatedUCDWordList with all deprecated UCD words declared inside the specified input.
static int	parseDeprecatedWordList(java.io.Reader reader, UCDWordList lstWords, DeprecatedUCDWordList lstDeprecatedWords) Add inside the given UCDWordList all deprecated UCD words declared inside the specified input.
static UCDWord	parsePSVLine(java.lang.String psvLine, boolean recommended) Parse a line of a PSV (Pipe Separated Value) file as the definition of a UCD word.
static UCD	parseUCD(java.lang.String ucdStr) Parse the given UCD and try to resolve each word as a known UCD word among the IVOA official list.
static UCDWordList	parseWordList(java.io.Reader reader, boolean recommended) Create a UCDWordList with all UCD words declared using the PSV (Pipe-Separated-Value) format inside the specified input.
static int	parseWordList(java.io.Reader reader, boolean recommended, UCDWordList words) Add inside the given UCDWordList all UCD words declared using the PSV (Pipe-Separated-Value) format inside the specified input.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

defaultParser

public static final UCDParser defaultParser

Default UCD parser which is initialized with a list of only the official IVOA UCD words and the deprecated ones (for better error messages and suggestions).

This parser is generally used through parseUCD(String) but could be used directly.

Note: Initialization errors and warnings are reported using the Java Util Logging API (JUL).

deprecatedWords

public final DeprecatedUCDWordList deprecatedWords

List of all deprecated words.

Important: When a UCD word can not be resolved, this UCDParser will try to find it among the deprecated words. If a match is found, the suggested UCD replacement will be proposed to the user.

This field is NEVER null.

Since:

1.1

FILE_UCD_DEPRECATED

public static final java.lang.String FILE_UCD_DEPRECATED

Default path to the file listing all deprecated UCD words and their replacement.

This path must be relative to the class path.

See parseDeprecatedWordList(Reader, UCDWordList) for more details about the expected file format.

Important: This list of deprecated words should be for the same UCD standard version than FILE_UCD_WORDS.

Since:

1.2

See Also:

Constant Field Values

FILE_UCD_WORDS

public static final java.lang.String FILE_UCD_WORDS

Default path to the PSV file listing all official IVOA UCDs.

This path must be relative to the class path.

See parseWordList(Reader, boolean) for more details about the expected file format.

Since:

1.2

See Also:

Constant Field Values

knownWords

public final UCDWordList knownWords

List of all known words.

Important: "Known" means here that all words of this list will be used as reference when building a UCD object when the corresponding UCD word match the listed UCDWord. So it means there is no guarantee that ALL UCDWord objects stored in this list are valid, recognised and/or recommended. This special status of a UCDWord depends of its initialization.

This field is NEVER null.

LOGGER

protected static final java.util.logging.Logger LOGGER

Logger used to report errors during the initialization of the default UCDParser.

Since:

1.2

NB_MAX_ERRORS

protected static final int NB_MAX_ERRORS

Maximum number of consecutive errors while parsing a PSV file, before stopping the parsing.

See Also:

Constant Field Values

UCIDY_VERSION

public static final java.lang.String UCIDY_VERSION

Current version of this Ucidy instance.

Since:

1.2

See Also:

Constant Field Values

VERSION_UCD_WORDS

public static final java.lang.String VERSION_UCD_WORDS

Version of the UCD words listed in FILE_UCD_WORDS and FILE_UCD_DEPRECATED.

Since:

1.2

See Also:

Constant Field Values

Constructor Detail

UCDParser

public UCDParser()

Create a UCD parser with an empty list of known words.

You can however fill this list directly through the field knownWords.

Note: The list of deprecated words is also empty by default. As for the known words, this list can be updated directly through the field deprecatedWords.

UCDParser

public UCDParser(java.lang.String wordsListVersion)

Create a UCD parser with an empty list of known words with a declared version.

You can however fill this list directly through the field knownWords.

Note: The list of deprecated words is also empty by default. As for the known words, this list can be updated directly through the field deprecatedWords.

Parameters:

wordsListVersion - Version of the empty UCD words lists created by default.

Since:

1.2

UCDParser

public UCDParser(UCDWordList words)

Build a UCD parser with the given list of known words.

Note: The given list can obviously be modified (i.e. addition and deletion are allowed) through the field knownWords or directly when manipulating the given list (it is stored in this UCDParser object by reference).

Parameters:

words - List of all known words.

UCDParser

public UCDParser(UCDWordList words,
                 DeprecatedUCDWordList deprecatedWords)

Build a UCD parser with the given list of known words and a given list of deprecated UCD words.

Note: The given lists can obviously be modified (i.e. addition and deletion are allowed) through the fields knownWords and deprecatedWords or directly when manipulating the given lists (they are stored in this UCDParser object by reference).

Parameters:

words - List of all known words.

deprecatedWords - List of all deprecated words.

Since:

1.1

Method Detail

getFullVersion

public final java.lang.String getFullVersion()

Get a paragraph giving the version of this parser and the version of all used lists.

Returns:

String describing all versions involved in this parser.

Since:

1.2

See Also:

getVersion(), UCDWordList.getVersion(), UCDWordList.getVersion()

getVersion

public static final java.lang.String getVersion()

Get the Ucidy/parser version.

Note: This function is equivalent to UCIDY_VERSION.

Returns:

Parser version.

Since:

1.2

main

public static void main(java.lang.String[] args)
                 throws java.lang.Throwable

Throws:

java.lang.Throwable

parse

public UCD parse(java.lang.String ucdStr)

Parse the given string representing a UCD into an object representation: UCD.

Each word of this UCD is searched in the list of known UCD words. If a match is found, the full definition of this UCD will be set in UCD. If none can be found, the word is searched in the list of deprecated words. If still not found, a not recognised UCDWord will be created instead, with a list of the closest recognised UCD words (if any).

Parameters:

ucdStr - The string serializing a UCD.

Returns:

The object representation of this UCD, or null if the given string is null or empty.

parseDeprecatedFileLine

public static java.lang.String[] parseDeprecatedFileLine(java.lang.String line)
                                                  throws java.lang.NullPointerException,
                                                         java.text.ParseException

Parse a line of a file listing the deprecated UCD words.

The expected syntax for a such line is 2 values separated by a space: the deprecated UCD word followed by a suggested UCD in replacement.

Note: Concatenated space characters will be replaced by a single space on each line. Besides, leading and trailing space characters will be ignored.

WARNING: Comment lines (i.e. starting with the character #) are not supported. This function will throw a NullPointerException in such case, as if an empty line was provided.

Parameters:

line - A non empty and not commented line of a file listing the deprecated UCD words.

Returns:

The corresponding deprecated UCD word and its suggested UCD replacement.

Throws:

java.lang.NullPointerException - If the given line is null, an empty string or a comment.

java.text.ParseException - If the given line has no space character or has too many.

Since:

1.1

parseDeprecatedWordList

public static DeprecatedUCDWordList parseDeprecatedWordList(java.io.Reader reader,
                                                            UCDWordList lstWords)
                                                     throws java.lang.NullPointerException,
                                                            java.io.IOException

Create a DeprecatedUCDWordList with all deprecated UCD words declared inside the specified input.

The expected file MUST contain exactly 2 columns, separated by at least one space character:

1. Word: the deprecated UCD word.
2. Suggested replacement: the UCD suggested to replace the deprecated UCD word.

If the syntax of a line is incorrect, an error message will be displayed in the standard error output. If more than 10 consecutive errors are raised, the parsing of the file stops immediately with a new error message.

A line is considered as incorrect in the following cases:

• there are less or more than 2 columns
• there is no UCD word (first column)
• there is no suggested UCD replacement (second column)
• the UCD word has an incorrect syntax
• the UCD word is already listed as non-deprecated in the given words list
• the suggested UCD replacement is is not fully valid (i.e. correct syntax + all words recognised)

If a deprecated UCD word is declared more than once, only the first occurrence will stay in the list. An error will be displayed only if the suggested UCD replacement is different. Otherwise just a warning is displayed.

Few additional notes about the parsing:

• All leading and trailing spaces of each column value are removed.

Parameters:

reader - Reader whose the content must be parsed.

lstWords - The list of all known and still correct UCD words.

Returns:

The list of all successfully parsed deprecated UCD words.

Throws:

java.lang.NullPointerException - If the given reader is null.

java.io.IOException - If an error occurred while reading the specified input.

Since:

1.1

See Also:

parseDeprecatedWordList(Reader, UCDWordList, DeprecatedUCDWordList)

parseDeprecatedWordList

public static int parseDeprecatedWordList(java.io.Reader reader,
                                          UCDWordList lstWords,
                                          DeprecatedUCDWordList lstDeprecatedWords)
                                   throws java.lang.NullPointerException,
                                          java.io.IOException

Add inside the given UCDWordList all deprecated UCD words declared inside the specified input.

The expected file MUST contain exactly 2 columns, separated by at least one space character:

1. Word: the deprecated UCD word.
2. Suggested replacement: the UCD suggested to replace the deprecated UCD word.

If the syntax of a line is incorrect, an error message will be displayed in the standard error output. If more than 10 consecutive errors are raised, the parsing of the file stops immediately with a new error message.

A line is considered as incorrect in the following cases:

• there are less or more than 2 columns
• there is no UCD word (first column)
• there is no suggested UCD replacement (second column)
• the UCD word has an incorrect syntax
• the UCD word is already listed as non-deprecated in the given words list
• the suggested UCD replacement is is not fully valid (i.e. correct syntax + all words recognised)

If a deprecated UCD word is declared more than once, only the first occurrence will stay in the list. An error will be displayed only if the suggested UCD replacement is different. Otherwise just a warning is displayed.

Few additional notes about the parsing:

• All leading and trailing spaces of each column value are removed.

Parameters:

reader - Reader whose the content must be parsed.

lstWords - The list of all known and still correct UCD words.

lstDeprecatedWords - The DeprecatedUCDWordList to complete with the deprecated UCD words extracted from the given input.

Returns:

The number of successfully added deprecated UCD words extracted from the input.

Throws:

java.lang.NullPointerException - If the given reader is null.

java.io.IOException - If an error occurred while reading the specified input.

Since:

1.1

See Also:

parseDeprecatedFileLine(String)

parsePSVLine

public static UCDWord parsePSVLine(java.lang.String psvLine,
                                   boolean recommended)
                            throws java.lang.NullPointerException,
                                   java.text.ParseException

Parse a line of a PSV (Pipe Separated Value) file as the definition of a UCD word.

Parameters:

psvLine - A non empty line of a PSV file listing the allowed UCD words.

recommended - true if the described UCD word is UCDWord.recommended by the IVOA standard, false otherwise.

Returns:

The corresponding UCD word.

Throws:

java.lang.NullPointerException - If the given PSV line is null or an empty string.

java.text.ParseException - If the syntax of the given PSV line is incorrect (expected syntax: ()), or if the syntax code is too long or unknown.

See Also:

UCDSyntax.get(char), UCDSyntax.allowedSyntaxCodes

parseUCD

public static UCD parseUCD(java.lang.String ucdStr)

Parse the given UCD and try to resolve each word as a known UCD word among the IVOA official list.

Non resolved words, will still be in the returned UCD exactly as provided, but won't be flagged as recognised. The consequence is a final non fully valid UCD.

Parameters:

ucdStr - The string serializing a UCD.

Returns:

The parsed UCD, or null if the given string is null or empty.

See Also:

parse(String)

parseWordList

public static UCDWordList parseWordList(java.io.Reader reader,
                                        boolean recommended)
                                 throws java.lang.NullPointerException,
                                        java.io.IOException

Create a UCDWordList with all UCD words declared using the PSV (Pipe-Separated-Value) format inside the specified input.

The expected PSV file MUST contain at least 3 columns, each separated by a pipe character (|):

1. Syntax code: a single character among P, S, Q, E, C and V. See UCDSyntax for more details.
2. Word: the UCD word itself.
3. Description: optional description of the UCD word.

Note: If more columns are provided, they will be considered as part of the description.

If the syntax of a PSV line is incorrect, an error message will be displayed in the standard error output. If more than 10 consecutive errors are raised, the parsing of the file stops immediately with a new error message.

A PSV line is considered as incorrect in the following cases:

• there are less than 3 columns (which includes the case where no pipe separator can be detected)
• there is no syntax code character (first column)
• there is no UCD word (second column)

Few additional notes about the parsing:

• All leading and trailing spaces of each column value are removed.
• If no description is provided, UCDWord.description will be set to null.
• An unknown syntax code character is permitted, but will flag the resulting UCDWord as NOT recommended.
• An incorrect UCD word structure is permitted, but will flag the resulting UCDWordList as NOT valid and so automatically as NOT recommended.

Parameters:

reader - Reader whose the content must be parsed.

recommended - true to flag all imported UCD words as recommended, false otherwise.

Returns:

The list of all successfully parsed UCD words.

Throws:

java.lang.NullPointerException - If the given reader is null.

java.io.IOException - If an error occurred while reading the specified input.

parseWordList

public static int parseWordList(java.io.Reader reader,
                                boolean recommended,
                                UCDWordList words)
                         throws java.lang.NullPointerException,
                                java.io.IOException

Add inside the given UCDWordList all UCD words declared using the PSV (Pipe-Separated-Value) format inside the specified input.

The expected PSV file MUST contain at least 3 columns, each separated by a pipe character (|):

1. Syntax code: a single character among P, S, Q, E, C and V. See UCDSyntax for more details.
2. Word: the UCD word itself.
3. Description: optional description of the UCD word.

Note: If more columns are provided, they will be considered as part of the description.

If the syntax of a PSV line is incorrect, an error message will be displayed in the standard error output. If more than 10 consecutive errors are raised, the parsing of the file stops immediately with a new error message.

A PSV line is considered as incorrect in the following cases:

• there are less than 3 columns (which includes the case where no pipe separator can be detected)
• there is no syntax code character (first column)
• there is no UCD word (second column)

Few additional notes about the parsing:

• All leading and trailing spaces of each column value are removed.
• If no description is provided, UCDWord.description will be set to null.
• An unknown syntax code character is permitted, but will flag the resulting UCDWord as NOT recommended.
• An incorrect UCD word structure is permitted, but will flag the resulting UCDWordList as NOT valid and so automatically as NOT recommended.

Parameters:

reader - Reader whose the content must be parsed.

recommended - true to flag all imported UCD words as recommended, false otherwise.

words - The UCDWordList to complete with the UCD words extracted from the given input.

Returns:

The number of successfully added UCD words extracted from the input.

Throws:

java.lang.NullPointerException - If the given reader is null.

java.io.IOException - If an error occurred while reading the specified input.