From a5f24411433aeb61ad015129354a664820affab0 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Wed, 12 Dec 2012 11:26:44 +0200 Subject: Add support for SQL name transformations --- doc/odb-epilogue.1 | 105 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/odb-epilogue.xhtml | 71 +++++++++++++++++++++++++++++++++ 2 files changed, 176 insertions(+) (limited to 'doc') 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 @@ +

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 --table-prefix + option. Similarly, we can specify custom suffixes for + automatically-derived + index (--index-suffix; default is _i), + foreign key (--fkey-suffix; default is _fk), and + sequence (--sequence-suffix; default is _seq) + names. Finally, we can also convert all the names to upper or lower + case with the --sql-name-case option (valid values + are upper and 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 + --kind-regex options, where + kind can be table, + column, index, + fkey, or sequence. On the + other hand, if we want our regular expressions to apply to all SQL + names, then we use the --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 --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 --*-regex options is a Perl-like + regular expression in the form + /pattern/replacement/. + Any character can be used as a delimiter instead of / + and the delimiter can be escaped inside pattern and + replacement with a backslash (\). + 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, --table-regex) + tried first followed by the generic expressions + (--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 CFoo to a table name in the + form FOO:

+ +

--table-regex '/C(.+)/\U$1/'

+ +

As a more interesting example, consider the transformation of class + names that follow the upper camel case convention (for example, + FooBar) to table names that follow the + underscore-separated, all upper case convention (for example, + FOO_BAR). For this case we have to use + separate expressions to handle one-word, two-word, etc., + names:

+ +

--table-regex '/([A-z][a-z]+)/\U$1/'

+

--table-regex '/([A-z][a-z]+)([A-z][a-z]+)/\U$1_$2/'

+ +

See also the REGEX AND SHELL QUOTING section below.

+

REGEX AND SHELL QUOTING

When entering a regular expression argument in the shell -- cgit v1.1