uk.ac.starlink.table.jdbc

## Class SqlSyntax

- java.lang.Object
- - uk.ac.starlink.table.jdbc.SqlSyntax

-     public class SqlSyntax
      extends java.lang.Object

  Summarises some aspects of the syntax of an SQL variant, and provides some utilities based on that.
  Since:
    7 Jun 2013

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.util.regex.Pattern` | `SQL92_IDENTIFIER_REGEX` Standard regular expression for identifiers, as per SQL92.
    `static java.lang.String[]` | `SQL92_RESERVED` SQL92 list of reserved words.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SqlSyntax(java.lang.String[] reservedWords, java.util.regex.Pattern identifierRegex, char quoteChar)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String[]` | `getParanoidReservedWords()` Returns a list of words that are known to be reserved in a mixed bag of popular RDBMSs.
    `java.util.SortedSet<java.lang.String>` | `getReservedWords()` Returns an alphabetical list of the reserved words known by this class, in normalised (upper case) form.
    `boolean` | `isIdentifier(java.lang.String word)` Indicates whether a given word is syntactically permitted to act as an identifier.
    `boolean` | `isReserved(java.lang.String word)` Indicates whether a given word is reserved.
    `java.lang.String` | `quote(java.lang.String word)` Returns a quoted version of a word.
    `java.lang.String` | `quoteIfNecessary(java.lang.String word)` Returns a string which can be used within an SQL query to refer to an item with the name of a given word.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### SQL92_IDENTIFIER_REGEX

          public static final java.util.regex.Pattern SQL92_IDENTIFIER_REGEX

      Standard regular expression for identifiers, as per SQL92.

    - #### SQL92_RESERVED

          public static final java.lang.String[] SQL92_RESERVED

      SQL92 list of reserved words. This list was actually taken from ADQL 2.0 standard.

  - ### Constructor Detail

    - #### SqlSyntax

          public SqlSyntax(java.lang.String[] reservedWords,
                           java.util.regex.Pattern identifierRegex,
                           char quoteChar)

      Constructor.
      Parameters:
        `reservedWords` - list of words considered reserved for this dialect
        `identifierRegex` - regular expression for an identifier token in this dialect
        `quoteChar` - character which may be used to quote words in this dialect (thus avoiding their usual parsing); words are quoted with a copy of this character at start and end, doubled if this character is embedded

  - ### Method Detail

    - #### getReservedWords

          public java.util.SortedSet<java.lang.String> getReservedWords()

      Returns an alphabetical list of the reserved words known by this class, in normalised (upper case) form.
      Returns:
        unmodifiable set of reserved words

    - #### isReserved

          public boolean isReserved(java.lang.String word)

      Indicates whether a given word is reserved. The result is not sensitive to the case of the supplied word.
      Parameters:
        `word` - word to test
      Returns:
        true iff reserved

    - #### isIdentifier

          public boolean isIdentifier(java.lang.String word)

      Indicates whether a given word is syntactically permitted to act as an identifier.
      Parameters:
        `word` - word to test
      Returns:
        true iff identifier

    - #### quoteIfNecessary

          public java.lang.String quoteIfNecessary(java.lang.String word)

      Returns a string which can be used within an SQL query to refer to an item with the name of a given word. If the given word can be used as it stands, it is returned as given. Otherwise (if it's reserved or syntactically unsuitable) a quoted version of the provided word is returned.
      Parameters:
        `word` - word to use
      Returns:
        quoted or unquoted version of `word`

    - #### quote

          public java.lang.String quote(java.lang.String word)

      Returns a quoted version of a word.

      Note that quoting words is not harmless - unlike for instance shell syntax, quotes are not just stripped off where present before processing, but instead in SQL92 and hence ADQL they modify the interpretation of what's quoted. This is something to do with the way case folding is handled, and I (mbt) didn't know about it until Markus Demleitner persuaded me it's actually true. As it happens MySQL behaves contrary to the standard in this respect (quoting of column names - but not table names?? - is harmless) but (for instance) PostgreSQL does not. Therefore do not use this method indiscriminately, use `quoteIfNecessary` instead.

      Parameters:
        `word` - word to quote
      Returns:
        quoted word

    - #### getParanoidReservedWords

          public static java.lang.String[] getParanoidReservedWords()

      Returns a list of words that are known to be reserved in a mixed bag of popular RDBMSs.
      Returns:
        reserved word list