/**
 * Copyright (C) 2009 - present by OpenGamma Inc. and the OpenGamma group of companies
 *
 * Please see distribution for license.
 */

/**
 * External SQL library.
 * <p>
 * This package contains a standalone library for managing SQL.
 * <p>
 * There are a number of techniques for creating SQL within an application.
 * The main ones are:
 * <ul>
 * <li>an Object Relational Mapper framework, such as Hibernate
 * <li>appending Strings, such as sql = "SELECT foo " + "FROM bar " + "WHERE ..."
 * <li>using a fluent API library, with methods like select("foo").from("bar").where(..)
 * <li>reading in an external file, such as a properties file
 * </ul>
 * This library focuses on the last of these, using an external file.
 * It is designed for use with Spring, and uses the Spring SqlParameterSource class.
 * <p>
 * The key benefit is a simple external file that a DBA can understand, something
 * which is invaluable for later maintenance and debugging.
 * <p>
 * The file format is a file which typically has the suffix ".extsql".
 * Here is an example highlighting the structure:
 * <pre>
 *  -- an example comment
 *  @NAME(SelectBlogs)
 *    SELECT @INSERT(CommonFields)
 *    FROM blogs
 *    WHERE id = :id
 *      @AND(:date)
 *        date > :date
 *  @NAME(CommonFields)
 *    title, author, content
 * </pre>
 * <ul>
 * <li>two dashes are used for comments
 * <li>tags start with the @ symbol
 * <li>the primary blocks are @NAME(name) - the name refers to the block
 * <li>indentation is used to create blocks - indented lines "belong" to the parent less-indented line
 * <li>variables start with a colon, as this is integrated with Spring
 * <li>the various tags aim to handle over 80% of your needs
 * </ul>
 * <p>
 * These are the tags:
 * <p>
 * @NAME(name)<br />
 * The name tag creates a named block which can be referred to from the application
 * or another part of the extsql file. The tag must be on a line by itself.
 * <p>
 * @INSERT(nameOrVariable)<br />
 * The insert tag inserts the contents of a named block or a variable (prefixed by colon).
 * The tag may be embedded in the middle of a line.
 * <p>
 * @WHERE<br />
 * The where tag works together with the and/or tags to build dynamic searches.
 * The @WHERE tag will output an SQL WHERE, but only if there is at least some content output from the block.
 * Normally, the where tag is not needed, as there is typically always one active where clause.
 * The where tag must be on a line by itself.
 * <p>
 * @AND(expression), @OR(expression)<br />
 * These tags are equivalent and output SQL AND or OR.
 * The block that the tag contains is only output if the expression is true.
 * The output SQL will avoid outputting the AND or OR if it immediately follows a WHERE.
 * The and/or tag must be on a line by itself.
 * <p>
 * The expression is evaluated as follows.
 * If the variable does not exist, then the result is false.
 * Otherwise, if the expression is (:foo) and foo is a boolean, then the result is the boolean value.
 * Otherwise, if the expression is (:foo) and foo is not a boolean, then the result is true.
 * Otherwise, if the expression is (:foo = bar) then the result is true if the variable equals "bar" ignoring case.
 * <p>
 * @LIKE sqlWithVariable<br />
 * @LIKE(variable)<br />
 * The like tag adds either an SQL = or an SQL LIKE based on the specified variable.
 * If the tag has no variable in brackets, then the text between the like tag and the end
 * of the line is parsed for a variable.
 * This tag can differ by database, so the actual SQL is generated by the configuration class.
 * <p>
 * @ENDLIKE<br />
 * The end-like tag is used on rare occasions to scope the end of the like tag.
 * Normally, the SQL should be written such that the end of the like tag is the end of the line.
 * <p>
 * @OFFSETFETCH<br />
 * The offset-fetch tag adds the SQL OFFSET and FETCH clauses for paging results.
 * These can differ by database, so the actual SQL is generated by the configuration class.
 * The tag bases its actions on the integer variables "paging_offset" and "paging_fetch".
 */
package com.opengamma.extsql;

Document extsql