diff options
Diffstat (limited to 'odb/doc/odb-epilogue.1')
-rw-r--r-- | odb/doc/odb-epilogue.1 | 153 |
1 files changed, 153 insertions, 0 deletions
diff --git a/odb/doc/odb-epilogue.1 b/odb/doc/odb-epilogue.1 new file mode 100644 index 0000000..e331b23 --- /dev/null +++ b/odb/doc/odb-epilogue.1 @@ -0,0 +1,153 @@ +.\" +.\" 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 , +.BR sequence , +or +.BR statement . +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 +When entering a regular expression argument in the shell command line +it is often necessary to use quoting (enclosing the argument in " " +or ' ') in order to prevent the shell from interpreting certain +characters, for example, spaces as argument separators and $ as +variable expansions. + +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 " " for quoting you will get +a wrong result with POSIX shells if your expression contains $. The +standard way of dealing with this on POSIX systems is to use ' ' +instead. Unfortunately, Windows shell does not remove ' ' from +arguments when they are passed to applications. As a result you may +have to use ' ' for POSIX and " " for Windows ($ is not treated as +a special character on Windows). + +Alternatively, you can save regular expression options into a file, +one option per line, and use this file with the +.B --options-file +option. With this approach you don't need to worry about shell quoting. +.\" +.\" DIAGNOSTICS +.\" +.SH DIAGNOSTICS +If the input file is not valid C++, +.B odb +will issue diagnostic messages to STDERR and exit with non-zero exit code. +.\" +.\" BUGS +.\" +.SH BUGS +Send bug reports to the odb-users@codesynthesis.com mailing list. +.\" +.\" COPYRIGHT +.\" +.SH COPYRIGHT +Copyright (c) $copyright$. + +Permission is granted to copy, distribute and/or modify this +document under the terms of the GNU Free Documentation License, +version 1.2; with no Invariant Sections, no Front-Cover Texts and +no Back-Cover Texts. Copy of the license can be obtained from +http://www.codesynthesis.com/licenses/fdl-1.3.txt |