diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/odb-epilogue.1 | 105 | ||||
-rw-r--r-- | doc/odb-epilogue.xhtml | 71 |
2 files changed, 176 insertions, 0 deletions
diff --git a/doc/odb-epilogue.1 b/doc/odb-epilogue.1 index 6bdc5c4..8755374 100644 --- a/doc/odb-epilogue.1 +++ b/doc/odb-epilogue.1 @@ -1,4 +1,109 @@ .\" +.\" SQL NAME TRANSFORMATIONS +.\" +.SH SQL NAME TRANSFORMATIONS +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 +.B --table-prefix +option. Similarly, we can specify custom suffixes for automatically-derived +index +.RB ( --index-suffix ; +default is +.BR _i ), +foreign key +.RB ( --fkey-suffix ; +default is +.BR _fk ), +and sequence +.RB ( --sequence-suffix ; +default is +.BR _seq ) +names. Finally, we can also convert all the names to upper or lower +case with the +.B --sql-name-case +option (valid values are +.B upper +and +.BR lower ). + +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 +.B --\fIkind\fB-regex +options, where +.I kind +can be +.BR table , +.BR column , +.BR index , +.BR fkey , +or +.BR sequence . +On the other hand, if we want our regular expressions to apply to all SQL +names, then we use the +.B --sql-name-regex +option. + +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 +.B --table-prefix +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. + +The value for the +.B --*-regex +options is a Perl-like regular expression in the form +.BI / pattern / replacement /\fR. +Any character can be used as a delimiter instead of +.B / +and the delimiter can be escaped inside +.I pattern +and +.I replacement +with a backslash +.RB ( \e ). +You can also specify multiple regular expressions by repeating these +options. + +All the regular expressions are tried in the order specified with the +name-specific expressions (for example, +.BR --table-regex) +tried first followed by the generic expressions +.RB ( --sql-name-regex ). +The first expression that matches is used. + +As an example, consider a regular expression that transforms a class +name in the form +.B CFoo +to a table name in the form +.BR FOO: + +.B --table-regex '/C(.+)/\eU$1/' + +As a more interesting example, consider the transformation of class +names that follow the upper camel case convention (for example, +.BR FooBar ) +to table names that follow the underscore-separated, all upper case +convention (for example, +.BR FOO_BAR ). +For this case we have to use separate expressions to handle one-word, +two-word, etc., names: + +.B --table-regex '/([A-z][a-z]+)/\eU$1/' + +.B --table-regex '/([A-z][a-z]+)([A-z][a-z]+)/\eU$1_$2/' + +See also the REGEX AND SHELL QUOTING section below. +.\" .\" REGEX AND SHELL QUOTING .\" .SH REGEX AND SHELL QUOTING diff --git a/doc/odb-epilogue.xhtml b/doc/odb-epilogue.xhtml index 8dd45e7..0309fc6 100644 --- a/doc/odb-epilogue.xhtml +++ b/doc/odb-epilogue.xhtml @@ -1,3 +1,74 @@ + <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>, or <code><b>sequence</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 |