<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<TITLE>XML DB Interpreter Documentation</TITLE>
<LINK REL="STYLESHEET" MEDIA="screen" HREF="documentation.css" TYPE="text/css">
</HEAD>
<BODY>
<H1 CLASS="center background-blue border">XML DB Interpreter</H1>
<DIV CLASS="background-lblue border">
<H2>Contents</H2>
<TABLE BORDER="0">
<TR>
<TD>
<UL>
<LI>Introduction</LI>
<LI>Usage</LI>
<LI>Function reference</LI>
<LI>License</LI>
</UL>
</TD>
</TR>
</TABLE>
</DIV>
<DIV CLASS="nocenter padding background-lblue border">
<H2>Introduction</H2>
<P>
In an effort to make the creation and maintenance of databases and their associated
tables easier, I have written this. It is an database schema interpreter which uses
XML to store the database structure.
</P>
</DIV>
<DIV CLASS="nocenter padding background-lblue border">
<H2>Usage</H2>
<P>
So far the interpreter can read the schema file, take the data, convert it to SQL and
execute it. An example schema is held in the file example.schema.xml. A listing of the
tags that can and will need to be used follows.
</P>
<P STYLE="padding-left: 20px">
<CODE CLASS="bold"><database></CODE><BR>
This is the tag to start a database. You can have multiple databases per schema
file, but it makes more sense to have one database per file. Attributes are:<BR>
</P>
<UL STYLE="padding-left: 20px">
<LI><CODE>name</CODE></LI>
<LI><CODE>if_not_exists</CODE></LI>
</UL>
<P STYLE="padding-left: 20px">
The <CODE>name</CODE> is self explanatory. The <CODE>if_not_exists</CODE> attribute
should be used and set to <I>yes</I> if you want the <CODE>IF NOT EXISTS</CODE>
keywords added to the SQL query.
</P>
<P STYLE="padding-left: 20px">
<CODE CLASS="bold"><table></CODE><BR>
This is the tag to start a table. You can have multiple tables per database.
Attributes are:<BR>
</P>
<UL STYLE="padding-left: 20px">
<LI><CODE>name</CODE></LI>
<LI><CODE>if_not_exists</CODE></LI>
<LI><CODE>temporary</CODE></LI>
<LI><CODE>options</CODE></LI>
</UL>
<P STYLE="padding-left: 20px">
The <CODE>name</CODE> is self explanatory. The <CODE>if_not_exists</CODE> attribute
should be used and set to <I>yes</I> if you want the <CODE>IF NOT EXISTS</CODE>
keywords added to the SQL query. The <CODE>temporary</CODE> attribute should be used
and set to <I>yes</I>if the table should have the <CODE>TEMPORARY</CODE> keyword added
to the definition. The <CODE>options</CODE> attribute should be used for any table options
you want specified and the contents will be added directly to the SQL query.
</P>
<P STYLE="padding-left: 20px">
<CODE CLASS="bold"><field></CODE><BR>
This is the tag to specify a field in the current table.
Attributes are:<BR>
</P>
<UL STYLE="padding-left: 20px">
<LI><CODE>name</CODE></LI>
<LI><CODE>type</CODE></LI>
<LI><CODE>size</CODE></LI>
<LI><CODE>null</CODE></LI>
<LI><CODE>default</CODE></LI>
<LI><CODE>extra</CODE></LI>
</UL>
<P STYLE="padding-left: 20px">
The <CODE>name, type, size</CODE> and <CODE>default</CODE> are self explanatory. All must be valid for the database
software you're using of course. <CODE>null</CODE> is for specifying the column to be <CODE>NOT NULL</CODE>.
it should be set to <I>no</I>. If this tag is not specified then the column will be set to <CODE>NULL</CODE>.
The <CODE>extra</CODE> attribute is for adding extra commands to the SQL query produced. The code is
appended to the end. An example usage of this attribute is the <CODE>AUTO_INCREMENT</CODE> keyword.
</P>
<P STYLE="padding-left: 20px">
<CODE CLASS="bold"><key></CODE><BR>
This is the tag to specify an index in the current table.
Attributes are:<BR>
</P>
<UL STYLE="padding-left: 20px">
<LI><CODE>type</CODE></LI>
<LI><CODE>field</CODE></LI>
<LI><CODE>name</CODE></LI>
</UL>
<P STYLE="padding-left: 20px">
The <CODE>type</CODE> specifies the type of key. This can be <I>primary</I>, which will specify a
primary key, <I>unique</I> which will specify a unique index and also <I>index</I>, which will
specify a normal index. The <CODE>field</CODE> specifies which field(s) to apply the index to.
The <CODE>name</CODE> attribute simply specifies the name of the index.
</P>
</DIV>
<DIV CLASS="nocenter padding background-lblue border">
<H2>Examples</H2>
<P>
There are two example files to help you utilise the script. One is an example schema that contains
most of the tags and attributes, and the other is an example script that uses the class to parse
the example schema and execute the SQL generated.
</P>
</DIV>
<DIV CLASS="nocenter padding background-lblue border">
<H2>Function Reference</H2>
<P>
<CODE><I>void</I> xml_dbas(<I>void</I>);</CODE><BR>
Constructor function.
</P>
<P>
<CODE><I>array</I> get_sql(<I>void</I>);</CODE><BR>
Accessor function to return the raw SQL statements.
</P>
<P>
<CODE><I>array</I> get_sql_errors(<I>void</I>);</CODE><BR>
Accessor function to return any SQL errors.
</P>
<P>
<CODE><I>string</I> get_data(<I>void</I>);</CODE><BR>
Accessor function to return the XML schema.
</P>
<P>
<CODE><I>void</I> start_element(<I>int</I> parser, <I>string</I> name, <I>array</I> attributes);</CODE><BR>
Handler for the opening tags (eg. <database>).
</P>
<P>
<CODE><I>void</I> end_element(<I>int</I> parser, <I>string</I> name);</CODE><BR>
Handler for the closing tags (eg. </database>).
</P>
<P>
<CODE><I>void</I> parse_schema(<I>void</I>);</CODE><BR>
Function to set the schema. Can be a file, in which case the data should be the filename,
and is_file should be set to TRUE, or it can be the data itself, in which case data should
contain the schema and is_file should be set to FALSE.
</P>
<P>
<CODE><I>void</I> parse_schema(<I>void</I>);</CODE><BR>
This function parses the schema. Results are stored in <I>$obj->sql</I>.
</P>
<P>
<CODE><I>void</I> create_dbas(<I>string</I> host, <I>string</I> username, <I>string</I> password [,<I>string</I> database]);</CODE><BR>
This function executes the SQL statements. If there are any errors they will be stored in
<I>$obj->sql_errors</I>. The host, username and password arguments are for the database server
to which the script will connect. The optional database argument is for schemas that don't create
new databases, merely new tables. If you wish to alter the database type that this class uses (eg
Postgres instead of MySQL), then this is the function to alter. Other minor changes may also be
warranted in the schema, but nothing particularly drastic.
</P>
</DIV>
<DIV CLASS="nocenter padding background-lblue border">
<H2>License</H2>
<P>
Postcard-ware. If you use this utility then I'd appreciate a postcard from ya. :)<BR>
Otherwise, it's free, be grateful, don't whinge, and don't sue me if it screws your database.
</P>
<P CLASS="center" ALIGN="CENTER">
<A HREF="http://validator.w3.org/check/referer">
<IMG SRC="http://validator.w3.org/images/vh40" BORDER="0" ALT="Valid HTML 4.0!" HEIGHT="31" WIDTH="88">
</A>
<A HREF="http://jigsaw.w3.org/css-validator/">
<IMG SRC="http://jigsaw.w3.org/css-validator/images/vcss.gif" BORDER="0" ALT="Valid CSS 1.0">
</A>
</P>
</DIV>
</BODY>
</HTML> |
Stumble It!
Bookmark in del.icio.us
Download
