Wxml
Go to: Introduction - Atom Attributes - Column Attributes - Data Types - Dictionaries - Embedding code -  Output Modes
Wxml is the tool that generates code from your xml description of data models.
A typical wxml input file looks like this:

<object name="NAME" table="TABLENAME" namespace="NSPC">
    <col name="CNAME" type="CTYPE" [attributes] />
        (more columns here)
</object>


That is, you define an object with a NAME and TABLE attributes and then an arbitrary number of rows with attributes.



Atom attributes

Attribute
 Type
 Description
*name 
string
 The name of the C# class mapped to this table.
*table
string
 The name of the table the C# class is mapped to.
NAMESPACE string
 The namespace the C# class will be placed under. If not specified, defaults to 'Womb.Atoms'





* mandatory field

                     
Column attributes

Attribute
 Type
 Description
*name
string
 The name of the column. An identically named property will be created in the C# class.
*type
 string
 Type of column. See types table below.
blurb
 string
 Human-readable name of the column. Womb.Gtk uses this attribute to show names of columns in widgets.
dict
 string
 Indicates this is a dict-bound column, ie it is an integer column that can only take a range of values speciified in another table (called the "dictionary table"). The value of the attribute is the name of the table containing the values. See below for details on how to create and use dictionaries with Wxml.
notnull boolean
 Indicates the value cannot be null. Setting the value to null will throw an exception. A NOT NULL constraint will be generated in the object's SQL definition.
indexed boolean
 If true, an index will be created for this column in the database to optimize lookups. Use indexes for columns you use as search criteria often, ie your primary keys.
default string
 The value of this attribute will be copied verbatim as the column's default value in the SQL definition of the column. It must be properly escaped and can be anything the server understands (eg. current_date, 7, 'nothing').
hidden boolean
 Indicates this is a hidden column, ie one not to be shown in reports. This attribute is used by widgets in Womb.Gtk to determine whether to show particular columns or not.
sql string
 The value of this attribute will be copied verbatim at the end of the SQL declaration of column. It must be properly escaped and can be anything the server understands. Use this to specify extra constraints or funky SQL expressions.


* mandatory field
                     

Data types
               
Wxml type
 Description
 C# type
int
Signed 32-bit integer
 Nullable<Int32>
bigint Signed 64-bit integer
 Nullable<Int64>
serial  
Auto-incrementing 32-bit signed integer Nullable<Int32>
bigserial Auto-incrementing 64-bit signed integer
 Nullable<Int64>
boolean Boolean (true/false) value Nullable<Boolean>
string
UTF-8 encoded text
 String
date  
Date and Time value Nullable<DateTime>
double
Double precision Nullable<Double>
numeric 
Decimal value Nullable<Decimal>
blob
 Large Object oid
 Nullable<Int32>



Dictionaries


Dictionaries are very useful for limiting the range of values a column can take, and mapping those values to symbolic names. This saves disk space and memory in the server and prevents bogus values from being inserted into the table. It also makes the application easier to use by users, since it maps numeric values to more meaningful strings.

Example dictionary -- type of fruit:

    Value    Symbolic name
    ------  -------------
        1    Apple
        2    Orange
        3    Banana
        4    Lemon

Dictionary tables are defined using XML like table data models, but are much more limited:

<dict name="FruitType" table="DICTFRUIT" namespace="HelloWomb">
    <row name="Apple"  value="1"/>
    <row name="Orange" value="2"/>
    <row name="Banana" value="3"/>
    <row name="Lemon"  value="4"/>
</dict>



We can now generate the dictionary table with Wxml:

    $ Wxml --sql FruitType.xml > FruitType.sql
    $ psql HelloWomb < FruitType.sql

Now that the table is stored in the database, we can tag our atoms as users of that dictionary:

<object name="FruitTree" name="trees">
    <col name="tname" type="string"/>
    <col name="tfruit" type="int" dict="DICTFRUIT"/>
</object>



Now :WOMB: knows the "tfruit" column is bound to the fruit dictionary, so doing something like:

    FruitTree tree = new FruitTree (db);
    tree.tfruit = 6; // ERROR -- Throws

will throw an exception, because "6" is not in the dictionary table. To prevent this from happening, Wxml can generate an enum mapped to the dictionary:

    $ Wxml.exe --body FruitType.xml > FruitType.cs

Now, if you include FruitType.cs in your application, you can use the symbolic names when assigning to the tfruit column:

    FruitTree tree = new FruitTree (db);
    tree.tfruit    = FruitType.Banana;

Womb.Gtk also knows about dict-bound columns and will automatically show a combo box for selecting the values in the data entry widgets (eg. Womb.Gtk.AtomTab, Womb.Gtk.AtomEditor).

Dictionary-bound columns can only be of type "int". Furthermore, you cannot use a pre-existing table as a dictionary: you must create it specifically using the output of Wxml.
Multiple tables can consume the same dictionary efficiently: dictionaries are cached on a per-session basis in the Womb.DB class.           


Embedding code


You can have wxml include  your own code when emitting C# code for your data model. For example, you may want to include some custom method in the generated atom, or override some of the Womb.Atom methods to do specific things.
Arbitrary code is attached to the atom by using the <body> tag in the xml file.

<object name="MyFooRow" table="foo" namespace="Baz">
    <col name="firstcol" type="int" />
    <col name="foostamp" type="date" default="current_date"/>

    <body>
        // Override atom Write () method to log write operation before writing to database
        public override void Write ()
        {
             FooLog.Log ("Writing atom!!!!!");
             base.Write ();
          }
    </body>

    <body>
      // Provide a custom ToString () method
      public override string ToString ()
      {
           return ((int) firstcol).ToString () + "." + ((DateTime) foostamp).ToString ();
      }
    </body>
</object>








Output modes



Wxml can generate different kinds of output for every input xml file.

  • C# SOURCE OUTPUT (-cs, --body):

    • For OBJECT xml models:
      Generates C# source code defining a class (whose name corresponds to the 'name' attribute of the object definition, namespaced under the 'namespace' attribute). You can then include this file into your project to manipulate data in the table the atom is mapped to.
      This mode takes a single xml file as input and writes output to stdout or file specified by the -o:FILE flag.

    • For DICT xml models:
      Generates C# source code defining an enum (whose name corresponds
      to the 'name' attribute of the dict definition, namespaced under
      the 'namespace' attribute). You can then include this file into
      your project to set values in atoms that use this dictionary using
      the dictionary's symbolic names.          
      This mode takes a single xml file as input and writes output to stdout or file specified by the -o:FILE flag.

  • ASSEMBLY OUTPUT (-asm, --assembly)

    • Generates C# source code for all xml files passed as input and compiles them all together into a ready-to-use assembly (specify name of output assembly with -o:FILE flag). You can combine both object and dict xml definition files in this mode.
      The generated assembly references mscorlib and Womb.dll, you can add extra references with the -r:LIB flag. Additionally, you can include extra C# source files to the compilation with the -i:FILE flag. You can also pass custom compiler flags via the -f:"FLAGS" option (must be quoted if you pass multiple options).
      This mode takes multiple xml files as input and writes output to a dll file specified by the -o:FILE flag.

  • SQL OUTPUT (-sql, --sql)

    • For OBJECT xml models:
      Generates PostgreSQL commands to create a table as defined by the xml model. The resulting script must be run in the database to create the storage.
      This mode takes a single xml file as input and writes output to stdout or file specified by the -o:FILE flag.

    • For DICT xml models:
      Generates PostgreSQL commands to create a dictionary table as defined by the xml model. The resulting script must be run in the database to create the storage and insert data and use
      any dictbound atoms properly.
      This mode takes a single xml file as input and writes output to stdout or file specified by the -o:FILE flag.
Go to: Introduction - Atom Attributes - Column Attributes - Data Types - Dictionaries - Embedding code -  Output Modes