mcs/class/Commons.Xml.Relaxng/README

   1 * Commons.Xml.Relaxng\r
   2 \r
   3 ** Introduction\r
   4 \r
   5   RelaxngValidatingReader is an implementation to validate XML with RELAX NG\r
   6   grammar. You can use full standard grammar components with it.\r
   7 \r
   8   Currently it supports both xml syntax and compact syntax.\r
   9 \r
  10   It supports RELAX NG predefined datatypes and XML Schema datatypes (its\r
  11   DatatypeLibrary is http://www.w3.org/2001/XMLSchema-datatypes ).\r
  12 \r
  13   All classes which is expected to use are in namespace Commons.Xml.Relaxng,\r
  14   except for Commons.Xml.Relaxng.Rnc.RncParser class (which is used to parse\r
  15   compact syntax).\r
  16   There is another namespace Commons.Xml.Relaxng.Derivative which is not\r
  17   expected to be used in users custom classes, though the classes are public\r
  18   as yet.\r
  19 \r
  20 \r
  21 ** Grammar Object Model\r
  22 \r
  23   RELAX NG grammar structure is represented in abstract RelaxngPattern class\r
  24   and its derivations. The easiest way to get this instance is to use\r
  25   static Read() method of RelaxngPattern class:\r
  26 \r
  27         RelaxngPattern pattern = RelaxngPattern.Read (\r
  28                 new XmlTextReader ("relaxng.rng");\r
  29 \r
  30   You can also use RelaxngPattern class to reuse grammar instance, as\r
  31   already described (see Grammar Object Model).\r
  32 \r
  33   And also, RelaxngGrammar and its contents can be created with managed code\r
  34   like System.Xml.Schema.XmlSchema.\r
  35 \r
  36 \r
  37 ** Compact Syntax Support\r
  38 \r
  39   Commons.Xml.Relaxng.dll also supports RELAX NG Compact Syntax. To parse\r
  40   compact syntax file, use Commons.Xml.Relaxng.Rnc.RncParser class:\r
  41 \r
  42         RncParser parser = new RncParser (new NameTable ());\r
  43         TextReader source = new StreamReader ("relaxng.rnc");\r
  44         RelaxngGrammar grammar = parser.Parse (source);\r
  45 \r
  46 \r
  47 ** Validating Reader usage\r
  48 \r
  49   RelaxngValidatingReader is used to validate XML document with RELAX NG\r
  50   grammar. The usage is simple:\r
  51 \r
  52         XmlReader instance = new XmlTextReader ("instance.xml");\r
  53         XmlReader grammar = new XmlTextReader ("my.rng");\r
  54         RelaxngValidatingReader reader = \r
  55                 new RelaxngValidatingReader (instance, grammar);\r
  56 \r
  57   Then Read() method (and other reading methods such as ReadElementString())\r
  58   reads the instance, validating with the supplied grammar.\r
  59 \r
  60 \r
  61 ** Datatype support\r
  62 \r
  63   Commons.Xml.Relaxng now supports custom datatype library. There are two \r
  64   classes from which you have to write classes derived.\r
  65 \r
  66   <ul>\r
  67         * RelaxngDatatype: it represents the actual data type\r
  68 \r
  69         * RelaxngDatatypeProvider: it provides the way to get RelaxngDatatype from QName and parameters\r
  70   </ul>\r
  71 \r
  72   RelaxngDatatype class has Parse() method which is used for validation.\r
  73   Basically RelaxngValidatingReader is only aware of that if the typed\r
  74   elements or attributes are parsable (you can override IsValid() method\r
  75   to change this behavior) using Parse() method for each datatype.\r
  76 \r
  77   To enable custom datatype support, first you have to implement concrete\r
  78   RelaxngDatatype implementations (it only requires to override Parse(), \r
  79   Name and NamespaceURI) and then RelaxngDatatypeProvider implementations\r
  80   (only GetDatatype() is required) to return the datatypes you implemented\r
  81   as above.\r
  82 \r
  83   Basically RelaxngDatatypeProvider is designed to allow to contain \r
  84   datatypes in different namespaces (e.g. supporting both XML schema\r
  85   datatypes and default namespace types). You can also use \r
  86   RelaxngMergedProvider class to combine existing two or more datatype\r
  87   providers. However, for ease of datatype search, it is indexed by the\r
  88   namespace URI (if you want to mix namespace-overrapped providers, you can\r
  89   implement your own merging provider). \r
  90 \r
  91 \r
  92 ** Known bugs\r
  93 \r
  94   Currently it is beta version as yet. It has some bugs:\r
  95 \r
  96         - Grammar simplification is incorrectly implemented as yet. It will\r
  97           fail to check incorrect recursion and might bind ref to incorrect\r
  98           definitions.\r
  99           not handle the same name define components properly.\r
 100         - Name class analysis and constraint check is not implemented (part\r
 101           of spec 7).\r
 102         - Empty string might not be validated properly.\r
 103 \r