diff options
Diffstat (limited to 'man/genxs.1')
| -rw-r--r-- | man/genxs.1 | 294 |
1 files changed, 294 insertions, 0 deletions
diff --git a/man/genxs.1 b/man/genxs.1 new file mode 100644 index 00000000000..26b6d6066b5 --- /dev/null +++ b/man/genxs.1 @@ -0,0 +1,294 @@ +.\" +.\" genxs manual page. +.\" (C) Lluis Sanchez Gual (lluis@ximian.com) +.\" +.TH genxs 1 +.SH NAME +genxs \- Mono's Xml Serializer Generator +.SH SYNOPSIS +.PP +.B genxs +configurationFile [destinationFolder] +.SH DESCRIPTION +.I genxs +is a tool for generating custom XML serialization writers and readers for +classes. +.PP +.I configurationFile +is configuration file which specifies several +information, such as the class for which to generate the reader and writer, the +name and namespace of the classes to generate, and a collection of hooks to +apply. By using hooks it is possible to customize the +behavior of the serializer without needing to modify the generated file, so you +can safely regenerate it if the source class is modified. +.PP +.I destinationFolder +specifies the folder where the files will be generated. +.PP +.B NOTE: +This tool only runs in the Mono runtime, since it uses some internal +classes not available in other runtimes. +.SH CONFIGURATION FILE FORMAT +The configuration file is an xml document based on the following grammar +("?" means optional, "*" 0 or more): +.PP +.nf + <configuration> + <serializer class="name" assembly="name"> * + <reader>name</reader> ? + <writer>name</writer> ? + <namespace>name</namespace> ? + <outFileName>name</outFileName> ? + <readerHooks> ? + <hook ...> * + </readerHooks> + <writerHooks> ? + <hook ...> * + </writerHooks> + </serializer> + </configuration> +.fi +.PP +A configuration file can have multiple "serializer" elements, each of which +specifies the class for which to generate a serializer together with several +generation options. The source class is specified in the following attributes: +.PP +.IP " *" 5 +.I class +: name of the class (including namespace). +.IP " *" 5 +.I assembly +: assembly name. It can include the complete path. +.PP +Generation options are specified in child elements: +.PP +.IP " *" 5 +.I reader +: name of the reader class. +.IP " *" 5 +.I writer +: name of the writer class. +.IP " *" 5 +.I namespace +: namespace of the reader and writer classes. +.IP " *" 5 +.I outFileName +: name of the generated file. +.IP " *" 5 +.I readerHooks +: a list of hooks to apply to the reader. +.IP " *" 5 +.I writerHooks +: a list of hooks to apply to the writer. +.SH SPECIFYING HOOKS +Using hooks you can customize the behavior of readers and writers. +A hook specification follows this grammar: +.PP +.nf + <hook type="name"> + <select> ? + <typeName>name</typeName> ? + <typeAttribute>name</typeAttribute> * + <typeMember>name</typeMember> ? + </select> + <replace>source code</replace> ? + <insertBefore>source code</insertBefore> ? + <insertAfter>source code</insertAfter> ? + </hook> +.fi +.PP +The "type" attribute specifies the context in which the hook is applied. It can +be one of the following: +.PP +.IP " *" 5 +.I attributes +: hook is applied where attributes are serialized/deserialized. +.IP " *" 5 +.I elements +: hook is applied where elements are serialized/deserialized. +.IP " *" 5 +.I unknownAttribute +: hook is applied where unknown attributes are processed. +.IP " *" 5 +.I unknownElement +: hook is applied where unknown elements are processed. +.IP " *" 5 +.I member +: hook is applied where a member is serialized/deserialized. +.IP " *" 5 +.I type +: hook is applied for the whole type. +.PP +The "select" element specifies the classes and members to which the hook has +to be added. It can contain the following elements: +.PP +.IP " *" 5 +.I typeName +: the class with that name will be selected (must include namespace) +.IP " *" 5 +.I typeAttribute +: all classes which have that attribute applied will be selected (specify the +full attribute class name, including namespace). Several attribute names can be +specified. +.IP " *" 5 +.I typeMember +: name of the class member for which the hook must be added. +.PP +The hook source code can be specified using any of the following elements: +.PP +.IP " *" 5 +.I replace +: the provided source code will replace all serialization/deserialization +operations in the hook context. +.IP " *" 5 +.I insertBefore +: the source code will be added before the hook context. +.IP " *" 5 +.I insertAfter +: the source code will be added after the hook context. +.PP +When writing the code for a hook you can use some special variables that are +defined during the code generation process. The variables are the following: +.PP +.IP " *" 5 +.I $TYPE: +name of the class being generated, without namespace. +.IP " *" 5 +.I $FULLTYPE: +full name of the class being generated, including namespace. +.IP " *" 5 +.I $OBJECT: +the object being serialized or deserialized. When using a replace +reader hook of type "type", the hook code must assign the deserialized object +to this variable. +.IP " *" 5 +-I $ELEMENT: +name of the element of the object being serialized/deserialized. +.IP " *" 5 +.I $NAMESPACE: +namespace of the element of the object being serialized/deserialized. +.IP " *" 5 +.I $MEMBER: +name of the member being serialized/deserialized. Only valid in the "member" +context. +.SH HOOK EXAMPLES +The following example adds a call to a Validate method after the deserialization +of any object: +.PP +.nf +<hook type="type"> + <insertAfter> + System.Xml.Schema.XmlSchema.Validate$TYPE ($OBJECT); + </insertAfter> +</hook> +.fi +.PP +This example specifies the code to be used to deserialize the XmlSchema class: +.PP +.nf +<hook type="type"> + <select> + <typeName>System.Xml.Schema.XmlSchema</typeName> + </select> + <replace> + $OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null); + </replace> +</hook> +.fi +.PP +That one specifies the code to be used to read XmlSchema instances: +.PP +.nf +<hook type="type"> + <select> + <typeName>System.Xml.Schema.XmlSchema</typeName> + </select> + <replace>$OBJECT.Write (Writer);</replace> +</hook> +.fi +.PP +With this two hooks the serializer will print some information when serializing +the class "MyClass": +.PP +.nf +<hook type="type"> + <select> + <typeName>MyNamespace.MyClass</typeName> + </select> + <insertBefore>Console.WriteLine ("Serializing MyClass");</replace> + <insertAfter>Console.WriteLine ("MyClass serialized");</insertAfter> +</hook> +<hook type="member"> + <select> + <typeName>MyNamespace.MyClass</typeName> + </select> + <insertAfter> + Console.WriteLine ("Serialized member $MEMBER"); + </insertAfter> +</hook> +.fi +.PP +This hook writes an additional element for all types that have the custom +attribute "MyAttribute": +.PP +.nf +<hook type="elements"> + <select> + <typeAttribute>MyNamespace.MyAttribute</typeAttribute> + </select> + <insertAfter> + Writer.WriteStartElement ("privateData"); + Writer.WriteString ($OBJECT.PrivateData); + Writer.WriteEndElement (); + </insertAfter> +</hook> +.fi +.SH CONFIGURATION FILE EXAMPLE +This is the configuration file used to generate the serializer for ServiceDescription: +.PP +.nf +<configuration> + <serializer class="System.Web.Services.Description.ServiceDescription" assembly="System.Web.Services"> + <reader>ServiceDescriptionReaderBase</reader> + <writer>ServiceDescriptionWriterBase</writer> + <namespace>System.Web.Services.Description</namespace> + <outFileName>ServiceDescriptionSerializerBase.cs</outFileName> + <readerHooks> + <hook type="unknownElement"> + <select> + <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute> + </select> + <replace>ServiceDescription.ReadExtension (Reader, $OBJECT);</replace> + </hook> + <hook type="type"> + <select> + <typeName>System.Xml.Schema.XmlSchema</typeName> + </select> + <replace>$OBJECT = System.Xml.Schema.XmlSchema.Read (Reader, null);</replace> + </hook> + </readerHooks> + <writerHooks> + <hook type="elements"> + <select> + <typeAttribute>System.Web.Services.Configuration.XmlFormatExtensionPointAttribute</typeAttribute> + </select> + <insertBefore>ServiceDescription.WriteExtensions (Writer, $OBJECT);</insertBefore> + </hook> + <hook type="type"> + <select> + <typeName>System.Xml.Schema.XmlSchema</typeName> + </select> + <replace>$OBJECT.Write (Writer);</replace> + </hook> + </writerHooks> + </serializer> +</configuration> +.fi +.SH AUTHORS +Lluis Sanchez Gual (lluis@ximian.com) +.PP +.SH LICENSE +GenXS is released under the terms of the GNU GPL. +.PP +.SH SEE ALSO +mono(1), mcs(1) |