diff options
Diffstat (limited to 'doc/pregenerated/odb.1')
| -rw-r--r-- | doc/pregenerated/odb.1 | 799 |
1 files changed, 799 insertions, 0 deletions
diff --git a/doc/pregenerated/odb.1 b/doc/pregenerated/odb.1 new file mode 100644 index 0000000..42d81d0 --- /dev/null +++ b/doc/pregenerated/odb.1 @@ -0,0 +1,799 @@ +.\" Process this file with +.\" groff -man -Tascii odb.1 +.\" +.TH ODB 1 "February 2015" "ODB 2.4.0" +.SH NAME +odb \- object-relational mapping (ORM) compiler for C++ +.\" +.\" +.\" +.\"-------------------------------------------------------------------- +.SH SYNOPSIS +.\"-------------------------------------------------------------------- +.B odb +.B [ +.I options +.B ] +.I file +.B [ +.IR file... +.B ] +.\" +.\" +.\" +.\"-------------------------------------------------------------------- +.SH DESCRIPTION +.\"-------------------------------------------------------------------- +Given a set of C++ classes in a header file, +.B odb +generates C++ code that allows you to persist, query, and update objects +of these classes in a relational database (RDBMS). The relational +database that the generated code should target is specified with the +required +.B --database +option (see below). + + +For an input file in the form +.B name.hxx +(other file extensions can be used instead of +.BR .hxx ), +in the single-database mode (the default), the generated C++ files by +default have the following names: +.B name-odb.hxx +(header file), +.B name-odb.ixx +(inline file), and +.B name-odb.cxx +(source file). Additionally, if the +.B --generate-schema +option is specified and the +.B sql +schema format is requested (see +.BR --schema-format ), +the +.B name.sql +database schema file is generated. If the +.B separate +schema format is requested, the database creation code is generated into +the separate +.B name-schema.cxx +file. + + +In the multi-database mode (see the +.B --multi-database +option below), the generated files corresponding to the +.B common +database have the same names as in the single-database mode. For other +databases, the file names include the database name: +.BR name-odb-\fIdb\fB.hxx , +.BR name-odb-\fIdb\fB.ixx , +.BR name-odb-\fIdb\fB.cxx , +.BR name-\fIdb\fB.sql , +and +.B name-schema-\fIdb\fB.cxx +(where +.I db +is the database name). +.\" +.\" +.\" +.\"-------------------------------------------------------------------- +.SH OPTIONS +.\"-------------------------------------------------------------------- +.IP "\fB--help\fR" +Print usage information and exit\. +.IP "\fB--version\fR" +Print version and exit\. +.IP "\fB-I\fR \fIdir\fR" +Add \fIdir\fR to the beginning of the list of directories to be searched for +included header files\. +.IP "\fB-D\fR \fIname\fR[=\fIdef\fR]" +Define macro \fIname\fR with definition \fIdef\fR\. If definition is omitted, +define \fIname\fR to be 1\. +.IP "\fB-U\fR \fIname\fR" +Cancel any previous definitions of macro \fIname\fR, either built-in or +provided with the \fB-D\fR option\. +.IP "\fB--database\fR|\fB-d\fR \fIdb\fR" +Generate code for the \fIdb\fR database\. Valid values are \fBmssql\fR, +\fBmysql\fR, \fBoracle\fR, \fBpgsql\fR, \fBsqlite\fR, and \fBcommon\fR +(multi-database mode only)\. +.IP "\fB--multi-database\fR|\fB-m\fR \fItype\fR" +Enable multi-database support and specify its type\. Valid values for this +option are \fBstatic\fR and \fBdynamic\fR\. + +In the multi-database mode, options that determine the kind (for example, +\fB--schema-format\fR), names (for example, \fB--odb-file-suffix\fR), or +content (for example, prologue and epilogue options) of the output files can +be prefixed with the database name followed by a colon, for example, +\fBmysql:value\fR\. This restricts the value of such an option to only apply +to generated files corresponding to this database\. +.IP "\fB--default-database\fR \fIdb\fR" +When static multi-database support is used, specify the database that should +be made the default\. When dynamic multi-database support is used, +\fBcommon\fR is always made the default database\. +.IP "\fB--generate-query\fR|\fB-q\fR" +Generate query support code\. Without this support you cannot use views and +can only load objects via their ids\. +.IP "\fB--generate-prepared\fR" +Generate prepared query execution support code\. +.IP "\fB--omit-unprepared\fR" +Omit un-prepared (once-off) query execution support code\. +.IP "\fB--generate-session\fR|\fB-e\fR" +Generate session support code\. With this option session support will be +enabled by default for all the persistent classes except those for which it +was explicitly disabled using the \fBdb session\fR pragma\. +.IP "\fB--generate-schema\fR|\fB-s\fR" +Generate the database schema\. The database schema contains SQL statements +that create database tables necessary to store persistent classes defined in +the file being compiled\. Note that by applying this schema, all the existing +information stored in such tables will be lost\. + +Depending on the database being used (\fB--database\fR option), the schema is +generated either as a standalone SQL file or embedded into the generated C++ +code\. By default the SQL file is generated for the MySQL, PostgreSQL, Oracle, +and Microsoft SQL Server databases and the schema is embedded into the C++ +code for the SQLite database\. Use the \fB--schema-format\fR option to alter +the default schema format\. + +If database schema evolution support is enabled (that is, the object model +version is specified), then this option also triggers the generation of +database schema migration statements, again either as standalong SQL files or +embedded into the generated C++ code\. You can suppress the generation of +schema migration statements by specifying the \fB--suppress-migration\fR +option\. +.IP "\fB--generate-schema-only\fR" +Generate only the database schema\. Note that this option is only valid when +generating schema as a standalone SQL file (see \fB--schema-format\fR for +details)\. +.IP "\fB--suppress-migration\fR" +Suppress the generation of database schema migration statements\. +.IP "\fB--suppress-schema-version\fR" +Suppress the generation of schema version table\. If you specify this option +then you are also expected to manually specify the database schema version and +migration state at runtime using the \fBodb::database::schema_version()\fR +function\. +.IP "\fB--schema-version-table\fR \fIname\fR" +Specify the alternative schema version table name instead of the default +\fBschema_version\fR\. If you specify this option then you are also expected +to manually specify the schema version table name at runtime using the +\fBodb::database::schema_version_table()\fR function\. The table name can be +qualified\. +.IP "\fB--schema-format\fR \fIformat\fR" +Generate the database schema in the specified format\. Pass \fBsql\fR as +\fIformat\fR to generate the database schema as a standalone SQL file or pass +\fBembedded\fR to embed the schema into the generated C++ code\. The +\fBseparate\fR value is similar to \fBembedded\fR except the schema creation +code is generated into a separate C++ file (\fBname-schema\.cxx\fR by +default)\. This value is primarily useful if you want to place the schema +creation functionality into a separate program or library\. Repeat this option +to generate the same database schema in multiple formats\. +.IP "\fB--omit-drop\fR" +Omit \fBDROP\fR statements from the generated database schema\. +.IP "\fB--omit-create\fR" +Omit \fBCREATE\fR statements from the generated database schema\. +.IP "\fB--schema-name\fR \fIname\fR" +Use \fIname\fR as the database schema name\. Schema names are primarily used +to distinguish between multiple embedded schemas in the schema catalog\. They +are not to be confused with database schemas (database namespaces) which are +specified with the \fB--schema\fR option\. If this option is not specified, +the empty name, which is the default schema name, is used\. +.IP "\fB--fkeys-deferrable-mode\fR \fIm\fR" +Use constraint checking mode \fIm\fR in foreign keys generated for object +relationships\. Valid values for this option are \fBnot_deferrable\fR, +\fBimmediate\fR, and \fBdeferred\fR (default)\. MySQL and SQL Server do not +support deferrable foreign keys and for these databases such keys are +generated commented out\. Other foreign keys generated by the ODB compiler +(such as the ones used to support containers and polymorphic hierarchies) are +always generated as not deferrable\. + +Note also that if you use either \fBnot_deferrable\fR or \fBimmediate\fR mode, +then the order in which you persist, update, and erase objects within a +transaction becomes important\. +.IP "\fB--default-pointer\fR \fIptr\fR" +Use \fIptr\fR as the default pointer for persistent objects and views\. +Objects and views that do not have a pointer assigned with the \fBdb +pointer\fR pragma will use this pointer by default\. The value of this option +can be '\fB*\fR' which denotes the raw pointer and is the default, or +qualified name of a smart pointer class template, for example, +\fBstd::shared_ptr\fR\. In the latter case, the ODB compiler constructs the +object or view pointer by adding a single template argument of the object or +view type to the qualified name, for example \fBstd::shared_ptr<object>\fR\. +The ODB runtime uses object and view pointers to return, and, in case of +objects, pass and cache dynamically allocated instances of object and view +types\. + +Except for the raw pointer and the standard smart pointers defined in the +\fB<memory>\fR header file, you are expected to include the definition of the +default pointer at the beginning of the generated header file\. There are two +common ways to achieve this: you can either include the necessary header in +the file being compiled or you can use the \fB--hxx-prologue\fR option to add +the necessary \fB#include\fR directive to the generated code\. +.IP "\fB--session-type\fR \fItype\fR" +Use \fItype\fR as the alternative session type instead of the default +\fBodb::session\fR\. This option can be used to specify a custom session +implementation to be use by the persistent classes\. Note that you will also +need to include the definition of the custom session type into the generated +header file\. This is normally achieved with the \fB--hxx-prologue*\fR +options\. +.IP "\fB--profile\fR|\fB-p\fR \fIname\fR" +Specify a profile that should be used during compilation\. A profile is an +options file\. The ODB compiler first looks for a database-specific version +with the name constructed by appending the +\fB-\fR\fIdatabase\fR\fB\.options\fR suffix to \fIname\fR, where +\fIdatabase\fR is the database name as specified with the \fB--database\fR +option\. If this file is not found, then the ODB compiler looks for a +database-independant version with the name constructed by appending just the +\fB\.options\fR suffix\. + +The profile options files are searched for in the same set of directories as +C++ headers included with the \fB#include <\.\.\.>\fR directive (built-in +paths plus those specified with the \fB-I\fR options)\. The options file is +first searched for in the directory itself and then in its \fBodb/\fR +subdirectory\. + +For the format of the options file refer to the \fB--options-file\fR option +below\. You can repeat this option to specify more than one profile\. +.IP "\fB--at-once\fR" +Generate code for all the input files as well as for all the files that they +include at once\. The result is a single set of source/schema files that +contain all the generated code\. If more than one input file is specified +together with this option, then the \fB--input-name\fR option must also be +specified in order to provide the base name for the output files\. In this +case, the directory part of such a base name is used as the location of the +combined file\. This can be important for the \fB#include\fR directive +resolution\. +.IP "\fB--schema\fR \fIschema\fR" +Specify a database schema (database namespace) that should be assigned to the +persistent classes in the file being compiled\. Database schemas are not to be +confused with database schema names (schema catalog names) which are specified +with the \fB--schema-name\fR option\. +.IP "\fB--export-symbol\fR \fIsymbol\fR" +Insert \fIsymbol\fR in places where DLL export/import control statements +(\fB__declspec(dllexport/dllimport)\fR) are necessary\. See also the +\fB--extern-symbol\fR option below\. +.IP "\fB--extern-symbol\fR \fIsymbol\fR" +If \fIsymbol\fR is defined, insert it in places where a template instantiation +must be declared \fBextern\fR\. This option is normally used together with +\fB--export-symbol\fR when both multi-database support and queries are +enabled\. +.IP "\fB--std\fR \fIversion\fR" +Specify the C++ standard that should be used during compilation\. Valid values +are \fBc++98\fR (default), \fBc++11\fR, \fBc++14\fR, \fBc++17\fR, and +\fBc++20\fR\. +.IP "\fB--warn-hard-add\fR" +Warn about hard-added data members\. +.IP "\fB--warn-hard-delete\fR" +Warn about hard-deleted data members and persistent classes\. +.IP "\fB--warn-hard\fR" +Warn about both hard-added and hard-deleted data members and persistent +classes\. +.IP "\fB--output-dir\fR|\fB-o\fR \fIdir\fR" +Write the generated files to \fIdir\fR instead of the current directory\. +.IP "\fB--input-name\fR \fIname\fR" +Use \fIname\fR instead of the input file to derive the names of the generated +files\. If the \fB--at-once\fR option is specified, then the directory part of +\fIname\fR is used as the location of the combined file\. Refer to the +\fB--at-once\fR option for details\. +.IP "\fB--changelog\fR \fIfile\fR" +Read/write changelog from/to \fIfile\fR instead of the default changelog +file\. The default changelog file name is derived from the input file name and +it is placed into the same directory as the input file\. Note that the +\fB--output-dir\fR option does not affect the changelog file location\. In +other words, by default, the changelog file is treated as another input rather +than output even though the ODB compiler may modify it\. Use the +\fB--changelog-in\fR and \fB--changelog-out\fR options to specify different +input and output chaneglog files\. +.IP "\fB--changelog-in\fR \fIfile\fR" +Read changelog from \fIfile\fR instead of the default changelog file\. If this +option is specified, then you must also specify the output chanegelog file +with \fB--changelog-out\fR\. +.IP "\fB--changelog-out\fR \fIfile\fR" +Write changelog to \fIfile\fR instead of the default changelog file\. If this +option is specified, then you must also specify the input chanegelog file with +\fB--changelog-in\fR\. +.IP "\fB--changelog-dir\fR \fIdir\fR" +Use \fIdir\fR instead of the input file directory as the changelog file +directory\. This directory is also added to changelog files specified with the +\fB--changelog\fR, \fB--changelog-in\fR, and \fB--changelog-in\fR options +unless they are absolute paths\. +.IP "\fB--init-changelog\fR" +Force re-initialization of the changelog even if one exists (all the existing +change history will be lost)\. This option is primarily useful for automated +testing\. +.IP "\fB--odb-file-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR to construct the names of the generated C++ files\. In the +single-database mode the default value for this option is \fB-odb\fR\. In the +multi-database mode it is \fB-odb\fR for the files corresponding to the +\fBcommon\fR database and \fB-odb-\fR\fIdb\fR\fR (where \fIdb\fR is the +database name) for other databases\. +.IP "\fB--sql-file-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR to construct the name of the generated schema SQL file\. In +the single-database mode by default no suffix is used\. In the multi-database +mode the default value for this option is \fB-\fR\fIdb\fR\fR (where \fIdb\fR +is the database name)\. +.IP "\fB--schema-file-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR to construct the name of the generated schema C++ source +file\. In the single-database mode the default value for this option is +\fB-schema\fR\. In the multi-database mode it is \fB-schema-\fR\fIdb\fR\fR +(where \fIdb\fR is the database name)\. See the \fB--schema-format\fR option +for details\. +.IP "\fB--changelog-file-suffix\fR \fIsfx\fR" +Use \fIsfx\fR to construct the name of the changelog file\. In the +single-database mode by default no suffix is used\. In the multi-database mode +the default value for this option is \fB-\fR\fIdb\fR\fR (where \fIdb\fR is the +database name)\. +.IP "\fB--hxx-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.hxx\fR to construct the name of +the generated C++ header file\. +.IP "\fB--ixx-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.ixx\fR to construct the name of +the generated C++ inline file\. +.IP "\fB--cxx-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.cxx\fR to construct the name of +the generated C++ source file\. +.IP "\fB--sql-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.sql\fR to construct the name of +the generated database schema file\. +.IP "\fB--changelog-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.xml\fR to construct the name of +the changelog file\. +.IP "\fB--hxx-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated C++ header file\. +.IP "\fB--ixx-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated C++ inline file\. +.IP "\fB--cxx-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated C++ source file\. +.IP "\fB--schema-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated schema C++ source file\. +.IP "\fB--sql-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated database schema file\. +.IP "\fB--migration-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated database migration file\. +.IP "\fB--sql-interlude\fR \fItext\fR" +Insert \fItext\fR after all the \fBDROP\fR and before any \fBCREATE\fR +statements in the generated database schema file\. +.IP "\fB--hxx-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated C++ header file\. +.IP "\fB--ixx-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated C++ inline file\. +.IP "\fB--cxx-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated C++ source file\. +.IP "\fB--schema-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated schema C++ source file\. +.IP "\fB--sql-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated database schema file\. +.IP "\fB--migration-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated database migration file\. +.IP "\fB--hxx-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated C++ header +file\. +.IP "\fB--ixx-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated C++ inline +file\. +.IP "\fB--cxx-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated C++ source +file\. +.IP "\fB--schema-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated schema C++ +source file\. +.IP "\fB--sql-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated database +schema file\. +.IP "\fB--migration-prologue-file\fR \fIf\fR" +Insert the content of file \fIf\fR at the beginning of the generated database +migration file\. +.IP "\fB--sql-interlude-file\fR \fIfile\fR" +Insert the content of \fIfile\fR after all the \fBDROP\fR and before any +\fBCREATE\fR statements in the generated database schema file\. +.IP "\fB--hxx-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated C++ header file\. +.IP "\fB--ixx-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated C++ inline file\. +.IP "\fB--cxx-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated C++ source file\. +.IP "\fB--schema-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated schema C++ source +file\. +.IP "\fB--sql-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated database schema +file\. +.IP "\fB--migration-epilogue-file\fR \fIf\fR" +Insert the content of file \fIf\fR at the end of the generated database +migration file\. +.IP "\fB--odb-prologue\fR \fItext\fR" +Compile \fItext\fR before the input header file\. This option allows you to +add additional declarations, such as custom traits specializations, to the ODB +compilation process\. +.IP "\fB--odb-prologue-file\fR \fIfile\fR" +Compile \fIfile\fR contents before the input header file\. Prologue files are +compiled after all the prologue text fragments (\fB--odb-prologue\fR option)\. +.IP "\fB--odb-epilogue\fR \fItext\fR" +Compile \fItext\fR after the input header file\. This option allows you to add +additional declarations, such as custom traits specializations, to the ODB +compilation process\. +.IP "\fB--odb-epilogue-file\fR \fIfile\fR" +Compile \fIfile\fR contents after the input header file\. Epilogue files are +compiled after all the epilogue text fragments (\fB--odb-epilogue\fR option)\. +.IP "\fB--table-prefix\fR \fIprefix\fR" +Add \fIprefix\fR to table names and, for databases that have global index +and/or foreign key names, to those names as well\. The prefix is added to both +names that were specified with the \fBdb table\fR and \fBdb index\fR pragmas +and those that were automatically derived from class and data member names\. +If you require a separator, such as an underscore, between the prefix and the +name, then you should include it into the prefix value\. +.IP "\fB--index-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB_i\fR to construct index names\. +The suffix is only added to names that were automatically derived from data +member names\. If you require a separator, such as an underscore, between the +name and the suffix, then you should include it into the suffix value\. +.IP "\fB--fkey-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB_fk\fR to construct foreign key +names\. If you require a separator, such as an underscore, between the name +and the suffix, then you should include it into the suffix value\. +.IP "\fB--sequence-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB_seq\fR to construct sequence +names\. If you require a separator, such as an underscore, between the name +and the suffix, then you should include it into the suffix value\. +.IP "\fB--sql-name-case\fR \fIcase\fR" +Convert all automatically-derived SQL names to upper or lower case\. Valid +values for this option are \fBupper\fR and \fBlower\fR\. +.IP "\fB--table-regex\fR \fIregex\fR" +Add \fIregex\fR to the list of regular expressions that is used to transform +automatically-derived table names\. See the SQL NAME TRANSFORMATIONS section +below for details\. +.IP "\fB--column-regex\fR \fIregex\fR" +Add \fIregex\fR to the list of regular expressions that is used to transform +automatically-derived column names\. See the SQL NAME TRANSFORMATIONS section +below for details\. +.IP "\fB--index-regex\fR \fIregex\fR" +Add \fIregex\fR to the list of regular expressions that is used to transform +automatically-derived index names\. See the SQL NAME TRANSFORMATIONS section +below for details\. +.IP "\fB--fkey-regex\fR \fIregex\fR" +Add \fIregex\fR to the list of regular expressions that is used to transform +automatically-derived foreign key names\. See the SQL NAME TRANSFORMATIONS +section below for details\. +.IP "\fB--sequence-regex\fR \fIregex\fR" +Add \fIregex\fR to the list of regular expressions that is used to transform +automatically-derived sequence names\. See the SQL NAME TRANSFORMATIONS +section below for details\. +.IP "\fB--statement-regex\fR \fIregex\fR" +Add \fIregex\fR to the list of regular expressions that is used to transform +automatically-derived prepared statement names\. See the SQL NAME +TRANSFORMATIONS section below for details\. +.IP "\fB--sql-name-regex\fR \fIregex\fR" +Add \fIregex\fR to the list of regular expressions that is used to transform +all automatically-derived SQL names\. See the SQL NAME TRANSFORMATIONS section +below for details\. +.IP "\fB--sql-name-regex-trace\fR" +Trace the process of applying regular expressions specified with the SQL name +\fB--*-regex\fR options\. Use this option to find out why your regular +expressions don't do what you expected them to do\. +.IP "\fB--accessor-regex\fR \fIregex\fR" +Add \fIregex\fR to the list of regular expressions used to transform data +member names to function names when searching for a suitable accessor +function\. The argument to this option is a Perl-like regular expression in +the form \fB/\fR\fIpattern\fR\fB/\fR\fIreplacement\fR\fB/\fR\fR\. Any +character can be used as a delimiter instead of '\fB/\fR' and the delimiter +can be escaped inside \fIpattern\fR and \fIreplacement\fR with a backslash +(\fB\e\fR)\. You can specify multiple regular expressions by repeating this +option\. + +All the regular expressions are tried in the order specified and the first +expression that produces a suitable accessor function is used\. Each +expression is tried twice: first with the actual member name and then with the +member's \fIpublic name\fR which is obtained by removing the common member +name decorations, such as leading and trailing underscores, the \fBm_\fR +prefix, etc\. The ODB compiler also includes a number of built-in expressions +for commonly used accessor names, such as \fBget_foo\fR, \fBgetFoo\fR, +\fBgetfoo\fR, and just \fBfoo\fR\. The built-in expressions are tried last\. + +As an example, the following expression transforms data members with public +names in the form \fBfoo\fR to accessor names in the form \fBGetFoo\fR: + +\fB/(\.+)/Get\eu$1/\fR + +See also the REGEX AND SHELL QUOTING section below\. +.IP "\fB--accessor-regex-trace\fR" +Trace the process of applying regular expressions specified with the +\fB--accessor-regex\fR option\. Use this option to find out why your regular +expressions don't do what you expected them to do\. +.IP "\fB--modifier-regex\fR \fIregex\fR" +Add \fIregex\fR to the list of regular expressions used to transform data +member names to function names when searching for a suitable modifier +function\. The argument to this option is a Perl-like regular expression in +the form \fB/\fR\fIpattern\fR\fB/\fR\fIreplacement\fR\fB/\fR\fR\. Any +character can be used as a delimiter instead of '\fB/\fR' and the delimiter +can be escaped inside \fIpattern\fR and \fIreplacement\fR with a backslash +(\fB\e\fR)\. You can specify multiple regular expressions by repeating this +option\. + +All the regular expressions are tried in the order specified and the first +expression that produces a suitable modifier function is used\. Each +expression is tried twice: first with the actual member name and then with the +member's \fIpublic name\fR which is obtained by removing the common member +name decorations, such as leading and trailing underscores, the \fBm_\fR +prefix, etc\. The ODB compiler also includes a number of built-in expressions +for commonly used modifier names, such as \fBset_foo\fR, \fBsetFoo\fR, +\fBsetfoo\fR, and just \fBfoo\fR\. The built-in expressions are tried last\. + +As an example, the following expression transforms data members with public +names in the form \fBfoo\fR to modifier names in the form \fBSetFoo\fR: + +\fB/(\.+)/Set\eu$1/\fR + +See also the REGEX AND SHELL QUOTING section below\. +.IP "\fB--modifier-regex-trace\fR" +Trace the process of applying regular expressions specified with the +\fB--modifier-regex\fR option\. Use this option to find out why your regular +expressions don't do what you expected them to do\. +.IP "\fB--include-with-brackets\fR" +Use angle brackets (<>) instead of quotes ("") in the generated \fB#include\fR +directives\. +.IP "\fB--include-prefix\fR \fIprefix\fR" +Add \fIprefix\fR to the generated \fB#include\fR directive paths\. +.IP "\fB--include-regex\fR \fIregex\fR" +Add \fIregex\fR to the list of regular expressions used to transform generated +\fB#include\fR directive paths\. The argument to this option is a Perl-like +regular expression in the form +\fB/\fR\fIpattern\fR\fB/\fR\fIreplacement\fR\fB/\fR\fR\. Any character can be +used as a delimiter instead of '\fB/\fR' and the delimiter can be escaped +inside \fIpattern\fR and \fIreplacement\fR with a backslash (\fB\e\fR)\. You +can specify multiple regular expressions by repeating this option\. All the +regular expressions are tried in the order specified and the first expression +that matches is used\. + +As an example, the following expression transforms include paths in the form +\fBfoo/bar-odb\.h\fR to paths in the form \fBfoo/generated/bar-odb\.h\fR: + +\fB%foo/(\.+)-odb\.h%foo/generated/$1-odb\.h%\fR + +See also the REGEX AND SHELL QUOTING section below\. +.IP "\fB--include-regex-trace\fR" +Trace the process of applying regular expressions specified with the +\fB--include-regex\fR option\. Use this option to find out why your regular +expressions don't do what you expected them to do\. +.IP "\fB--guard-prefix\fR \fIprefix\fR" +Add \fIprefix\fR to the generated header inclusion guards\. The prefix is +transformed to upper case and characters that are illegal in a preprocessor +macro name are replaced with underscores\. +.IP "\fB--show-sloc\fR" +Print the number of generated physical source lines of code (SLOC)\. +.IP "\fB--sloc-limit\fR \fInum\fR" +Check that the number of generated physical source lines of code (SLOC) does +not exceed \fInum\fR\. +.IP "\fB--options-file\fR \fIfile\fR" +Read additional options from \fIfile\fR\. Each option should appear on a +separate line optionally followed by space or equal sign (\fB=\fR) and an +option value\. Empty lines and lines starting with \fB#\fR are ignored\. +Option values can be enclosed in double (\fB"\fR) or single (\fB'\fR) quotes +to preserve leading and trailing whitespaces as well as to specify empty +values\. If the value itself contains trailing or leading quotes, enclose it +with an extra pair of quotes, for example \fB'"x"'\fR\. Non-leading and +non-trailing quotes are interpreted as being part of the option value\. + +The semantics of providing options in a file is equivalent to providing the +same set of options in the same order on the command line at the point where +the \fB--options-file\fR option is specified except that the shell escaping +and quoting is not required\. Repeat this option to specify more than one +options file\. +.IP "\fB-x\fR \fIoption\fR" +Pass \fIoption\fR to the underlying C++ compiler (\fBg++\fR)\. The +\fIoption\fR value that doesn't start with '\fB-\fR' is considered the +\fBg++\fR executable name\. +.IP "\fB-v\fR" +Print the commands executed to run the stages of compilation\. +.IP "\fB--trace\fR" +Trace the compilation process\. +.IP "\fB--mysql-engine\fR \fIengine\fR" +Use \fIengine\fR instead of the default \fBInnoDB\fR in the generated database +schema file\. For more information on the storage engine options see the MySQL +documentation\. If you would like to use the database-default engine, pass +\fBdefault\fR as the value for this option\. +.IP "\fB--sqlite-override-null\fR" +Make all columns in the generated database schema allow \fBNULL\fR values\. +This is primarily useful in schema migration since SQLite does not support +dropping of columns\. By making all columns \fBNULL\fR we can later "delete" +them by setting their values to \fBNULL\fR\. Note that this option overrides +even the \fBnot_null\fR pragma\. +.IP "\fB--sqlite-lax-auto-id\fR" +Do not force monotonically increasing automatically-assigned object ids\. In +this mode the generated database schema omits the \fBAUTOINCREMENT\fR keyword +which results in faster object persistence but may lead to +automatically-assigned ids not being in a strictly ascending order\. Refer to +the SQLite documentation for details\. +.IP "\fB--pgsql-server-version\fR \fIver\fR" +Specify the minimum PostgreSQL server version with which the generated C++ +code and schema will be used\. This information is used to enable +version-specific optimizations and workarounds in the generated C++ code and +schema\. The version must be in the \fImajor\fR\fB\.\fR\fIminor\fR\fR form, +for example, \fB9\.1\fR\. If this option is not specified, then \fB7\.4\fR or +later is assumed\. +.IP "\fB--oracle-client-version\fR \fIver\fR" +Specify the minimum Oracle client library (OCI) version with which the +generated C++ code will be linked\. This information is used to enable +version-specific optimizations and workarounds in the generated C++ code\. The +version must be in the \fImajor\fR\fB\.\fR\fIminor\fR\fR form, for example, +\fB11\.2\fR\. If this option is not specified, then \fB10\.1\fR or later is +assumed\. +.IP "\fB--oracle-warn-truncation\fR" +Warn about SQL names that are longer than 30 characters and are therefore +truncated\. Note that during database schema generation +(\fB--generate-schema\fR) ODB detects when such truncations lead to name +conflicts and issues diagnostics even without this option specified\. +.IP "\fB--mssql-server-version\fR \fIver\fR" +Specify the minimum SQL Server server version with which the generated C++ +code and schema will be used\. This information is used to enable +version-specific optimizations and workarounds in the generated C++ code and +schema\. The version must be in the \fImajor\fR\fB\.\fR\fIminor\fR\fR form, +for example, \fB9\.0\fR (SQL Server 2005), \fB10\.5\fR (2008R2), or +\fB11\.0\fR (2012)\. If this option is not specified, then \fB10\.0\fR (SQL +Server 2008) or later is assumed\. +.IP "\fB--mssql-short-limit\fR \fIsize\fR" +Specify the short data size limit\. If a character, national character, or +binary data type has a maximum length (in bytes) less than or equal to this +limit, then it is treated as \fIshort data\fR, otherwise it is \fIlong +data\fR\. For short data ODB pre-allocates an intermediate buffer of the +maximum size and binds it directly to a parameter or result column\. This way +the underlying API (ODBC) can read/write directly from/to this buffer\. In the +case of long data, the data is read/written in chunks using the +\fBSQLGetData()\fR/\fBSQLPutData()\fR ODBC functions\. While the long data +approach reduces the amount of memory used by the application, it may require +greater CPU resources\. The default short data limit is 1024 bytes\. When +setting a custom short data limit, make sure that it is sufficiently large so +that no object id in the application is treated as long data\. +.\" +.\" 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) 2009-2023 Code Synthesis Tools CC. + +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 |