Class ADQLParser
Usage
The simplest way to use this parser is just to create a default ADQL
parser, and call the function parseQuery(String)
on the ADQL query
to evaluate.
Example:
try { // 1. CREATE A PARSER: ADQLParser parser = newADQLParser()
; // 2. PARSE AN ADQL QUERY: ADQLSet query = parser.parseQuery
("SELECT foo FROM bar WHERE stuff = 1"); System.out.println("((i)) Correct ADQL query ((i))"); System.out.println("((i)) As interpreted: ((i))\n " + query.toADQL().replaceAll("\n", "\n ")); } // 3. EVENTUALLY DEAL WITH ERRORS: catch(ParseException
ex) { System.err.println("((X)) INCORRECT QUERY! " + ex.getClass().getSimpleName() + " ((X))\n" + ex.getPosition() + " " + ex.getMessage()); }
In the above example, the parser runs with the minimal set of options. It
means that only the default optional language features are available, any
UDF (even if undeclared) and any coordinate system are allowed and no
consistency with a list of tables and columns is performed. These points can
be customized at creation with
ADQLParser(ADQLVersion, QueryChecker, ADQLQueryFactory, FeatureSet)
but also after creation with setSupportedFeatures(FeatureSet)
,
setQueryChecker(QueryChecker)
and
setAllowedCoordSys(Collection)
.
Runnable class
This class includes a main function and thus, can be executed directly. Its execution allows to parse an ADQL query. Then, in function of the passed parameters, it is possible to just check its syntax, translate it into SQL or try to fix the query.
To get help about this program, just run it with the argument
-h
or --help
:
java -jar adqllib.jar --help
ADQL version
It is able to deal with all versions of the ADQL grammar supported by this
library. All these versions are listed in the enumeration
ADQLParser.ADQLVersion
.
If a specific version of the grammar must be used, it must be specified in the constructor of the parser.
Example:
new
ADQLParser
(ADQLParser.ADQLVersion.V2_1
)
Main functions
Here are the key functions to use:
parseQuery(String)
(or any its alternative with an InputStream) to parse an input ADQL query String and get its corresponding ADQL treetryQuickFix(String)
to try fixing the most common issues with ADQL queries (e.g. Unicode confusable characters, unescaped ADQL identifiers, SQL reserved keywords, ...)setSupportedFeatures(FeatureSet)
to set which optional ADQL features are supported or not ; all optional features used in the query while being declared as un-supported will throw an error at the end of the parsingsetAllowedCoordSys(Collection)
to set which coordinate systems are allowed when specifying a geometric region (e.g. POINT, CIRCLE, REGION) ; note: this function is mainly useful with ADQL-2.0 because it is the only version in which the coordinate system parameter is mandatoryallowAnyUdf(boolean)
to support any undeclared User Defined Function. By default only UDFs declared as supported features are allowedallowExtendedRegionParam(boolean)
to allow any string expression and serialization as parameter of theREGION(...)
function. By default, only a string literal using a supported serialization (seeRegion.parse(String)
; e.g. DALI, STC/s) is allowed
Default general checks
This ADQL parser always performs some verification after the parsing of an
ADQL query. In addition of the syntax, this parser also ensures that no
unsupported optional language feature and no unsupported coordinate system
are used in parsed ADQL queries. If unsupported content is detected, a
ParseException
is immediately raised.
By default, all optional language features are supported, and any coordinate system is allowed.
By default, no undeclared UDF is allowed. To change this, use
allowAnyUdf(boolean)
.
By default, only a string literal using a supported serialization (e.g. DALI
and STC/s) is allowed as parameter of the REGION(...)
function.
It is however possible to accept any string expression or to support any
other serialization thanks to allowExtendedRegionParam(boolean)
.
Look at Region.parse(String)
to know the exhaustive list of
supported region serializations.
Custom checks
Besides the general checks, this parser allows the addition of a custom
validation. Thanks to a QueryChecker
object, it is able to check
each ADQLSet
just after its generation and the general checks. It
could be used, for instance, to check the consistency between the ADQL query
to parse and the "database" on which the query must be executed.
By default, there is no QueryChecker
. Thus you must either use an
already existing QueryChecker
or extend this latter to run your own
tests on the parsed ADQL queries.
DBChecker
is an extension of QueryChecker
able to check that
table and column names used in a query exist in a given set of DB metadata.
Custom Query Factory
To create an object representation of the given ADQL query, this parser
uses a ADQLQueryFactory
object. All parts of the ADQL grammar can
already be created with this object.
However, in some special cases, you may need to change the type of some
specific nodes of the generated ADQL tree (e.g. CONTAINS
). In
such case, you just have to extend the corresponding default object
(i.e. ContainsFunction
) and to extend the corresponding function of
ADQLQueryFactory
(i.e. createContains(...)). Then, give an instance
of this custom factory to the ADQLParser
, at
creation
or with the setter setQueryFactory(ADQLQueryFactory)
.
- Since:
- 2.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enum
Enumeration of all supported versions of the ADQL grammar. -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected String[]
List of all allowed coordinate systems.protected boolean
Indicate whether any UDF (even if not declared) should be considered as supported.protected String
A regular expression built using the list of allowed coordinate systems.static final ADQLParser.ADQLVersion
Version of the ADQL grammar to use when none is specified:2.0
.protected boolean
Indicate whether the REGION(...) function accepts any string expression and any serialization or only a string literal using a supported serialization (e.g.protected final ADQLGrammar
Grammar parser to use.protected QueryChecker
API to checkADQL queries
(sub-queries or not) just after their generation.protected QueryFixer
This object is used only when one of thetryQuickFix(String)
functions is called.protected FeatureSet
List of all supported features. -
Constructor Summary
ConstructorsConstructorDescriptionBuilds an ADQL query parser for the default (i.e.ADQLParser
(ADQLParser.ADQLVersion version) Builds an ADQL query parser for the specified version of the ADQL grammar.ADQLParser
(ADQLParser.ADQLVersion version, QueryChecker queryChecker, ADQLQueryFactory factory, FeatureSet features) Builds a parser whose the query to parse will have to be given as a String in parameter ofparseQuery(String)
. -
Method Summary
Modifier and TypeMethodDescriptionprotected void
Run all available checks on the given ADQL tree: the general checks: optional features support, region serializations, ... the custom checks (if any).void
allowAnyUdf
(boolean allowed) Let specify whether any UDF (even if not declared) should be considered as supported or not.void
allowExtendedRegionParam
(boolean allowed) Let specify whether the REGION(...) function accepts any string expression and any serialization or only a string literal using a supported serialization (e.g.protected void
checkCoordinateSystem
(CoordSys coordSys, ADQLOperand operand, UnresolvedIdentifiersException errors) Check whether the given coordinate system is allowed by this implementation.protected void
checkCoordinateSystem
(StringConstant adqlCoordSys, UnresolvedIdentifiersException errors) Parse and then check the coordinate system contained in the givenStringConstant
instance.protected void
checkRegion
(Region r, RegionFunction fct, UnresolvedIdentifiersException errors) Check the given region.protected ADQLSet
Run the query parsing, then, if successful, all the available checks on the parsing result (i.e.protected void
Run the general and common checks on the given ADQL tree.final ADQLParser.ADQLVersion
Get the ADQL grammar version followed by this parser.final String[]
Get the list of allowed coordinate systems.final ADQLGrammar
Get the internal grammar parser specific to the target ADQL version.final QueryChecker
Get the custom checker of parsed ADQL queries.final ADQLQueryFactory
Get the query factory used to create ADQL objects during the parsing of an ADQL query.final QueryFixer
Get the API used to attempt fixing given ADQL queries with the functionstryQuickFix(InputStream)
andtryQuickFix(String)
.final FeatureSet
Get the list of all supported features.static ADQLParser.ADQLVersion[]
Get the list of all supported ADQL grammar versions.static String
Build on the fly a human list of all supported ADQL grammar versions.boolean
Tell whether UDFs are considered as supported even if undeclared.boolean
Tell whether the REGION(...) function accepts any string expression and any serialization or only a string literal using a supported serialization (e.g.static final void
Parse the given ADQL query.final FromContent
Parse the givenFROM
clause.final ClauseADQL
<ADQLOperand> parseGroupBy
(String adql) Parse the givenGROUP BY
clause.final ClauseADQL
<ADQLOrder> parseOrderBy
(String adql) Parse the givenORDER BY
clause.final ADQLSet
parseQuery
(InputStream stream) Parses the query contained in the stream given in parameter.final ADQLSet
parseQuery
(String q) Parses the query string given in parameter.final ClauseSelect
parseSelect
(String adql) Parse the givenSELECT
clause.final ClauseConstraints
parseWhere
(String adql) Parse the givenWHERE
clause.protected void
resolveCoordinateSystems
(ADQLSet query, UnresolvedIdentifiersException errors) Search for all explicit coordinate system declarations, check their syntax and whether they are allowed by this implementation.protected void
resolveRegionExpressions
(ADQLSet query, UnresolvedIdentifiersException errors) Search for all region expressions inside the given query, parse them (and so check their syntax) and then determine whether the declared coordinate system and the expressed region are allowed in this implementation.final void
setAllowedCoordSys
(Collection<String> allowedCoordSys) Set the list of allowed coordinate systems.final void
setDebug
(boolean debug) Enable/Disable the debugging messages while parsing an ADQL expression.final void
Set a default set of supported language features in function of the target ADQL version.final void
setQueryChecker
(QueryChecker checker) Set a custom checker of parsed ADQL queries.final void
setQueryFactory
(ADQLQueryFactory factory) Set the query factory to use when creating ADQL objects during the parsing of an ADQL query.final void
setQuickFixer
(QueryFixer fixer) Set the tool to use in order to attempt fixing any given ADQL query with the functionstryQuickFix(InputStream)
andtryQuickFix(String)
.final void
setSupportedFeatures
(FeatureSet features) Set a new set of supported features.protected final String[]
specialSort
(Collection<String> items) Transform the given collection of string elements into a sorted array.Token[]
Parse the given ADQL expression and split it intoToken
s.final String
tryQuickFix
(InputStream input) Try fixing tokens/terms of the input ADQL query.final String
tryQuickFix
(String adqlQuery) Try fixing tokens/terms of the given ADQL query.
-
Field Details
-
grammarParser
Grammar parser to use.Implementation note: Never NULL.
-
supportedFeatures
List of all supported features.Note: The default set of features can be set with the function
setDefaultFeatures()
.Implementation note: Never NULL.
-
allowedCoordSys
List of all allowed coordinate systems.Each item of this list must be of the form: "{frame} {refpos} {flavor}". Each of these 3 items can be either of value, a list of values expressed with the syntax "({value1}|{value2}|...)" or a '*' to mean all possible values.
Note: since a default value (corresponding to the empty string - '') should always be possible for each part of a coordinate system, the checker will always add the default value (UNKNOWNFRAME, UNKNOWNREFPOS or SPHERICAL2) into the given list of possible values for each coord. sys. part.
If this list is NULL, all coordinates systems are allowed. However, if not, all items of this list must be the only allowed coordinate systems. So, if the list is empty, none is allowed.
-
coordSysRegExp
A regular expression built using the list of allowed coordinate systems.With this regex, it is possible to known whether a coordinate system expression is allowed or not.
If NULL, all coordinate systems are allowed.
-
queryChecker
API to checkADQL queries
(sub-queries or not) just after their generation.Note: This check step is optional. To ignore it, set this attribute to NULL.
-
quickFixer
This object is used only when one of thetryQuickFix(String)
functions is called. It allows to try fixing common errors in the given ADQL query.Implementation note: Never NULL.
-
anyUdfAllowed
protected boolean anyUdfAllowedIndicate whether any UDF (even if not declared) should be considered as supported. -
extendedRegionExpressionAllowed
protected boolean extendedRegionExpressionAllowedIndicate whether the REGION(...) function accepts any string expression and any serialization or only a string literal using a supported serialization (e.g. DALI, STC/s). -
DEFAULT_VERSION
Version of the ADQL grammar to use when none is specified:2.0
.
-
-
Constructor Details
-
ADQLParser
public ADQLParser()Builds an ADQL query parser for the default (i.e. last stable) version of the ADQL grammar.This parser is set with:
- the
default version
of the ADQL grammar, - the
default set
of optional features, - the default
ADQL query factory
, - and no custom check (i.e. no
QueryChecker
is set).
- See Also:
- the
-
ADQLParser
Builds an ADQL query parser for the specified version of the ADQL grammar.This parser is set with:
- the specified version of the ADQL grammar,
- the
default set
of optional features, - the default
ADQL query factory
, - and no custom check (i.e. no
QueryChecker
is set).
- Parameters:
version
- Version of the ADQL grammar that the parser must implement. If NULL, theDEFAULT_VERSION
will be used.
-
ADQLParser
public ADQLParser(ADQLParser.ADQLVersion version, QueryChecker queryChecker, ADQLQueryFactory factory, FeatureSet features) Builds a parser whose the query to parse will have to be given as a String in parameter ofparseQuery(String)
.- Parameters:
version
- Version of the ADQL grammar that the parser must implement. If NULL, theDEFAULT_VERSION
will be used.queryChecker
- The custom checks to perform. If NULL, only the general checks (e.g. supported features, UDFs, types) will be run.factory
- The factory of ADQL objects to use. If NULL, the default query factory will be used.features
- The set of supported features. If NULL, the default set of supported features will be used (seesetDefaultFeatures()
).
-
-
Method Details
-
getSupportedVersions
Get the list of all supported ADQL grammar versions.- Returns:
- List of all supported ADQL versions.
- See Also:
-
getSupportedVersionsAsString
Build on the fly a human list of all supported ADQL grammar versions.The default version item will be suffixed by the string
(default)
.Example:
v2.0, v2.1 (default)
- Returns:
- List of all supported ADQL versions.
-
getADQLVersion
Get the ADQL grammar version followed by this parser.- Returns:
- The target ADQL version.
-
getGrammarParser
Get the internal grammar parser specific to the target ADQL version.Warning: Changing the configuration of this internal parser might break the normal functioning of this
ADQLParser
instance. It is recommended to not use directly this internal parser. The goal ofADQLParser
is to provide a nice and safe parser API. If something is missing or incorrect, please, contact the library developer so that this API can be completed/fixed.- Returns:
- The internal grammar parser.
-
getQuickFixer
Get the API used to attempt fixing given ADQL queries with the functionstryQuickFix(InputStream)
andtryQuickFix(String)
.- Returns:
- The query fixer tool.
-
setQuickFixer
Set the tool to use in order to attempt fixing any given ADQL query with the functionstryQuickFix(InputStream)
andtryQuickFix(String)
.- Parameters:
fixer
- The tool to use.- Throws:
NullPointerException
- If the given fixer is NULL.
-
getQueryFactory
Get the query factory used to create ADQL objects during the parsing of an ADQL query.- Returns:
- The used ADQL query factory.
-
setQueryFactory
Set the query factory to use when creating ADQL objects during the parsing of an ADQL query.- Parameters:
factory
- The ADQL query factory to use.- Throws:
NullPointerException
- If the given factory is NULL.
-
getSupportedFeatures
Get the list of all supported features.Note: To customize the list of supported features, either get the set with this function and then update it directly, or set a new
FeatureSet
instance withsetSupportedFeatures(FeatureSet)
.- Returns:
- Set of supported features.
-
setDefaultFeatures
public final void setDefaultFeatures()Set a default set of supported language features in function of the target ADQL version.- ADQL-2.0: the geometric functions are the only supported features.
- ADQL-2.1: all optional features are supported.
Note: To customize the list of supported features, either get the set with
getSupportedFeatures()
and then update it directly, or set a newFeatureSet
instance withsetSupportedFeatures(FeatureSet)
. -
setSupportedFeatures
Set a new set of supported features.- Parameters:
features
- The new list of supported features.- Throws:
NullPointerException
- If the given object is NULL.
-
getAllowedCoordSys
Get the list of allowed coordinate systems.If NULL, any coordinate system is allowed. But if empty array, no coordinate system is allowed.
- Returns:
- All allowed coordinate systems.
-
setAllowedCoordSys
Set the list of allowed coordinate systems.Each item of this list must be of the form: "{frame} {refpos} {flavor}". Each of these 3 items can be either of value, a list of values expressed with the syntax "({value1}|{value2}|...)" or a '*' to mean all possible values.
Note: since a default value (corresponding to the empty string - '') should always be possible for each part of a coordinate system, this parser will always add the default value (UNKNOWNFRAME, UNKNOWNREFPOS or SPHERICAL2) into the given list of possible values for each coord. sys. part.
If this list is NULL, all coordinates systems are allowed. However, if not, all items of this list must be the only allowed coordinate systems. So, if the list is empty, none is allowed.
Note: When an exception is thrown, the list of allowed coordinate systems of this parser stays in the same state than before calling this function.
- Parameters:
allowedCoordSys
- List of allowed coordinate systems.- Throws:
ParseException
- If the syntax of one of the given coordinate system is incorrect.
-
allowAnyUdf
public void allowAnyUdf(boolean allowed) Let specify whether any UDF (even if not declared) should be considered as supported or not. If not, UDFs must be explicitly declared to be considered as supported (as any other optional language feature).- Parameters:
allowed
-true
to support any UDF,false
to force the declaration of supported UDFs.
-
isAnyUdfAllowed
public boolean isAnyUdfAllowed()Tell whether UDFs are considered as supported even if undeclared.- Returns:
true
if any UDF is considered as supported,false
if supported UDFs must be explicitly declared.
-
allowExtendedRegionParam
public void allowExtendedRegionParam(boolean allowed) Let specify whether the REGION(...) function accepts any string expression and any serialization or only a string literal using a supported serialization (e.g. DALI, STC/s).- Parameters:
allowed
-true
to support any string expression,false
to only support string literal.
-
isExtendedRegionParamAllowed
public boolean isExtendedRegionParamAllowed()Tell whether the REGION(...) function accepts any string expression and any serialization or only a string literal using a supported serialization (e.g. DALI, STC/s).- Returns:
true
if any string expression is supported,false
if only a string literal is supported.
-
getQueryChecker
Get the custom checker of parsed ADQL queries.- Returns:
- Custom query checker, or NULL if no custom check is available.
-
setQueryChecker
Set a custom checker of parsed ADQL queries.- Parameters:
checker
- The custom query checks to run, or NULL to have no custom check.
-
setDebug
public final void setDebug(boolean debug) Enable/Disable the debugging messages while parsing an ADQL expression.- Parameters:
debug
-true
to enable debugging,false
to disable it.
-
parseQuery
Parses the query string given in parameter.- Parameters:
q
- The ADQL query to parse.- Returns:
- The object representation of the given ADQL query.
- Throws:
ParseException
- If there is at least one error.- See Also:
-
parseQuery
Parses the query contained in the stream given in parameter.- Parameters:
stream
- The stream which contains the ADQL query to parse.- Returns:
- The object representation of the given ADQL query.
- Throws:
ParseException
- If there is at least one error.- See Also:
-
effectiveParseQuery
Run the query parsing, then, if successful, all the available checks on the parsing result (i.e. the query tree).This functions stops immediately with a
ParseException
if the parsing failed or if any of the available checks fails.- Returns:
- The object representation of the successfully parsed query (i.e. the ADQL tree).
- Throws:
ParseException
- If syntax is incorrect (i.e. no ADQL tree can be generated), or if any check on the parsing result fails.- See Also:
-
parseSelect
Parse the givenSELECT
clause.Important note: The given string MUST start with
SELECT
(case insensitive). It MUST also follow the syntax of the FULL clause as described in the appropriate version of the ADQL Grammar.Examples of INcorrect parameter:
SELECT
aColumn
DISTINCT TOP 10 aColumn, bColumn AS "B"
Example of correct parameter:
SELECT DISTINCT TOP 10 aColumn, bColumn AS "B"
This functions stops immediately with a
ParseException
if the parsing failed or if any of the available checks fails.- Parameters:
adql
- TheSELECT
clause to parse.- Returns:
- The corresponding object representation of the given clause.
- Throws:
ParseException
- If the syntax of the given clause is incorrect.
-
parseFrom
Parse the givenFROM
clause.Important note: The given string MUST start with
FROM
(case insensitive). It MUST also follow the syntax of the FULL clause as described in the appropriate version of the ADQL Grammar.Examples of INcorrect parameter:
FROM
aTable
aTable JOIN bTable
aTable JOIN bTable AS "B" USING(id)
Example of correct parameter:
FROM aTable JOIN bTable AS "B" USING(id)
This functions stops immediately with a
ParseException
if the parsing failed or if any of the available checks fails.- Parameters:
adql
- TheFROM
clause to parse.- Returns:
- The corresponding object representation of the given clause.
- Throws:
ParseException
- If the syntax of the given clause is incorrect.
-
parseWhere
Parse the givenWHERE
clause.Important note: The given string MUST start with
WHERE
(case insensitive). It MUST also follow the syntax of the FULL clause as described in the appropriate version of the ADQL Grammar.Examples of INcorrect parameter:
WHERE
foo
foo = 'bar'
Example of correct parameter:
WHERE foo = 'bar'
This functions stops immediately with a
ParseException
if the parsing failed or if any of the available checks fails.- Parameters:
adql
- TheWHERE
clause to parse.- Returns:
- The corresponding object representation of the given clause.
- Throws:
ParseException
- If the syntax of the given clause is incorrect.
-
parseOrderBy
Parse the givenORDER BY
clause.Important note: The given string MUST start with
ORDER BY
(case insensitive). It MUST also follow the syntax of the FULL clause as described in the appropriate version of the ADQL Grammar.Examples of INcorrect parameter:
ORDER BY
aColumn DESC
Example of correct parameter:
ORDER BY aColumn DESC
This functions stops immediately with a
ParseException
if the parsing failed or if any of the available checks fails.- Parameters:
adql
- TheORDER BY
clause to parse.- Returns:
- The corresponding object representation of the given clause.
- Throws:
ParseException
- If the syntax of the given clause is incorrect.
-
parseGroupBy
Parse the givenGROUP BY
clause.Important note: The given string MUST start with
GROUP BY
(case insensitive). It MUST also follow the syntax of the FULL clause as described in the appropriate version of the ADQL Grammar.Examples of INcorrect parameter:
GROUP BY
aColumn
Example of correct parameter:
GROUP BY aColumn
This functions stops immediately with a
ParseException
if the parsing failed or if any of the available checks fails.- Parameters:
adql
- TheGROUP BY
clause to parse.- Returns:
- The corresponding object representation of the given clause.
- Throws:
ParseException
- If the syntax of the given clause is incorrect.
-
allChecks
Run all available checks on the given ADQL tree:- the general checks: optional features support, region serializations, ...
- the custom checks (if any).
- Parameters:
q
- The ADQL query to check.- Throws:
ParseException
- If any of the common checks or any of the optional ones failed- See Also:
-
generalChecks
Run the general and common checks on the given ADQL tree.By default, this function checks whether or not language features found in the given ADQL tree are supported. It also checks all explicit coordinate systems and STC-s expressions (embedded in REGION function). All unsupported expressions (i.e. feature, coord. sys., STC-s) are appended into an
UnresolvedIdentifiersException
which is finally thrown if not empty.- Parameters:
q
- The ADQL query to check.- Throws:
ParseException
- If any unsupported language feature is used in the given ADQL tree.
-
specialSort
Transform the given collection of string elements into a sorted array. Only non-NULL and non-empty strings are kept.- Parameters:
items
- Items to copy and sort.- Returns:
- A sorted array containing all - except NULL and empty strings - items of the given collection.
-
resolveCoordinateSystems
Search for all explicit coordinate system declarations, check their syntax and whether they are allowed by this implementation.Note: "explicit" means here that all
StringConstant
instances. Only coordinate systems expressed as string can be parsed and so checked. So if a coordinate system is specified by a column, no check can be done at this stage...it will be possible to perform such test only at the execution.- Parameters:
query
- Query in which coordinate systems must be checked.errors
- List of errors to complete in this function each time a coordinate system has a wrong syntax or is not supported.- See Also:
-
checkCoordinateSystem
protected void checkCoordinateSystem(StringConstant adqlCoordSys, UnresolvedIdentifiersException errors) Parse and then check the coordinate system contained in the givenStringConstant
instance.- Parameters:
adqlCoordSys
- TheStringConstant
object containing the coordinate system to check.errors
- List of errors to complete in this function each time a coordinate system has a wrong syntax or is not supported.- See Also:
-
checkCoordinateSystem
protected void checkCoordinateSystem(CoordSys coordSys, ADQLOperand operand, UnresolvedIdentifiersException errors) Check whether the given coordinate system is allowed by this implementation.- Parameters:
coordSys
- Coordinate system to test.operand
- The operand representing or containing the coordinate system under test.errors
- List of errors to complete in this function each time a coordinate system is not supported.
-
resolveRegionExpressions
Search for all region expressions inside the given query, parse them (and so check their syntax) and then determine whether the declared coordinate system and the expressed region are allowed in this implementation.- Parameters:
query
- Query in which region expressions must be checked.errors
- List of errors to complete in this function each time the region syntax is wrong or each time the declared coordinate system or region is not supported.- See Also:
-
checkRegion
Check the given region.The following points are checked in this function:
- whether the coordinate system is allowed,
- whether the type of region is allowed,
- and whether the inner regions are correct (here this function is called recursively on each inner region).
- Parameters:
r
- The region to check.fct
- The REGION function containing the region to check.errors
- List of errors to complete in this function if the given region or its inner regions are not supported.- See Also:
-
tokenize
Parse the given ADQL expression and split it intoToken
s.Note: If
stopAtEnd=true
, the encountered EOQ (i.e. End Of Query =;
) or EOF (i.e. End Of File) are NOT included in the returned array.Example:
tokenize("SELECT ; FROM", false); // = { SELECT, EOQ, FROM } tokenize("SELECT ; FROM", true); // = { SELECT }
- Parameters:
expr
- The ADQL expression to tokenize.stopAtEnd
-true
to stop the tokenization process when an EOQ or an EOF is encountered,false
to stop when the end of the string is reached.- Returns:
- The corresponding ordered list of tokens.
- Throws:
ParseException
- If an unknown token is encountered.
-
tryQuickFix
Try fixing tokens/terms of the input ADQL query.This function does not try to fix syntactical or semantical errors. It just try to fix the most common issues in ADQL queries, such as:
- some Unicode characters confusable with ASCII characters (like a space, a dash, ...) ; this function replace them by their ASCII alternative,
- any of the following are double quoted:
- non regular ADQL identifiers
(e.g.
_RAJ2000
), - ADQL function names used as identifiers
(e.g.
distance
) - and SQL reserved keywords
(e.g.
public
).
- non regular ADQL identifiers
(e.g.
Note 1: The given stream is NOT closed by this function even if the EOF is reached. It is the responsibility of the caller to close it.
Note 2: This function does not use any instance variable of this parser (especially the InputStream or Reader provided at initialisation or ReInit).
- Parameters:
input
- Stream containing the input ADQL query to fix.- Returns:
- The suggested correction of the input ADQL query.
- Throws:
IOException
- If there is any error while reading from the given input stream.ParseException
- If any unrecognised character is encountered, or if anything else prevented the tokenization of some characters/words/terms.- Since:
- 1.5
- See Also:
-
tryQuickFix
Try fixing tokens/terms of the given ADQL query.This function does not try to fix syntactical or semantical errors. It just try to fix the most common issues in ADQL queries, such as:
- some Unicode characters confusable with ASCII characters (like a space, a dash, ...) ; this function replace them by their ASCII alternative,
- any of the following are double quoted:
- non regular ADQL identifiers
(e.g.
_RAJ2000
), - ADQL function names used as identifiers
(e.g.
distance
) - and SQL reserved keywords
(e.g.
public
).
- non regular ADQL identifiers
(e.g.
Note: This function does not use any instance variable of this parser (especially the InputStream or Reader provided at initialisation or ReInit).
- Parameters:
adqlQuery
- The input ADQL query to fix.- Returns:
- The suggested correction of the given ADQL query.
- Throws:
ParseException
- If any unrecognised character is encountered, or if anything else prevented the tokenization of some characters/words/terms.- Since:
- 1.5
- See Also:
-
main
Parse the given ADQL query.Usage
adqlParser.jar [--version=...] [-h] [-d] [-v] [-e] [-a|-s] [-f] [<FILE>|<URL>]
Note: If no file or URL is given, the ADQL query is expected in the standard input. This query must end with a ';' or invalid input: '<'Ctrl+D>!
Parameters
--version=...
: Set the version of the ADQL grammar to follow. It must be one among: v2.0, v2.1 (default).-h
or--help
: Display this help.-v
or--verbose
: Print the main steps of the parsing.-d
or--debug
: Print stack traces when a grave error occurs.-e
or--explain
: Explain the ADQL parsing (or Expand the parsing tree).-a
or--adql
: Display the understood ADQL query.-s
or--sql
: Ask the SQL translation of the given ADQL query (SQL compatible with PostgreSQL).-f
or--try-fix
: Try fixing the most common ADQL query issues before attempting to parse the query.
Return
By default, nothing if the query is correct. Otherwise a message explaining why the query is not correct is displayed.
With the
-s
option, the SQL translation of the given ADQL query will be returned.With the
-a
option, the ADQL query is returned as it has been understood.Exit status
0
: OK!1
: Parameter error (missing or incorrect parameter)2
: File error (incorrect file/url, reading error, ...)3
: Parsing error (syntactic or semantic error)4
: Translation error (a problem has occurred during the translation of the given ADQL query in SQL).
- Parameters:
args
- Program parameters.- Throws:
Exception
- If any unexpected error occurs.
-