Add support for SQL name transformations

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