Permalink
Browse files

documentation changes

  • Loading branch information...
1 parent fa189ea commit c948d5214797bfb56cc42d2f8c9b3258ce29876d yarivvv committed Dec 25, 2007
View
@@ -1,5 +1,9 @@
v0.7
+- Added yaws_arg:add_to_opaque/2, yaws_arg:add_all_to_opaque/2, and
+yaws_arg:get_opaque_val/2 to simplify accessing the 'opaque' field of the
+Yaws arg record.
+
- Added support for multiple databases. More information is in the
documentation. (yariv)
View
@@ -99,16 +99,19 @@
<h2><a name="types">Data Types</a></h2>
<h3><a name="type-driver">driver()</a></h3>
-<p><tt>driver() = {Driver, Options::<a href="#type-proplist">proplist()</a>} | {Driver, Options::<a href="#type-proplist">proplist()</a>, [<a href="#type-pool">pool()</a>]}</tt></p>
+<p><tt>driver() = atom() | {Driver::atom(), DriverOptions::<a href="#type-proplist">proplist()</a>} | {Driver::atom(), DriverOptions::<a href="#type-proplist">proplist()</a>, [<a href="#type-pool">pool()</a>]}</tt></p>
<h3><a name="type-pool">pool()</a></h3>
<p><tt>pool() = atom() | {default, PoolId::atom()}</tt></p>
<h2><a name="index">Function Index</a></h2>
-<table width="100%" border="1"><tr><td valign="top"><a href="#code_gen-2">code_gen/2</a></td><td>Generate code for the list of modules using the provided drivers.</td></tr>
-<tr><td valign="top"><a href="#code_gen-3">code_gen/3</a></td><td/></tr>
+<table width="100%" border="1"><tr><td valign="top"><a href="#code_gen-2">code_gen/2</a></td><td>Equivalent to <a href="#code_gen-3"><tt>code_gen(Modules, Drivers, [])</tt></a>.
+</td></tr>
+<tr><td valign="top"><a href="#code_gen-3">code_gen/3</a></td><td>Equivalent to <a href="#code_gen-4"><tt>code_gen(Modules, Drivers, Options, [])</tt></a>.
+</td></tr>
+<tr><td valign="top"><a href="#code_gen-4">code_gen/4</a></td><td>Generate code for the list of modules using the provided drivers.</td></tr>
<tr><td valign="top"><a href="#start-1">start/1</a></td><td>Start an ErlyDB session for the driver using the driver's default
options.</td></tr>
<tr><td valign="top"><a href="#start-2">start/2</a></td><td>Start an ErlyDB sessions for the driver using the list of
@@ -118,94 +121,132 @@
<h2><a name="functions">Function Details</a></h2>
<h3><a name="code_gen-2">code_gen/2</a></h3>
-<p><tt>code_gen(Modules::[Module::atom() | string()], Options::[<a href="#type-driver">driver()</a>]) -&gt; ok | {error, Err}</tt></p>
+<tt>code_gen(Modules, Drivers) -&gt; term()
+</tt><p>Equivalent to <a href="#code_gen-3"><tt>code_gen(Modules, Drivers, [])</tt></a>.</p>
+
+
+<h3><a name="code_gen-3">code_gen/3</a></h3>
+<tt>code_gen(Modules, Drivers, Options) -&gt; term()
+</tt><p>Equivalent to <a href="#code_gen-4"><tt>code_gen(Modules, Drivers, Options, [])</tt></a>.</p>
+
+
+<h3><a name="code_gen-4">code_gen/4</a></h3>
+<p><tt>code_gen(Modules::[Module::atom() | string()], Driver::[<a href="#type-driver">driver()</a>] | <a href="#type-driver">driver()</a>, Options::[term()], IncludePaths::[IncludePath::string()]) -&gt; ok | {error, Err}</tt></p>
<p><p>Generate code for the list of modules using the provided drivers.</p>
+ <p>If you're using ErlyWeb, you shouldn't need to call this function directly.
+ Instead, refer to <a href="erlyweb.html#compile-2"><code>erlyweb:compile/2</code></a>.</p>
+
+ <h4><a name="Usage">Usage</a></h4>
+
<p>In ErlyWeb 0.7, the signature for this function has changed.
ErlyDB used to support only a single driver with a single connection
pool in a session. As of ErlyWeb 0.7, ErlyDB supports multiple
drivers in a session, and multiple connection pools for each
driver.</p>
- <p>The 'Modules' parameter is a list of files or modules for which to
+ <h5><a name="Modules">Modules</a></h5><p>
+The 'Modules' parameter is a list of files or modules for which to
generate ErlyDB code. If a list item is an atom, ErlyDB assumes it's
-a module that has been loaded into the VM or that resides in the
+a module that has been loaded into the VM or that resides in the VM's
code path. In either case, the module's source code should be discoverable
-either through path conventions or because it includes debug_info.
-If a list item is a string, ErlyDB treats it as a file name (relative
+either through Erlang's path conventions or because the module
+was compiled with debug_info.</p>
+
+ <p>If a list item is a string, ErlyDB treats it as a file name (relative
or absolute) and attempts to read it from disk.</p>
- <p>The 'Driver's parameter is a list of Driver::atom(),
-{Driver::atom(), Options::proplist()} or
-{Driver::atom(), Options::proplist(), Pools::pool()} tuples.
-The first tuple in the Drivers list is
+ <h5><a name="Drivers">Drivers</a></h5><p>
+ The 'Drivers' parameter is either a single element or a list of
+ elements of the form
+ <code>Driver::atom()</code>,
+ <code>{Driver::atom(), DriverOptions::proplist()}</code>, or
+ <code>{Driver::atom(), DriverOptions::proplist(), Pools::pool()}</code>.</p>
+
+ <p>The first element in the Drivers list is
the default driver that ErlyDB will use for all modules that don't
override the driver option.</p>
- <p>Driver can be 'mysql', 'psql' or 'mnesia'. Options is a list of
+ <p>'Driver' can be <code>mysql</code>, <code>psql</code> or <code>mnesia</code>. 'Options' is a list of
driver-specific options. For a list of available options, refer to
the driver's documentation.</p>
- <p>Pools is a list of available connection pools for the driver.
-Note that the driver must be started and the pools must be connected
-before code_gen/2 is called. Each item in Pools is an atom indicating
-the pool id, or a tuple of the form {default, PoolId}, indicating
-that this pool will be used as the default pool for the driver.
-If you don't provide a {default, PoolId} pool option, ErlyDB will use
-the built-in default pool id.</p>
+ <p>'DriverOptions' is a property list that contains driver-specific options
+(e.g. '{allow_unsafe_statements, Bool}').
+For more information refer to the driver's documentation.</p>
+
+ <p>'Pools' is a list of available connection pools for the driver.
+ Note that the driver must be started and the pools must be connected
+ before code_gen/2 is called. Each item in 'Pools' is an atom indicating
+ the pool id, or a tuple of the form <code>{PoolId, default}</code>, which indicates
+ that this pool will be used as the default pool for the driver.
+ If you don't provide a <code>{PoolId, default}</code> pool option, ErlyDB will use
+the driver-defined default pool id if it exists (you can obtain it by
+calling Mod:get_default_pool_id(), where 'Mod' is the driver's
+module, e.g. 'erlydb_mysql').</p>
+
+ <h5><a name="Options">Options</a></h5>
- <p>Below are some examples:</p>
+ <p>'Options' is a list of options that are used for all modules. This may
+include global driver options as well as options that are passed to
+compile:file/2. For more information, refer to this function's documentation
+in the OTP documentation.</p>
+
+ <h5><a name="IncludePaths">IncludePaths</a></h5>
+
+ <p>Additional include paths that will be used to search for header files
+when compiling the modules.</p>
+
+ <h4><a name="Examples">Examples</a></h4>
<p>Generate code for "musician.erl" using the MySQL driver. Only the default
pool is enabled.</p>
- <pre> code_gen(["musician.erl"], [mysql]).</pre>
+ <pre> code_gen(["musician.erl"], mysql).</pre>
- <p>To use the previous settings but allow unsafe SQL statements, use
-the following:</p>
+ <p>Use the previous settings but allow unsafe SQL statements, and compile
+with debug_info:</p>
- <pre> code_gen(["musician.erl"], [{mysql, [{allow_unsafe_statements, true}]}]).</pre>
+ <pre> code_gen(["musician.erl"],
+ {mysql, [{allow_unsafe_statements, true}]},
+ [debug_info]).</pre>
- <p>Generate code for the modules using the MySQL driver with two additional
-pools, 'pool1' and 'pool2'. The default pool is not overridden.</p>
+ <p>Generate code for the modules using the MySQL driver with two additional
+ pools, 'pool1' and 'pool2'. The default pool is remains <code>erlydb_mysql</code>:</p>
<pre> code_gen(["musician.erl", "instrument.erl"],
- [{mysql, [], [pool1, pool2]}]).</pre>
+ {mysql, [], [pool1, pool2]}).</pre>
+ <p>Similar to the previous setting, but allow unsafe statement and use
+ <code>pool2</code> as the default pool name:</p>
+ <pre> code_gen(["src/musician.erl", "src/instrument.erl"],
+ {mysql, [{allow_unsafe_statements, true}],
+ [{pool1, {pool2, default}}]})</pre>
- <p>tells ErlyDB to use the 'mysql' driver with the default
-code_gen(["src/musician.erl", "src/instrument.erl"],
-[{mysql, [{allow_unsafe_statements, true}],
-[{pool1, {default, pool2}}]}])
-'''</p>
-
- <p>To specify which connection pool ErlyDB should for a specific module, add
-the following line to the module's source code:</p>
+ <p>Generate code for the modules using both the MySQL and Postgres driver.
+The MySQL driver has 2 pools enabled: mysql_pool1 and mysql_pool2, which is
+the default. The Postgres driver has a single default pool, pg_pool1.
+The MySQL driver allows unsafe statements:</p>
- <pre> -erlydb_options(pool_id, PoolId).</pre>
+ <pre> code_gen(["src/musician.erl", "src/instrument.erl", "src/song.erl"],
+ [{mysql, [{allow_unsafe_statements, true}],
+ [{mysql_pool1, {mysql_pool2, default}}]},
+ {psql, [], [{pg_pool1, default}]}])</pre>
- <p>This tells ErlyDB to use the default driver, but a non-default pool id.
-If you want the module to use a non-default driver, use the attribute</p>
+ <h4><a name="Module-Specific_Settings">Module-Specific Settings</a></h4>
- <p>'''
--erlydb_options(driver, Driver).
-'''
-or</p>
+ <p>To specify which connection pool ErlyDB should for a specific module, add
+the following line to the module's source code:</p>
- <p>'''
--erlydb_options(driver, {Driver, PoolId}).
-'''</p>
+ <pre> -erlydb_options([{driver, Driver}, {pool_id, PoolId}]).</pre>
- The first option tells ErlyDB to use a non-default driver with the
- default pool id for the driver. The second option tells ErlyDB
- to use a non-default driver, and a non-default pool id for the driver.
+ The 'driver' option tells ErlyDB to use a non-default driver for the
+ module. The 'pool_id' option tells ErlyDB to use a non-default pool id
+ for the module. Neither option is required -- you can specify only
+ a 'driver' option or only a 'pool_id' option.
</p>
-<h3><a name="code_gen-3">code_gen/3</a></h3>
-<tt>code_gen(Modules, Options, IncludePaths) -&gt; term()
-</tt>
-
<h3><a name="start-1">start/1</a></h3>
<p><tt>start(Driver::atom()) -&gt; ok | {error, Err}</tt></p>
<p>Start an ErlyDB session for the driver using the driver's default
View
@@ -84,7 +84,7 @@
fields.</td></tr>
<tr><td valign="top"><a href="#aggregate_related_many_to_many-7">aggregate_related_many_to_many/7</a></td><td>This function works as <a href="#aggregate_related_many_to_one-5"><code>aggregate_related_many_to_one/5</code></a>, but
for modules defining many-to-many relations.</td></tr>
-<tr><td valign="top"><a href="#aggregate_related_many_to_one-6">aggregate_related_many_to_one/6</a></td><td>Get aggregate statistics about fields from related records in
+<tr><td valign="top"><a href="#aggregate_related_many_to_one-7">aggregate_related_many_to_one/7</a></td><td>Get aggregate statistics about fields from related records in
one-to-many relations.</td></tr>
<tr><td valign="top"><a href="#before_delete-1">before_delete/1</a></td><td>A hook that gets called before a record is deleted.</td></tr>
<tr><td valign="top"><a href="#before_save-1">before_save/1</a></td><td>A hook that gets called before a record is saved.</td></tr>
@@ -126,8 +126,8 @@
according to the Where and Extras expressions.</td></tr>
<tr><td valign="top"><a href="#find_related_many_to_many-5">find_related_many_to_many/5</a></td><td>This function works as <a href="#find_related_many_to_one-4"><code>find_related_many_to_one/4</code></a>, but
for modules defining many-to-many relations.</td></tr>
-<tr><td valign="top"><a href="#find_related_many_to_one-4">find_related_many_to_one/4</a></td><td>Find the set of related records in a one-to-many relation.</td></tr>
-<tr><td valign="top"><a href="#find_related_one_to_many-2">find_related_one_to_many/2</a></td><td>Find the related record for a record from a module having a
+<tr><td valign="top"><a href="#find_related_many_to_one-5">find_related_many_to_one/5</a></td><td>Find the set of related records in a one-to-many relation.</td></tr>
+<tr><td valign="top"><a href="#find_related_one_to_many-3">find_related_one_to_many/3</a></td><td>Find the related record for a record from a module having a
many-to-one relation.</td></tr>
<tr><td valign="top"><a href="#get-2">get/2</a></td><td>A generic getter function ErlyDB uses to generate getters, e.g.</td></tr>
<tr><td valign="top"><a href="#get_module-1">get_module/1</a></td><td>Get the name of the module to which the record belongs.</td></tr>
@@ -159,7 +159,7 @@
<tr><td valign="top"><a href="#set_fields_from_strs-3">set_fields_from_strs/3</a></td><td>Equivalent to <a href="#set_fields-4"><tt>set_fields(Module, Record, Fields,
fun field_from_string/2)</tt></a>.
</td></tr>
-<tr><td valign="top"><a href="#set_related_one_to_many-2">set_related_one_to_many/2</a></td><td>Set the foreign key fields of a record from a module having a
+<tr><td valign="top"><a href="#set_related_one_to_many-3">set_related_one_to_many/3</a></td><td>Set the foreign key fields of a record from a module having a
many-to-one relation to the primary key values of the Other record.</td></tr>
<tr><td valign="top"><a href="#table-0">table/0</a></td><td>Return the name of the table that holds the records for this module.</td></tr>
<tr><td valign="top"><a href="#to_iolist-2">to_iolist/2</a></td><td>Equivalent to <a href="#to_iolist-3"><tt>to_iolist(Module, Recs, fun field_to_iolist/2)</tt></a>.
@@ -255,8 +255,8 @@
</p>
<p><b>See also:</b> <a href="#aggregate_related_many_to_one-5">aggregate_related_many_to_one/5</a>.</p>
-<h3><a name="aggregate_related_many_to_one-6">aggregate_related_many_to_one/6</a></h3>
-<p><tt>aggregate_related_many_to_one(OtherModule::atom(), AggFunc::atom(), Rec::<a href="#type-record">record()</a>, Field::atom(), Where::<a href="#type-where_expr">where_expr()</a>, Extras::<a href="#type-extras_expr">extras_expr()</a>) -&gt; float() | integer() | <a href="#type-exit">exit(Err)</a></tt></p>
+<h3><a name="aggregate_related_many_to_one-7">aggregate_related_many_to_one/7</a></h3>
+<p><tt>aggregate_related_many_to_one(OtherModule::atom(), PkFks::term(), AggFunc::atom(), Rec::<a href="#type-record">record()</a>, Field::atom(), Where::<a href="#type-where_expr">where_expr()</a>, Extras::<a href="#type-extras_expr">extras_expr()</a>) -&gt; float() | integer() | <a href="#type-exit">exit(Err)</a></tt></p>
<p><p>Get aggregate statistics about fields from related records in
one-to-many relations.</p>
@@ -583,8 +583,8 @@
</p>
<p><b>See also:</b> <a href="#find_related_many_to_one-4">find_related_many_to_one/4</a>.</p>
-<h3><a name="find_related_many_to_one-4">find_related_many_to_one/4</a></h3>
-<p><tt>find_related_many_to_one(OtherModule::atom(), Rec::<a href="#type-record">record()</a>, Where::<a href="#type-where_expr">where_expr()</a>, Extras::<a href="#type-extras_expr">extras_expr()</a>) -&gt; [<a href="#type-record">record()</a>] | <a href="#type-exit">exit(Err)</a></tt></p>
+<h3><a name="find_related_many_to_one-5">find_related_many_to_one/5</a></h3>
+<p><tt>find_related_many_to_one(OtherModule::atom(), PkFks::term(), Rec::<a href="#type-record">record()</a>, Where::<a href="#type-where_expr">where_expr()</a>, Extras::<a href="#type-extras_expr">extras_expr()</a>) -&gt; [<a href="#type-record">record()</a>] | <a href="#type-exit">exit(Err)</a></tt></p>
<p><p>Find the set of related records in a one-to-many relation.</p>
<p>This function isn't meant to be used directly; ErlyDB uses this function
@@ -617,8 +617,8 @@
</p>
<p><b>See also:</b> <a href="#find-3">find/3</a>, <a href="#find_first-3">find_first/3</a>, <a href="#find_max-4">find_max/4</a>, <a href="#find_range-5">find_range/5</a>.</p>
-<h3><a name="find_related_one_to_many-2">find_related_one_to_many/2</a></h3>
-<p><tt>find_related_one_to_many(OtherModule::atom(), Rec::<a href="#type-record">record()</a>) -&gt; <a href="#type-record">record()</a> | <a href="#type-exit">exit(Err)</a></tt></p>
+<h3><a name="find_related_one_to_many-3">find_related_one_to_many/3</a></h3>
+<p><tt>find_related_one_to_many(OtherModule::atom(), PkFkfields::<a href="#type-proplist">proplist()</a>, Rec::<a href="#type-record">record()</a>) -&gt; <a href="#type-record">record()</a> | <a href="#type-exit">exit(Err)</a></tt></p>
<p><p>Find the related record for a record from a module having a
many-to-one relation.</p>
@@ -835,8 +835,8 @@
<p><b>See also:</b> <a href="#field_from_string-2">field_from_string/2</a>.</p>
-<h3><a name="set_related_one_to_many-2">set_related_one_to_many/2</a></h3>
-<p><tt>set_related_one_to_many(Rec::<a href="#type-record">record()</a>, Other::<a href="#type-record">record()</a>) -&gt; <a href="#type-record">record()</a> | <a href="#type-exit">exit(Err)</a></tt></p>
+<h3><a name="set_related_one_to_many-3">set_related_one_to_many/3</a></h3>
+<p><tt>set_related_one_to_many(Rec::<a href="#type-record">record()</a>, PkFkFields::<a href="#type-proplist">proplist()</a>, Other::<a href="#type-record">record()</a>) -&gt; <a href="#type-record">record()</a> | <a href="#type-exit">exit(Err)</a></tt></p>
<p><p>Set the foreign key fields of a record from a module having a
many-to-one relation to the primary key values of the Other record.</p>
Oops, something went wrong.

0 comments on commit c948d52

Please sign in to comment.