+++ /dev/null
-<html>
-<title>Web Object Compiler</title>
-<body>
-<h1>Web Object Compiler</h1>
-
-In a classic three-tier architecture (see below) there are two interface layers: data and communication.
-The Web Object Compiler (woc) helps implementing these three-tier architecture interfaces.<p>
-
-<table frame="1" border="1">
-<tr><td>Layer 3<td>Client Presentation Layer</tr>
-<tr><td rowspan="3"><i>Communication Interface</i><td><i><b>Server Abstraction Layer</b></i></tr>
- <tr><td><i>Network Protocol (eg. HTTP)</i></tr>
- <tr><td><i><b>Communication Abstraction Layer</b></i></tr>
-<tr><td>Layer 2<td>Server Business Logic</tr>
-<tr><td rowspan="2"><i>Data Interface</i><td><i><b>Database Abstraction Layer</b></i></tr>
- <tr><td><i>DB-Protocol (eg. LibMySQL)</i></tr>
-<tr><td>Layer 1<td>Database (eg. MySQL)</tr>
-</table>
-<i>Three Tier Architecture</i><p>
-
-<h2>Overall File Format</h2>
-
-Woc translates Web Object Language Files (*.wolf) into PHP or C++/Qt code. The wolf files are simple XML syntax.<p>
-
-Each wolf file must be enclosed in the <Wolf> and </Wolf> tags. The first few statements inside must describe the project itself:
-
-<pre>
-<Wolf>
- <Doc>Documentation...</Doc>
- <Project baseDir=".." wobDir="wob"/>
- <Version comm="0100" needcomm="0100" humanReadable="1.1 alpha" svnTarget="."/>
-</Wolf>
-</pre>
-
-Above the <Project> tag tells woc what the overall project directory is (relative to its current working directory) and where, relative to the baseDir, it will find all wolf files.<p>
-
-The <Doc> tag can be used to create project documentation. Each tag generates one paragraph. HTML can be embedded by escaping the "<" character as "&lt;".<p>
-
-The <Version> tag describes the communication protocol:
-
-<table frame="1" border="1">
-<tr><td><b>Attribute</b></td><td><b>Description</b></td></tr>
-<tr><td>comm</td><td>the communication protocol described by this wolf file</td></tr>
-<tr><td>needcomm</td><td>the minimum communication protocol this wolf file is compatible with (attention: the processor uses ASCII string comparison, not int comparison)</td></tr>
-<tr><td>humanReadable</td><td>the version number shown to the user</td></tr>
-<tr><td>svnTarget</td><td>if given: woc will call SVN to find out which repository revision was used</td></tr>
-<tr><td>svnExe</td><td>executable to call for subversion (default: svn)</td></tr>
-</table><p>
-
-The Include tag can be used to include other wolf files in the processing:
-<pre>
-<Include file="user.wolf"/>
-</pre><p>
-
-<h3>Attribute Types</h3>
-
-Boolean attributes in wolf files allow integers (0 is false, non-zere is true) or the explicit strings "yes", "true", "on" for true and "no", "false", "off" for false.<p>
-
-Integers can be entered in C notation - if it starts with 1 through 9 it is decimal, if it starts with 0 it is octal, if it starts with 0x it is hexadecimal. All integers are interpreted by woc - the generated source will always contain decimal numbers.<p>
-
-Woc is case-sensitive.
-
-<h2>Chosing Outputs</h2>
-
-Outputs should be declared after the basics have been declared, but before any tables, classes or transactions are declared.
-
-<pre>
-<QtClientOutput sourceDir="src" subDir="wob" priInclude="wob.pri"/>
-<PHPServerOutput sourceDir="www" subDir="inc/wob" extension=".php" clean="yes"/>
-<HtmlOutput sourceDir="doc" subDir="wob"/>
-</pre>
-
-The attribute "sourceDir" tells woc which directory (above baseDir) is the root source directory for each sub-project, the "subDir" attribute tells it which subdirectory below the sourceDir should be used for woc's generated output. The attribute "clean" tells woc to first delete all files from that sub-directory before starting the generator. Multiple generators of the same type can be used.<p>
-
-The QtClientOutput tag tells woc to create a generator for a Qt based client - the priInclude attribute tells woc which name it should give to the QMake include for its generated output.<p>
-
-The PHPServerOutput tag tells woc to create a generator for a PHP based server. The "extension" attribute tells woc which file extension to use for the generated files (default is .php). Woc will automatically create a "autoload" (plus extension) file that should be included from the main body of the PHP project to load the automatically generated classes.<p>
-
-The HtmlOutput tag tells woc where to generate API documentation.
-
-<h2>Database Abstraction Layer</h2>
-
-The Database Abstraction Layer is the servers lower bound towards the database. It is a simple translation of the database structure into usable PHP objects. The woc compiler generates one class per table.<p>
-
-One of the first statements is the manifest for the database schema:
-
-<pre>
-<DataBase instance="dbInst" schema="dbSchema" version="00.01"/>
-</pre>
-
-The attribute "instance" tells woc what variable name it should use for the database connection instance, likewise "schema" tells woc which variable represents the database schema (usually an instance of WobSchema, which is generated by woc). The "version" attribute tells woc which database schema version is described in this wolf file.<p>
-
-For each database table woc needs a description of that table:
-
-<pre>
-<Table name="ticket" backup="yes" base="BarcodeTable">
- <Column name="ticketid" type="string:32" primarykey="yes"/>
- <Column name="eventid" type="int32" foreignkey="event:eventid"/>
- <Column name="price" type="int32" notnull="yes"/>
- <Column name="status" type="enum32" notnull="yes">
- <Value name="Reserved" value="0x301"/> <!--dec: 769-->
- <Value name="Cancelled" value="0x4"/> <!--dec: 4-->
- <Value name="MaskUsable" value="0x300"/> <!--dec: 768-->
- </Column>
- <Column name="orderid" type="int32" foreignkey="order:orderid" notnull="yes"/>
-</Table>
-</pre>
-
-Table attributes:
-<table frame="1" border="1">
-<tr><td><b>Attribute</b></td><td><b>Description</b></td></tr>
-<tr><td>name</td><td>the name of the table, the generated class will be <tt>Wt<i>tablename</i></tt></td></tr>
-<tr><td>backup</td><td>bool, contains whether the table is in the backup routine (default: false)</td></tr>
-<tr><td>base</td><td>optional, contains the class that this tables class is derived from, the base class must be derived from WobTable (default is to derive from WobTable directly)</td></tr>
-</table><p>
-
-The Table tag can have Doc subtags to embed documentation.<p>
-
-Column attributes:
-<table frame="1" border="1">
-<tr><td><b>Attribute</b></td><td><b>Description</b></td></tr>
-<tr><td>name</td><td>the name of the column in the database</td></tr>
-<tr><td>type</td><td>the type of the column, this must be a woc type which is then translated into SQL by woc</td></tr>
-<tr><td>notnull, null</td><td>bool, marks the column to (not) allow NULL values, only one of the two attributes is allowed, currently the default is to allow NULL, but this may change in the future</td></tr>
-<tr><td>foreignkey</td><td>declares a reference to a foreign key column, the syntax is "foreigntablename:column" - the table that is referenced must be declared before the current one</td></tr>
-<tr><td>unique</td><td>bool, declares the column UNIQUE</td></tr>
-<tr><td>primarykey</td><td>bool, tells woc that this column is part of the primary key (multiple columns may be part of the primary key)</td></tr>
-<tr><td>default</td><td>declares a default value for the column (currently defaults for enums must be given as integer)</td></tr>
-</table><p>
-
-Column Types:
-<table frame="1" border="1">
-<tr><td><b>Attribute</b></td><td><b>Description</b></td></tr>
-<tr><td>string:<i>int</i>, string</td><td>a string column (SQL: VARCHAR), if the :int is given the column will have that maximum length assigned, if it is not given the database maximum is used; most databases support VARCHARs up to 255 characters</td></tr>
-<tr><td>int32, int64</td><td>a 32-bit/64-bit integer type</td></tr>
-<tr><td>enum, enum32, enum64</td><td>a 32bit/64bit (enum=enum32) integer interpreted as enumeration, the column must contain "Value" tags to declare the valid values</td></tr>
-<tr><td>bool</td><td>a boolean column (the SQL representation may vary per database system)</td></tr>
-<tr><td>seq32, seq64</td><td>a 32bit/64bit integer that counts up automatically (ie. that has a sequence attached to it) - this is usually only used for primary keys</td></tr>
-<tr><td>text</td><td>a large text field</td></tr>
-<tr><td>blob</td><td>binary large object</td></tr>
-</table><p>
-
-All names in table descriptions must follow a very strict syntax in order to be compatible with as many database systems as possible. Woc allows names that start with letters and contain only letters, underscored and digits.<p>
-
-The Value tags for enum types function similar to enums in C++. If a value attribute is given that value is assigned to the enum symbol, if no value is given the previous one is increased by one (the first value is 0).<p>
-
-Columns can be documented by adding the description directly to the Column tag or by embedding it with a Doc tag inside the Column tag. Enum values can be documented by embedding the description between <Value> and </Value>.<p>
-
-<h2>Communication Abstraction Layer</h2>
-
-The Communication Abstraction Layer is the servers upper bound towards the client. It hides the complexities of serializing data onto the network transport protocol by providing communication classes that do this automatically. The configuration of this layer is split into two major components: communication classes and transactions. While the communication classes describe what data can be transported over the connection, the transactions describe what operations can be performed.<p>
-
-<h3>Communication Classes</h3>
-
-An example class can be seen here:
-
-<pre>
-<Class name="Ticket">
- <Enum name="TicketState" refColumn="ticket:status"/>
- <Property name="ticketid" type="astring" id="yes"/>
- <Property name="eventid" type="int"/>
- <Property name="price" type="int"/>
- <Property name="status" type="TicketState"/>
- <Property name="orderid" type="int"/>
-
- <ToXml name="inOrder">ticketid eventid price status</ToXml>
- <ToXml name="Full">ticketid eventid price status orderid</ToXml>
-
- <Mapping table="ticket">
- <Map column="ticketid"/>
- <Map column="price"/>
- <Map column="eventid"/>
- <Map column="status"/>
- <Map column="orderid" property="orderid"/>
- </Mapping>
-</Class>
-</pre>
-
-The "name" attribute of the Class tag gives the communication class a name by which it can be referenced. The language converters will prefix it with "WO" to make it unique and postfix it with "Abstract" if the class is declared abstract - in this case the user must derive the non-abstract class to make it usable.<p>
-
-Class attributes:
-<table frame="1" border="1">
-<tr><td><b>Attribute</b></td><td><b>Description</b></td></tr>
-<tr><td>name</td><td>the name of the class</td></tr>
-<tr><td>abstract</td><td>(optional) marks the class abstract</td></tr>
-</table><p>
-
-The Enum tag defines a local enumeration. In most cases they will simply reference an enumeration that has already been defined in a database table with a refColumn attribute (syntax: <tt><i>table</i>:<i>column</i></tt>), but it may also locally define its values by using the same Value tags used for database enums.<p>
-
-The Property tag defines a property of the class that can be read and written to:
-<table frame="1" border="1">
-<tr><td><b>Attribute</b></td><td><b>Description</b></td></tr>
-<tr><td>name</td><td>the name of the property</td></tr>
-<tr><td>abstract</td><td>(optional) marks the property abstract - this automatically makes the class abstract and the user has to overwrite the getter and setter methods</td></tr>
-<tr><td>id</td><td>(optional, default=no) marks the property to identify the instance in a cache</td></tr>
-<tr><td>type</td><td>(mandatory) defines the type of the property, see below</td></tr>
-</table><p>
-
-Property types:
-<table frame="1" border="1">
-<tr><td><b>Type</b></td><td><b>Description</b></td></tr>
-<tr><td>int</td><td>an integer - it is at least a 32bit signed type; it is transported as attribute</td></tr>
-<tr><td>astring</td><td>a string that can be safely stored in a XML attribute</td></tr>
-<tr><td>string</td><td>a string that is transported as element and can reach any length</td></tr>
-<tr><td><i>EnumName</i></td>the name of an enum defined in the same class is possible, local storage is as integer, transport is as string equalling the symbolic name of the value in an attribute</td></tr>
-<tr><td><i>ClassName</i></td><td>the name of a defined class makes the property an instance of that class; they are transported as sub-elements of this class</td></tr>
-<tr><td>List:*</td><td>prefixing the type with "List:" makes the property a list of that type - any of the above types can be made into lists; on transport list values are always serialized as elements</td></tr>
-</table><p>
-
-The Mapping tag can be used to provide a shortcut cast between a database table type and the communication class type. This is provided for the trivial case in which no transformations between the database query result and the transport data is necessary. If the property attribute is ommitted a property with the same name as the listed column is looked for.<p>
-
-The ToXml tag provides valid serializations. Each serialization must have a name - the language converters prefix them with "toString" and "toXml" to build a method names. The text of the tag simply lists all properties that should be contained in the serialization separated by spaces. Properties that are communication classes (or lists thereof) must also list the proper serialization function of that communication class, eg. Order serialized thus:
-
-<pre>
-<ToXml name="Full">orderid customerid seller amountpaid state amountdue tickets/inOrder vouchers/inOrder</ToXml>
-</pre>
-
-Above the property "tickets" is a list of Ticket and "inOrder" is a serialization defined above for Ticket.<p>
-
-Classes can be documented by adding Doc subtags. Properties can be documented by adding the description directly into the Property tag. Enum values can be documented by adding the description directly into the Value tag.
-
-
-<h3>Transactions</h3>
-
-<pre>
-<Transaction name="GetTicket">
- <Input>
- <Var name="ticketid" type="astring"/>
- <Call lang="php" method="getTicketFunction"/>
- </Input>
- <Output>
- <Var name="ticket" type="Ticket/Full"/>
- </Output>
-</Transaction>
-</pre>
-
-Each transaction must have a name that identifies it. This name is used in the wire protocol to correctly identify the currently requested transaction.
-
-Transaction attributes:
-<table frame="1" border="1">
-<tr><td><b>Attribute</b></td><td><b>Description</b></td></tr>
-<tr><td>name</td><td>the name of the transaction</td></tr>
-<tr><td>mode</td><td>(optional, default=checked) can be used to require less restrictive privileges, see below for values</td></tr>
-</table><p>
-
-Transaction modes:
-<table frame="1" border="1">
-<tr><td><b>Mode</b></td><td><b>Description</b></td></tr>
-<tr><td>checked</td><td>the default mode: the session must be authenticated and the user must have the privilege to execute this query</td></tr>
-<tr><td>auth</td><td>the session must be authenticated, but no special privilege is required; this can for example be used for the logout function or a function query information about the session itself</td></tr>
-<tr><td>open</td><td>no session is necessary for this to work; usually this is only done for login</tr></tr>
-</table><p>
-
-Input defines the input parameters (Var tag) of the transaction (ie. what is sent to the server) and what function is called (Call tag) once the transaction has been checked and authenticated.<p>
-
-Output defines the data (Var tag) sent back to the client.<p>
-
-Var attributes:
-<table frame="1" border="1">
-<tr><td><b>Attribute</b></td><td><b>Description</b></td></tr>
-<tr><td>name</td><td>the name of the variable</td></tr>
-<tr><td>type</td><td>type of the attribute; all types allowed for class properties (except enums) are allowed here</td></tr>
-</table><p>
-
-Call attributes:
-<table frame="1" border="1">
-<tr><td><b>Attribute</b></td><td><b>Description</b></td></tr>
-<tr><td>lang</td><td>the language binding this refers to (currently only "php")</td></tr>
-<tr><td>method</td><td>the function to call - it must take exactly one argument: the transaction object</td></tr>
-</table><p>
-
-Transactions are represented as classes. On the client side they are used to execute the query and to represent the result. On the server side they internally verify the input and authenticate the transaction and are then used to take and encode the output or possible error conditions.<p>
-
-Transactions can be documented by adding Doc tags. Inputs and Outputs can be documented by adding the description directly into the Var tags.
-
-
-<h2>Server Abstraction Layer</h2>
-
-This is the clients lower bound towards the server. It takes care of basic tasks like authentication, communication, serializing and deserializing data and keeping a cache of some important objects.
-
-
-</html>
\ No newline at end of file
+++ /dev/null
-//
-// C++ Implementation: domquery
-//
-// Description:
-//
-//
-// Author: Konrad Rosenbaum <konrad@silmor.de>, (C) 2009
-//
-// Copyright: See README/COPYING files that come with this distribution
-//
-//
-
-#include "domquery.h"
-
-
-MDomQuery::MDomQuery(const QDomDocument&start,QString path)
-{
- construct(start.documentElement(),path);
-}
-
-MDomQuery::MDomQuery(const QDomElement&start,QString path)
-{
- construct(start,path);
-}
-
-void MDomQuery::construct(const QDomElement&start,QString path)
-{
- //split query
- QStringList ql=path.split("/",QString::SkipEmptyParts);
- //determine start mode and initialize list
- MDomNodeList ndlst;
- if(path.startsWith("//")){
- QDomDocument doc=start.ownerDocument();
- if(ql.size()<1){
- qDebug("MDomQuery: // query must not be empty!");
- return;
- }
- if(ql[0]=="*" || ql[0]=="@*"){
- qDebug("MDomQuery: // query must not start with wildcard * or @*.");
- return;
- }
- if(ql[0].startsWith("@")){
- qDebug("MDomQuery: cannot start with attributes in a // query.");
- return;
- }else{
- ndlst=doc.elementsByTagName(ql[0]);
- ql.removeFirst();
- }
- }else
- if(path.startsWith("/")){
- QDomElement root=start.ownerDocument().documentElement();
- if(ql.size()<1){
- //hmm, guess what the user really wanted (assume "/ *" )
- m_result<<root;
- return;
- }
- if(ql[0].startsWith("@")){
- qDebug("MDomQuery: cannot start with attributes in a / query.");
- return;
- }
- if(ql[0]=="*"){
- //any root
- ndlst<<root;
- }else{
- //specific root
- if(root.tagName()==ql[0])ndlst<<root;
- }
- //remove root from query, then go on below
- ql.removeFirst();
- }else{
- //query starts at current element
- ndlst<<start;
- }
- //iteratively go through path and eliminate non-matches
- while(ql.size()>0){
- MDomNodeList lst2;
- //parse pattern
- if(ql[0].startsWith("@")){
- //attribute handling...
- if(ql.size()>1){
- qDebug("MDomQuery: cannot sub-parse attributes.");
- return;
- }
- if(ql[0]=="@*"){
- //get all attributes of all current elements
- for(int i=0;i<ndlst.size();i++)
- lst2+=ndlst[i].toElement().attributes();
- }else{
- //get specific attributes
- for(int i=0;i<ndlst.size();i++){
- QDomElement el=ndlst[i].toElement();
- QString nm=ql[0].mid(1);
- if(el.hasAttribute(nm))
- lst2<<el.attributeNode(nm);
- }
- }
- }else{
- //element handling
- QString nm=ql[0];
- if(nm=="*"){
- //copy any element
- for(int i=0;i<ndlst.size();i++){
- QDomNodeList nl=ndlst[i].childNodes();
- for(int j=0;j<nl.size();j++){
- QDomElement el=nl.at(j).toElement();
- if(!el.isNull())
- lst2<<el;
- }
- }
- }else{
- //search for specific elements
- for(int i=0;i<ndlst.size();i++)
- lst2+=ndlst[i].toElement().elementsByTagName(nm);
- }
- }
- //next recursion:
- ql.removeFirst();
- ndlst=lst2;
- }
- m_result=ndlst;
-}
-
-QString MDomQuery::toString()const
-{
- QString ret;
- for(int i=0;i<m_result.size();i++){
- if(ret!="")ret+=" ";
- if(m_result[i].isElement())
- ret+=m_result[i].toElement().text();
- else
- ret+=m_result[i].nodeValue();
- }
- return ret;
-}
-
-QStringList MDomQuery::toStringList()const
-{
- QStringList ret;
- for(int i=0;i<m_result.size();i++)
- if(m_result[i].isElement())
- ret<<m_result[i].toElement().text();
- else
- ret<<m_result[i].nodeValue();
- return ret;
-}
+++ /dev/null
-//
-// C++ Interface: domquery
-//
-// Description:
-//
-//
-// Author: Konrad Rosenbaum <konrad@silmor.de>, (C) 2009
-//
-// Copyright: See README/COPYING files that come with this distribution
-//
-//
-
-#ifndef MAGICSMOKE_DOMQUERY_H
-#define MAGICSMOKE_DOMQUERY_H
-
-
-#include <QDomElement>
-#include <QList>
-#include <QStringList>
-
-/**Helper class: more flexible version of QDomNodeList*/
-class MDomNodeList:public QList<QDomNode>
-{
- public:
- MDomNodeList(){}
- MDomNodeList(const MDomNodeList&l):QList<QDomNode>(l){}
- MDomNodeList(const QList<QDomNode>&l):QList<QDomNode>(l){}
- MDomNodeList(const QDomNodeList&l){for(int i=0;i<l.size();i++)append(l.at(i));}
- MDomNodeList(const QDomNamedNodeMap&l){for(int i=0;i<l.size();i++)append(l.item(i));}
-
- MDomNodeList& operator+=(const QDomNodeList&l)
- {for(int i=0;i<l.size();i++)append(l.at(i));return *this;}
-
- MDomNodeList& operator+=(const QDomNamedNodeMap&l)
- {for(int i=0;i<l.size();i++)append(l.item(i));return *this;}
-};
-
-
-/**DOM Query Class
-
-It uses a simplified version of the XPath syntax:
-
-Namespaces/Prefixes are ignored. It is recommended to use patternist for cases in which namespaces matter.
-
-The search path uses slash "/" to separate elements, the last item in the search path may start with "@" to match an attribute instead of an element. The special names "*" and "@*" may be used to match any element or attribute. If the search path starts with a slash "/", the search starts at the document root irrespective of what element was fed to the query object (the first item matched against the root element). If the search path starts with a double slash "//" the search considers all positions in the document as valid starting points (using all elements that match the first item to start the search, the first item must not be "*" in that case). If there is no slash at the start of the path the search begins exactly at the supplied element (the first item matched against child elements of the supplied element). Queries that start with a slash must search an element at the first position.
-
-When casting to QString or QStringList the query object uses the method text() of the QDomElement to generate the content of the element. For attributes it simply returns the value.
-
-Examples:
-<table>
-<tr><td>mouse</td><td>return all child elements of the current element that are called "mouse"</td></tr>
-<tr><td>\@mouse</td><td>return all attribute nodes of the current element that are called "mouse"</td></tr>
-<tr><td>*</td><td>returns all child elements of the current element</td></tr>
-<tr><td>\@*</td><td>returns all attributes of the current element</td></tr>
-<tr><td>/<!-- -->*</td><td>returns the root element of the document irrespective of name</td></tr>
-<tr><td>/mouse</td><td>returns the root element of the document if it has the tag name "mouse" or an empty list</td></tr>
-<tr><td>/<!-- -->*<!-- -->/mouse</td><td>returns all elements directly below the root element that are called "mouse"</td></tr>
-<tr><td>//mouse</td><td>returns all elements in the document that are called "mouse"</td></tr>
-<tr><td>mouse/\@trap/door</td><td>syntax error, attributes cannot have children</td></tr>
-</table>
-*/
-class MDomQuery
-{
- public:
- /**creates the query object and executes the query*/
- MDomQuery(const QDomElement&start,QString path);
-
- /**creates the query object and executes the query; this is equivalent to calling the query with the document element as starting point*/
- MDomQuery(const QDomDocument&start,QString path);
-
- /**returns the search result as a single string, if there were multiple matches, they are separated by spaces*/
- QString toString()const;
- /**returns the search result as a list of strings, one string element per match*/
- QStringList toStringList()const;
- /**returns the result as a list of DOM nodes*/
- MDomNodeList toNodeList()const{return m_result;}
-
- /**cast to QString: see toString()*/
- operator QString()const{return toString();}
- /**cast to QStringList: see toStringList()*/
- operator QStringList()const{return toStringList();}
- /**cast to DOM node list: see toNodeList()*/
- operator MDomNodeList()const{return m_result;}
- private:
- MDomNodeList m_result;
-
- //helper for constructor
- void construct(const QDomElement&start,QString path);
-};
-
-#endif
projects / konrad/smoke.git / commitdiff