diff --git a/tutorial/tutorial.wmml b/tutorial/tutorial.wmml index dc257e37bae3be639eca1d72564d0b8af3484879..d254925a8ae96f77fc2cfba787fc9bba42618bee 100644 --- a/tutorial/tutorial.wmml +++ b/tutorial/tutorial.wmml @@ -7470,7 +7470,7 @@ object map(funcion <i>fu</i>, string|int|array(int|string) <i>columns</i>, mixed This method calls the function for all rows in the table. The value returned will replace the values in the columns given as argument to map. If the function returns an array, several columns will be replaced. Otherwise -on the first column will be replaced. The result will be returned as a new +the first column will be replaced. The result will be returned as a new table object. </man_description> </method> @@ -7660,6 +7660,257 @@ write(.Table.ASCII.encode(t->select("frukt")->distinct("frukt")-> <hr noshade size=1> +<module name=Yabu> +<section title="Yabu"> +Yabu is an all purpose database, used to store data records associated with a +unique key. Yabu is very similar to mappings, however, records are +stored in files and not in memory. Also, Yabu features <i>tables</i>, +which is a way to handle several mapping-like structures in the same +database. A characteristic feature of Yabu is that it allows for +<i>transactions</i>. A transaction is a sequence of database manipulations +that will be accepted in whole, or not at all.<p> + +Alot of effort have been put to make sure that Yabu is crash safe. +This means that the database should survive process kills, core dumps +and such. Also, all non-commited and pending transactions will be +cancelled in case of a crash.<p> + +<man_note> +It is very important not to open the same a database more than +once at a time. Otherwise there will be conflicts and most likely +strange failures and unpredictable behaviours. Yabu does not check +weather a database is already open or not. +</man_note> + +<hr noshade size=1> + +<method name=Yabu.db->create title="opens a Yabu database"> +<man_syntax> +void create(string <i>directory</i>, string <i>mode</i>); +</man_syntax> +<man_description> +Create takes two arguments:<p> +<ol> +<li><i>directory</i> is a string specifying the directory where Yabu will +store its files. Yabu will create the directory if it does not exist, +provided Yabu is opened in write and create mode (see below).<p> +<li><i>mode</i> is a string specifying the mode in which Yabu will +operate. There are four switches available:<p> +<blockquote> +"r" - Read mode. No database entries can be altered and no files will +be modified.<p> +"c" - Create mode. The database can create new tables. Create mode is +only used togheter with write mode.<p> +"w" - Write mode. The database can be altered and the files will be +updates accordingly.<p> +"C" - Compress mode. Provided the <link to=Gz>Gz-module</link> is +available, all records will be compressed before stored on to disk.<p> +</blockquote> +</ol> +</man_description> +<man_example> +<example language=pike> +// Open a database in create/write mode. +object db = Yabu.db("my.database", "cw"); + +// Open a database in read mode. +object db = Yabu.db("my.database", "r"); + +// Open a database in create/write/compress mode. +object db = Yabu.db("my.database", "cwC"); +</example> +</man_example> +</method> + +<hr noshade size=1> + +<method name=Yabu.db->table title="opens a table"> +<man_syntax> +object(table) table(string <i>table_name</i>);<br> +</man_syntax> +<man_description> +This method opens a table with <i>table_name</i>. If the table +does not exist, it will be created. A table object will be returned. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.db->`[] title="opens a table"> +<man_syntax> +object(table) `[](string <i>table_name</i>);<br> +</man_syntax> +<man_description> +Synonymous with <link to=Yabu.db.table>table</link>. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.db->_indices title="lists all tables"> +<man_syntax> +array(string) _indices();<br> +</man_syntax> +<man_description> +This method lists all available tables. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.db->sync title="synchronizes the database"> +<man_syntax> +void sync();<br> +</man_syntax> +<man_description> +This method synchronizes the database on disk. Yabu stores some information +about the database in memory for performance reasons. Syncing is recommended +when one wants the information on disk to be updated with the current +information in memory. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.db->purge title="deletes the database"> +<man_syntax> +void purge();<br> +</man_syntax> +<man_description> +This method deletes the whole database and all database files stored on disk. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.table->set title="stores a record in the table"> +<man_syntax> +mixed set(string key, mixed data);<br> +</man_syntax> +<man_description> +This method stores the contents of <i>data</i> as a record with the name +<i>key</i>. If a record with that name already exists, it will be +replaced. Records can only be added to the database in write mode. +</man_description> +</method> +<hr noshade size=1> + +<method name=Yabu.table->`[]= title="stores a record in the table"> +<man_syntax> +mixed `[]=(string key, mixed data);<br> +</man_syntax> +<man_description> +Synonymous with <link to=Yabu.table.set>set</link>. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.table->get title="fetch a record in the table"> +<man_syntax> +mixed get(string key);<br> +</man_syntax> +<man_description> +This method fetches the data associated with the record name +<i>key</i>. If a record does not exist, zero is returned. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.table->`[] title="fetch a record in the table"> +<man_syntax> +mixed `[](string key);<br> +</man_syntax> +<man_description> +Synonymous with <link to=Yabu.table.get>get</link>. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.table->list_keys title="lists the records in the table"> +<man_syntax> +array(string) list_keys();<br> +</man_syntax> +<man_description> +This method lists all record names in the table. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.table->delete title="deletes a record from a table"> +<man_syntax> +void delete(string <i>key</i>);<br> +</man_syntax> +<man_description> +This method deletes the record with the name <i>key</i>. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.table->purge title="deletes a table"> +<man_syntax> +void purge();<br> +</man_syntax> +<man_description> +This method deletes the whole table and the table files on disk. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.table->transaction title="begins a transaction"> +<man_syntax> +object(transaction) transaction();<br> +</man_syntax> +<man_description> +A transaction is a sequence of table commands that will be accepted in +whole, or not at all. If the program for some reason crashes or makes +an abrupt exit during a transaction, the transaction is cancelled.<p> +This method returns a transaction object. It can be used in the same +way as a table object. The difference is that in order to make the +changes take affect, <link to=Yabu.transaction.commit>commit</link> +must be issued. Before that, all changes will be local to the +transaction object. Also, if a record in a transaction is altered +before the transaction is commited, a conflict will arise upon commit. +A transaction can be cancelled using <link to=Yabu.transaction.rollback> +rollback</link>. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.transaction->commit title="commits a transaction"> +<man_syntax> +void commit();<br> +</man_syntax> +<man_description> +This method commits the changes made in a transaction. If a record affected +by the transaction is altered during the transaction, a conflict will +arise and an error is thrown. +</man_description> +</method> + +<hr noshade size=1> + +<method name=Yabu.transaction->rollback title="rollbacks a transaction"> +<man_syntax> +void rollback();<br> +</man_syntax> +<man_description> +This method cancels a transaction. All changes made in the transaction +are lost. +</man_description> +</method> + +</section> +</module> + +<hr noshade size=1> + <module name=MIME> <section title="MIME">