Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC corrections suggested by DAL WG #100

Merged
merged 6 commits into from
Oct 31, 2023
Merged

RFC corrections suggested by DAL WG #100

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3751fe3
Add a section about comments
gmantele Oct 11, 2023
652bcdd
Reword introduction of the section about geometry constructors
gmantele Oct 11, 2023
c932204
Fix ADQL versions not allowing different COOSYS arguments
gmantele Oct 11, 2023
eede4a1
Rephrase position of ADQL comments
gmantele Oct 13, 2023
eb16d53
Add recommendation to use UDFs from the UDF Catalogue EN
gmantele Oct 18, 2023
ec9aa40
Add explanation on how to escape single quotes in string literal
gmantele Oct 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 45 additions & 9 deletions ADQL.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -383,13 +383,21 @@ \subsubsection{Case sensitivity}
\subsubsection{Literals}
\label{sec:literals}

String literals are expressed as a character expression delimited by single quotes.
String literals are expressed as a character expression delimited by single
quotes.

\begin{verbatim}
<character_string_literal> ::=
<quote> [ <character_representation>... ] <quote>
\end{verbatim}

A single quote inside a string literal must be escaped with a second single
quote. For instance:

\begin{verbatim}
'Earth''s satellite is the Moon.'
\end{verbatim}

Numeric literals are expressed as an exact decimal value, e.g. \verb:12: or
\verb:12.3:, or a floating point number with an exponent, e.g. \verb:12.3E4:.

Expand Down Expand Up @@ -425,6 +433,23 @@ \subsubsection{Whitespace}
The rules on where whitespace is allowed and required are as in SQL-92;
essentially, any \verb:<token>: may be followed by a \verb:<separator>:.

\subsubsection{Comments}
\label{sec:comments}

As in SQL-92, comments are supported in ADQL. A comment is syntactically legal
wherever whitespace is legal and can then stand in for that whitespace. It
starts with a double minus sign and ends with the end of line.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"anywhere in the query" is too strong a statement; in the SQL92 grammar, there's the separator nonterminal that we've (rightly) thrown out, so we can't refer to that. What about "A comment is syntactically legal wherever whitespace is legal (and can then stand in for that whitespace)"?

\begin{verbatim}
<comment> ::= <comment_introducer> [ <comment_character>... ] <newline>

<comment_character> ::= <nonquote_character> | <quote>

<comment_introducer> ::= <minus_sign><minus_sign> [<minus_sign>...]
\end{verbatim}

Comments are not expected to be interpreted by ADQL parsers.

\clearpage % to keep the entire verbatim block for query syntax on the same page
\subsection{Query syntax}
\label{sec:syntax}
Expand Down Expand Up @@ -1450,12 +1475,13 @@ \subsubsection{Coordinate limits}
\subsubsection{Datatype functions}
\label{sec:functions.geom.type}

The following functions provide constructors for each of the geometry datatypes.
The semantics of these datatypes are based on the corresponding
concepts from the \STCSpec{} data model.
Some of the functions described in this section (e.g. \verb:POINT:,
\verb:CIRCLE:) are constructors for each of the geometry datatypes. The
semantics of these datatypes are based on the corresponding concepts from the
\STCSpec{} data model.

The geometry datatypes and expressions are part of the core \verb:<value_expression>:
in the ADQL grammar.
The geometry datatypes and expressions are part of the core
\verb:<value_expression>: in the ADQL grammar.

\begin{verbatim}
<value_expression> ::=
Expand Down Expand Up @@ -1519,9 +1545,9 @@ \subsubsection{Coordinate system}
coordinate systems. However, be aware that in a future version of ADQL, these
functions will no longer be expected to perform any coordinate conversion.
Consequently, it is recommanded to avoid relying on this deprecated feature.
For interoperability reasons, queries against 2.0 services SHOULD NOT pass
arguments with differing COOSYS arguments to \verb:DISTANCE:, \verb:CONTAINS:
or \verb:INTERSECTS:, as behaviour is undefined in that case.
For interoperability reasons, queries against 2.0 or later services SHOULD NOT
pass arguments with differing COOSYS arguments to \verb:DISTANCE:,
\verb:CONTAINS: or \verb:INTERSECTS:, as behaviour is undefined in that case.

\subsubsection{Predicate functions}
\label{sec:functions.geom.predicate}
Expand Down Expand Up @@ -2217,6 +2243,12 @@ \subsubsection{Overview}
ivo_string_agg()
\end{verbatim}

The \CatalogueUDF{} collects many \verb:ivo: prefixed functions defined in other
IVOA specifications, Endorsed Notes and functions defined in at least two
implementations. At the time of this writing it is the only endorsed IVOA
document providing such a collection of \verb:ivo: prefixed functions. It is
then strongly recommended to follow function names and definitions from this
catalogue when providing functions offering identical or similar functionnality.

\subsubsection{Metadata}
\label{sec:user.metadata}
Expand Down Expand Up @@ -2894,6 +2926,10 @@ \subsection{Between 2.0 and 2.1}
\verb:BLOB: \SectionSee{sec:types}
\item Language feature description
(see \AppendixRef{sec:features})
\item Syntax description for comments inside a query
(see \SectionRef{sec:comments})
\item Description of how to escape single quotes in a string
literal (see \SectionRef{sec:literals})
\end{itemize}
\item \textbf{Updated}
\begin{itemize}
Expand Down