diff options
Diffstat (limited to 'odb/doc/odb-epilogue.xhtml')
| -rw-r--r-- | odb/doc/odb-epilogue.xhtml | 126 |
1 files changed, 126 insertions, 0 deletions
diff --git a/odb/doc/odb-epilogue.xhtml b/odb/doc/odb-epilogue.xhtml new file mode 100644 index 0000000..9eba558 --- /dev/null +++ b/odb/doc/odb-epilogue.xhtml @@ -0,0 +1,126 @@ + <h1>SQL NAME TRANSFORMATIONS</h1> + + <p>The ODB compiler provides a number of mechanisms for transforming + automatically-derived SQL names, such as tables, columns, etc., + to match a specific naming convention. At the higher level, we can + add a prefix to global names (tables and, for some databases, + indexes and/or foreign keys) with the <code><b>--table-prefix</b></code> + option. Similarly, we can specify custom suffixes for + automatically-derived + index (<code><b>--index-suffix</b></code>; default is <code><b>_i</b></code>), + foreign key (<code><b>--fkey-suffix</b></code>; default is <code><b>_fk</b></code>), and + sequence (<code><b>--sequence-suffix</b></code>; default is <code><b>_seq</b></code>) + names. Finally, we can also convert all the names to upper or lower + case with the <code><b>--sql-name-case</b></code> option (valid values + are <code><b>upper</b></code> and <code><b>lower</b></code>).</p> + + <p>At the lower level we can specify a set of regular expressions to + implement arbitrary transformations of the automatically-derived SQL + names. If we want a particular regular expression only to apply to + a specific name, for example, table or column, then we use one of the + <code><b>--</b><i>kind</i><b>-regex</b></code> options, where + <code><i>kind</i></code> can be <code><b>table</b></code>, + <code><b>column</b></code>, <code><b>index</b></code>, + <code><b>fkey</b></code>, <code><b>sequence</b></code>, or + <code><b>statement</b></code>. On the other hand, if we want our + regular expressions to apply to all SQL names, then we use the + <code><b>--sql-name-regex</b></code> option.</p> + + <p>The interaction between the higher and lower level transformations + is as follows. Prefixes and suffixes are added first. Then the + regular expression transformations are applied. Finally, if requested, + the name is converted to upper or lower case. Note also that all of + these transformations except for <code><b>--table-prefix</b></code> + only apply to automatically-derived names. In other words, if a table, + column, etc., name was explicitly specified with a pragma, then it + is used as is, without applying any (except for the table prefix) + transformations.</p> + + <p>The value for the <code><b>--*-regex</b></code> options is a Perl-like + regular expression in the form + <code><b>/</b><i>pattern</i><b>/</b><i>replacement</i><b>/</b></code>. + Any character can be used as a delimiter instead of <code><b>/</b></code> + and the delimiter can be escaped inside <code><i>pattern</i></code> and + <code><i>replacement</i></code> with a backslash (<code><b>\</b></code>). + You can also specify multiple regular expressions by repeating these + options.</p> + + <p>All the regular expressions are tried in the order specified with the + name-specific expressions (for example, <code><b>--table-regex</b></code>) + tried first followed by the generic expressions + (<code><b>--sql-name-regex</b></code>). The first expression that + matches is used.</p> + + <p>As an example, consider a regular expression that transforms a class + name in the form <code><b>CFoo</b></code> to a table name in the + form <code><b>FOO</b></code>:</p> + + <p><code><b>--table-regex '/C(.+)/\U$1/'</b></code></p> + + <p>As a more interesting example, consider the transformation of class + names that follow the upper camel case convention (for example, + <code><b>FooBar</b></code>) to table names that follow the + underscore-separated, all upper case convention (for example, + <code><b>FOO_BAR</b></code>). For this case we have to use + separate expressions to handle one-word, two-word, etc., + names:</p> + + <p><code><b>--table-regex '/([A-z][a-z]+)/\U$1/'</b></code></p> + <p><code><b>--table-regex '/([A-z][a-z]+)([A-z][a-z]+)/\U$1_$2/'</b></code></p> + + <p>See also the REGEX AND SHELL QUOTING section below.</p> + + <h1>REGEX AND SHELL QUOTING</h1> + + <p>When entering a regular expression argument in the shell + command line it is often necessary to use quoting (enclosing + the argument in <code><b>" "</b></code> or + <code><b>' '</b></code>) in order to prevent the shell + from interpreting certain characters, for example, spaces as + argument separators and <code><b>$</b></code> as variable + expansions.</p> + + <p>Unfortunately it is hard to achieve this in a manner that is + portable across POSIX shells, such as those found on + GNU/Linux and UNIX, and Windows shell. For example, if you + use <code><b>" "</b></code> for quoting you will get a + wrong result with POSIX shells if your expression contains + <code><b>$</b></code>. The standard way of dealing with this + on POSIX systems is to use <code><b>' '</b></code> instead. + Unfortunately, Windows shell does not remove <code><b>' '</b></code> + from arguments when they are passed to applications. As a result you + may have to use <code><b>' '</b></code> for POSIX and + <code><b>" "</b></code> for Windows (<code><b>$</b></code> is + not treated as a special character on Windows).</p> + + <p>Alternatively, you can save regular expression options into + a file, one option per line, and use this file with the + <code><b>--options-file</b></code> option. With this approach + you don't need to worry about shell quoting.</p> + + <h1>DIAGNOSTICS</h1> + + <p>If the input file is not valid C++, <code><b>odb</b></code> + will issue diagnostic messages to STDERR and exit with non-zero exit + code.</p> + + <h1>BUGS</h1> + + <p>Send bug reports to the + <a href="mailto:odb-users@codesynthesis.com">odb-users@codesynthesis.com</a> mailing list.</p> + + </div> + <div id="footer"> + Copyright © $copyright$. + + <div id="terms"> + Permission is granted to copy, distribute and/or modify this + document under the terms of the + <a href="http://codesynthesis.com/licenses/fdl-1.3.txt">GNU Free + Documentation License, version 1.3</a>; with no Invariant Sections, + no Front-Cover Texts and no Back-Cover Texts. + </div> + </div> +</div> +</body> +</html> |