kwalify 0.5.1 → 0.6.0

data/doc-api/rdoc-style.css

@@ -0,0 +1,208 @@
+
+body {
+    font-family: Verdana,Arial,Helvetica,sans-serif;
+    font-size:   90%;
+    margin: 0;
+    margin-left: 40px;
+    padding: 0;
+    background: white;
+}
+
+h1,h2,h3,h4 { margin: 0; color: #efefef; background: transparent; }
+h1 { font-size: 150%; }
+h2,h3,h4 { margin-top: 1em; }
+
+a { background: #eef; color: #039; text-decoration: none; }
+a:hover { background: #039; color: #eef; }
+
+/* Override the base stylesheet's Anchor inside a table cell */
+td > a {
+  background: transparent;
+  color: #039;
+  text-decoration: none;
+}
+
+/* and inside a section title */
+.section-title > a {
+  background: transparent;
+  color: #eee;
+  text-decoration: none;
+}
+
+/* === Structural elements =================================== */
+
+div#index {
+    margin: 0;
+    margin-left: -40px;
+    padding: 0;
+    font-size: 90%;
+}
+
+
+div#index a {
+    margin-left: 0.7em;
+}
+
+div#index .section-bar {
+   margin-left: 0px;
+   padding-left: 0.7em;
+   background: #ccc;
+   font-size: small;
+}
+
+
+div#classHeader, div#fileHeader {
+    width: auto;
+    color: white;
+    padding: 0.5em 1.5em 0.5em 1.5em;
+    margin: 0;
+    margin-left: -40px;
+    border-bottom: 3px solid #006;
+}
+
+div#classHeader a, div#fileHeader a {
+    background: inherit;
+    color: white;
+}
+
+div#classHeader td, div#fileHeader td {
+    background: inherit;
+    color: white;
+}
+
+
+div#fileHeader {
+    background: #057;
+}
+
+div#classHeader {
+    background: #048;
+}
+
+
+.class-name-in-header {
+  font-size:  180%;
+  font-weight: bold;
+}
+
+
+div#bodyContent {
+    padding: 0 1.5em 0 1.5em;
+}
+
+div#description {
+    padding: 0.5em 1.5em;
+    background: #efefef;
+    border: 1px dotted #999;
+}
+
+div#description h1,h2,h3,h4,h5,h6 {
+    color: #125;;
+    background: transparent;
+}
+
+div#validator-badges {
+    text-align: center;
+}
+div#validator-badges img { border: 0; }
+
+div#copyright {
+    color: #333;
+    background: #efefef;
+    font: 0.75em sans-serif;
+    margin-top: 5em;
+    margin-bottom: 0;
+    padding: 0.5em 2em;
+}
+
+
+/* === Classes =================================== */
+
+table.header-table {
+    color: white;
+    font-size: small;
+}
+
+.type-note {
+    font-size: small;
+    color: #DEDEDE;
+}
+
+.xxsection-bar {
+    background: #eee;
+    color: #333;
+    padding: 3px;
+}
+
+.section-bar {
+   color: #333;
+   border-bottom: 1px solid #999;
+    margin-left: -20px;
+}
+
+
+.section-title {
+    background: #79a;
+    color: #eee;
+    padding: 3px;
+    margin-top: 2em;
+    margin-left: -30px;
+    border: 1px solid #999;
+}
+
+.top-aligned-row {  vertical-align: top }
+.bottom-aligned-row { vertical-align: bottom }
+
+/* --- Context section classes ----------------------- */
+
+.context-row { }
+.context-item-name { font-family: monospace; font-weight: bold; color: black; }
+.context-item-value { font-size: small; color: #448; }
+.context-item-desc { color: #333; padding-left: 2em; }
+
+/* --- Method classes -------------------------- */
+.method-detail {
+    background: #efefef;
+    padding: 0;
+    margin-top: 0.5em;
+    margin-bottom: 1em;
+    border: 1px dotted #ccc;
+}
+.method-heading {
+  color: black;
+  background: #ccc;
+  border-bottom: 1px solid #666;
+  padding: 0.2em 0.5em 0 0.5em;
+}
+.method-signature { color: black; background: inherit; }
+.method-name { font-weight: bold; }
+.method-args { font-style: italic; }
+.method-description { padding: 0 0.5em 0 0.5em; }
+
+/* --- Source code sections -------------------- */
+
+a.source-toggle { font-size: 90%; }
+div.method-source-code {
+    background: #262626;
+    color: #ffdead;
+    margin: 1em;
+    padding: 0.5em;
+    border: 1px dashed #999;
+    overflow: hidden;
+}
+
+div.method-source-code pre { color: #ffdead; overflow: hidden; }
+
+/* --- Ruby keyword styles --------------------- */
+
+.standalone-code { background: #221111; color: #ffdead; overflow: hidden; }
+
+.ruby-constant  { color: #7fffd4; background: transparent; }
+.ruby-keyword { color: #00ffff; background: transparent; }
+.ruby-ivar    { color: #eedd82; background: transparent; }
+.ruby-operator  { color: #00ffee; background: transparent; }
+.ruby-identifier { color: #ffdead; background: transparent; }
+.ruby-node    { color: #ffa07a; background: transparent; }
+.ruby-comment { color: #b22222; font-weight: bold; background: transparent; }
+.ruby-regexp  { color: #ffa07a; background: transparent; }
+.ruby-value   { color: #7fffd4; background: transparent; }

data/doc/users-guide.html

@@ -15,7 +15,7 @@
     <div align="left"><h1>Kwalify Users' Guide (for Ruby and Java)</h1></div>
     <div align="left">
       makoto kuwata &lt;kwa(at)kuwata-lab.com&gt;<br>
-      last update: $Date: 2005-12-20 12:50:56 +0900 (Tue, 20 Dec 2005) $<br>
+      last update: $Date: 2006-05-14 13:57:07 +0900 (Sun, 14 May 2006) $<br>
     </div>
 
 <a name="preface"></a>
@@ -57,16 +57,18 @@ This rule is more aggressive and cost-effective than Pareto Law. The rule is nam
 <p>Kwalify is small and in fact poorer than RelaxNG or XML Schema.
 I hope you extend/customize Kwalify for your own way.
 </p>
-Table of Contents:
-<div class="toc">
+<div class="footnote">
+ <dl compact>
+  <dt>(<a name="fnref:1" href="#fnlink:1">*1</a>)</dt>
+  <dd>Pronounce as 'Qualify'.</dd>
+ </dl>
+</div>
+<a name="toc"></a>
+<h3 class="section2">Table of Contents</h3>
 <ul>
   <li><a href="#preface">Preface</a>
-  </li>
-  <li><a href="#usage">Usage of Kwalify</a>
   <ul>
-    <li><a href="#usage1">Usage in Command-Line</a>
-    </li>
-    <li><a href="#usage2">Usage in Ruby Script</a>
+    <li><a href="#toc">Table of Contents</a>
     </li>
   </ul>
   </li>
@@ -104,171 +106,29 @@ Table of Contents:
     </li>
   </ul>
   </li>
+  <li><a href="#actions">Actions</a>
+  <ul>
+    <li><a href="#action-genclass">Class Definition Generation</a>
+    <ul>
+      <li><a href="#action-genclass-ruby">Ruby Class Definition</a>
+      </li>
+      <li><a href="#action-genclass-java">Java Class Definition</a>
+      </li>
+    </ul>
+    </li>
+  </ul>
+  </li>
+  <li><a href="#usage">Usage of Kwalify</a>
+  <ul>
+    <li><a href="#usage1">Usage in Command-Line</a>
+    </li>
+    <li><a href="#usage-ruby">Usage in Ruby Script</a>
+    </li>
+    <li><a href="#usage-java">Usage in Java Program</a>
+    </li>
+  </ul>
+  </li>
 </ul>
-</div>
-<div class="footnote">
- <dl compact>
-  <dt>(<a name="fnref:1" href="#fnlink:1">*1</a>)</dt>
-  <dd>Pronounce as 'Qualify'.</dd>
- </dl>
-</div>
-<br>
-
-
-<a name="usage"></a>
-<h2 class="section1">Usage of Kwalify</h2>
-<a name="usage1"></a>
-<h3 class="section2">Usage in Command-Line</h3>
-<div class="terminal_caption">
-usage1: validate YAML document in command-line</div>
-<pre class="terminal">### kwalify-ruby
-$ kwalify -f schema.yaml document.yaml [document2.yaml ...]
-
-### kwalify-java
-$ java -classpath kwalify.jar kwalify.Main -f schema.yaml document.yaml [document2.yaml ...]
-</pre>
-<div class="terminal_caption">
-usage2: validate schema definition in command-line</div>
-<pre class="terminal">### kwalify-ruby
-$ kwalify -m schema.yaml [schema2.yaml ...]
-
-### kwalify-java
-$ java -classpath kwalify.jar kwalify.Main -m schema.yaml [schema2.yaml ...]
-</pre>
-<p>Command-line options:
-</p>
-<dl class="dl3">
-<dt class="dt3"><strong>
-<code>-h</code>, <code>--help</code> </strong></dt>
-<dd class="dd3">
-	Print help message.
-</dd>
-<dt class="dt3"><strong>
-<code>-v</code> </strong></dt>
-<dd class="dd3">
-	Print version.
-</dd>
-<dt class="dt3"><strong>
-<code>-s</code> </strong></dt>
-<dd class="dd3">
-	Silent mode.
-</dd>
-<dt class="dt3"><strong>
-<code>-f <em>schema.yaml</em></code> </strong></dt>
-<dd class="dd3">
-	Specify schema definition file.
-</dd>
-<dt class="dt3"><strong>
-<code>-m</code> </strong></dt>
-<dd class="dd3">
-	Meta-validation of schema definition.
-</dd>
-<dt class="dt3"><strong>
-<code>-t</code> </strong></dt>
-<dd class="dd3">
-	Expand tab characters to spaces automatically.
-</dd>
-<dt class="dt3"><strong>
-<code>-l</code> </strong></dt>
-<dd class="dd3">
-	Show linenumber on which error found.
-</dd>
-<dt class="dt3"><strong>
-<code>-E</code> </strong></dt>
-<dd class="dd3">
-	Show errors in Emacs-compatible style (implies '-l' option).
-</dd>
-</dl>
-<p>Notice that the command-line option <code>-l</code> is an experimental feature, for kwalify command use original YAML parser instead of Syck parser when this option is specified.
-</p>
-<p>If you are an Emacs user, try <code>-E</code> option that show errors in format which Emacs can parse and jump to errors.
-You can use <code>C-x `</code> (next-error) to jump into errors.
-</p>
-<br>
-
-
-<a name="usage2"></a>
-<h3 class="section2">Usage in Ruby Script</h3>
-<p>The followings are example scripts for Ruby.
-</p>
-<div class="program_caption">
-validate YAML document in Ruby script</div>
-<pre class="program">require 'kwalify'
-
-## parse schema definition and create validator
-schema = YAML.load_file('schema.yaml')
-validator = Kwalify::Validator.new(schema)  # raises Kwalify::SchemaError if wrong
-
-## validate YAML document
-document = YAML.load_file('document.yaml')
-error_list = validator.validate(document)
-unless error_list.empty?
-   error_list.each do |error|     # error is instance of Kwalify::ValidationError
-      puts "[#{error.path}] #{error.message}"
-   end
-end
-</pre>
-<div class="program_caption">
-validate YAML document and show linenumber on where error is found.</div>
-<pre class="program">require 'kwalify'
-
-## parse schema definition and create validator
-schema = YAML.load_file('schema.yaml')
-validator = Kwalify::Validator.new(schema)  # raises Kwalify::SchemaError if wrong
-
-## parse YAML document with Kwalify's parser
-str = File.read('document.yaml')
-parser = Kwalify::Parser.new(str)
-document = parser.parse()
-
-## validate document and show errors
-error_list = validator.validate(document)
-unless error_list.empty?
-   parser.set_errors_linenum(error_list)  # set linenum on error
-   error_list.sort.each do |error|
-      puts "(line %d)[%s] %s" % [error.linenum, error.path, error.message]
-   end
-end
-</pre>
-<p>Kwalify's YAML parser is experimental. You should notice that Kwalify's YAML parser is limited only for basic syntax of YAML.
-</p>
-<p>The followings are example programs of Java.
-</p>
-<div class="program_caption">
-validate YAML document and show linenumber on where error is found.</div>
-<pre class="program">import kwalify.*;
-
-public class Test {
-
-  public static void main(String[] args) throws Exception {
-    // read schema
-    String schema_str = Util.readFile("schema.yaml");
-    Object schema = new YamlParser(schema_str).parse();
-
-    // read document file
-    String document_str = Util.readFile("document.yaml");
-    YamlParser parser = new YamlParser(document_str);
-    Object document = parser.parse();
-
-    // create validator and validate
-    Validator validator = new Validator(schema);
-    List errors = validator.validate(document);
-
-    // show errors
-    if (errors != null &amp;&amp; errors.size() &gt; 0) {
-      parser.setErrorsLineNumber(errors);
-      Collections.sort(errors);
-      for (Iterator it = errors.iterator(); it.hasNext(); ) {
-        ValidationException error = (ValidationException)it.next();
-        int linenum = error.getLineNumber();
-        String path = error.getPath();
-        String mesg = error.getMessage();
-        System.out.println("- " + linenum + ": [" + path + "] " + mesg);
-      }
-    }
-  }
-}
-</pre>
 <br>
 
 
@@ -293,6 +153,7 @@ sequence:
 - bar
 - baz
 </pre>
+<a name="valid01.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema01.yaml document01a.yaml
@@ -305,6 +166,7 @@ document01a.yaml#0: valid.
 - 123
 - baz
 </pre>
+<a name="invalid01.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema01.yaml document01b.yaml
@@ -342,6 +204,7 @@ email:  foo@mail.com
 age:    20
 birth:  1985-01-01
 </pre>
+<a name="valid02.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema02.yaml document02a.yaml
@@ -355,6 +218,7 @@ email:  foo(at)mail.com
 age:    twenty
 birth:  Jun 01, 1985
 </pre>
+<a name="invalid02.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema02.yaml document02b.yaml
@@ -391,6 +255,7 @@ sequence:
 - name:   baz
   email:  baz@mail.org
 </pre>
+<a name="valid03.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema03.yaml document03a.yaml
@@ -406,6 +271,7 @@ document03a.yaml#0: valid.
 - name:   baz
   mail:   baz@mail.org
 </pre>
+<a name="invalid03.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema03.yaml document03b.yaml
@@ -456,6 +322,7 @@ employees:
     name:   bar
     email:  bar@kuwata-lab.com
 </pre>
+<a name="valid04.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema04.yaml document04a.yaml
@@ -474,6 +341,7 @@ employees:
     name:   bar
     mail:   bar@kuwata-lab.com
 </pre>
+<a name="invalid04.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema04.yaml document04b.yaml
@@ -585,6 +453,11 @@ document04b.yaml#0: INVALID
 <dd class="dd3">
 	Description. This is not used for validation.
 </dd>
+<dt class="dt3"><strong>
+<code>classname:</code> </strong></dt>
+<dd class="dd3">
+	Class name.  This is available only with type 'map' and used with 'genclass' action. See '<a href="#actions">Actions</a>' section for details.
+</dd>
 </dl>
 <p>Rule contains 'type:' entry. 'sequence:' entry takes a list of rule. 'mapping:' entry takes a hash which values are rules.
 </p>
@@ -637,6 +510,7 @@ sequence:
   blood:    AB
   birth:    1980-01-01
 </pre>
+<a name="valid05.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema05.yaml document05a.yaml
@@ -658,6 +532,7 @@ document05a.yaml#0: valid.
   blood:    AB
   birth:    1980/01/01
 </pre>
+<a name="invalid05.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema05.yaml document05b.yaml
@@ -722,6 +597,7 @@ sequence:
   groups:
     - users
 </pre>
+<a name="valid06.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema06.yaml document06a.yaml
@@ -747,6 +623,7 @@ document06a.yaml#0: valid.
   groups:
     - users
 </pre>
+<a name="invalid06.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema06.yaml document06b.yaml
@@ -852,6 +729,7 @@ end
     answer:    bad
     reason:    I don't like this style.
 </pre>
+<a name="valid07.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ ruby answers-validator.rb document07a.yaml
@@ -868,6 +746,7 @@ Valid.
   - name:    Baz
     answer:  not bad
 </pre>
+<a name="invalid07.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ ruby answers-validator.rb document07b.yaml
@@ -989,6 +868,7 @@ public class AnswersValidator extends Validator {
     }
 }
 </pre>
+<a name="AnswersValidator.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ java -classpath kwalify.jar AnswersValidator document07a.yaml
@@ -1002,7 +882,7 @@ $ java -classpath kwalify.jar AnswersValidator document07b.yaml
 
 <a name="schema-block"></a>
 <h3 class="section2">Validator with Block</h3>
-<p><strong>Notice: This is an experimental feature.</strong>
+<p><strong>Notice: This feature has been obsolete. Use Kwalify::Validator#validate_hook() method instead.</strong>
 </p>
 <p><code>Kwalify::Validator.new()</code> method can take a block which is invoked when validation.
 </p>
@@ -1047,11 +927,13 @@ else
    end
 end
 </pre>
+<a name="valid08.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ ruby validate08.rb document07a.yaml
 Valid.
 </pre>
+<a name="valid08.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ ruby validate08.rb document07b.yaml
@@ -1113,26 +995,15 @@ JSON can be considered as a subset of YAML. It means that YAML parser can parse
 <pre class="program">{ "type": "map",
   "required": true,
   "mapping": {
-    "name": {
-       "type": "str",
-       "required": true
-    },
-    "email": {
-       "type": "str"
-    },
-    "age": {
-       "type": "int"
-    },
-    "gender": {
-       "type": "str",
-       "enum": ["M", "F"]
-    },
-    "favorite": {
-       "type": "seq",
-       "sequence": [
-          { "type": "str" }
-       ]
-    }
+    "name":   { "type": "str", "required": true },
+    "email":  { "type": "str" },
+    "age":    { "type": "int" },
+    "gender": { "type": "str", "enum": ["M", "F"] },
+    "favorite": { "type": "seq",
+                  "sequence": [
+                     { "type": "str" }
+                   ]
+                 }
   }
 }
 </pre>
@@ -1150,6 +1021,7 @@ JSON can be considered as a subset of YAML. It means that YAML parser can parse
   ]
 }
 </pre>
+<a name="valid12.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema12.yaml document12a.yaml
@@ -1165,6 +1037,7 @@ document12a.yaml#0: valid.
   "favorite": [ 123, 456 ]
 }
 </pre>
+<a name="invalid12.yaml"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema12.yaml document12b.yaml
@@ -1225,6 +1098,7 @@ sequence:
   post:          clerk
   supervisor:    <strong>*bar</strong>
 </pre>
+<a name="valid13.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema13.yaml document13a.yaml
@@ -1268,6 +1142,7 @@ mapping:
 value2: 0.5
 value3: -0.9
 </pre>
+<a name="valid14.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema14.yaml document14a.yaml
@@ -1280,6 +1155,7 @@ document14a.yaml#0: valid.
 value2: 1.1
 value3: -2.0
 </pre>
+<a name="invalid14.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema14.yaml document14b.yaml
@@ -1346,6 +1222,7 @@ user:
   name: bar
   email: bar@mail.com
 </pre>
+<a name="valid15.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema15.yaml document15a.yaml
@@ -1360,6 +1237,7 @@ document15a.yaml#0: valid.
 user:
   name: toooooo-looooong-name
 </pre>
+<a name="invalid15.expected"></a>
 <div class="terminal_caption">
 validate</div>
 <pre class="terminal">$ kwalify -lf schema15.yaml document15b.yaml
@@ -1370,6 +1248,628 @@ document15b.yaml#0: INVALID
 <br>
 
 
+<br>
+
+
+<a name="actions"></a>
+<h2 class="section1">Actions</h2>
+<p>Kwalify has the command-line '-a <em>action</em>' which perform a certain action to schema definition.
+Currently only the following action is supported.
+</p>
+<dl class="dl3">
+<dt class="dt3"><strong>
+genclass-ruby </strong></dt>
+<dd class="dd3">
+	Generate class definitions in Ruby.
+</dd>
+<dt class="dt3"><strong>
+genclass-java </strong></dt>
+<dd class="dd3">
+	Generate class definitions in Java.
+</dd>
+</dl>
+<p>In fact action name represents template filename.
+For example, action 'genclass-ruby' invokes template file 'kwalify/templates/genclass-ruby.eruby'.
+</p>
+<p>Each action can accept some command-line properties.
+For example, action 'genclass-ruby' can accept the command-line properties '--module=<em>name</em>', '--parent=<em>name</em>', and so on.
+Type 'kwalify -h -a <em>action</em>' to show the list of command-line properties the action can accept.
+</p>
+<a name="action-genclass"></a>
+<h3 class="section2">Class Definition Generation</h3>
+<p>Command-line option '-a genclass-ruby' or '-a genclass-java' generates class definition
+automatically from schema definition in Ruby or Java.
+</p>
+<p>Assume the following data file and schema definition.
+</p>
+<a name="address-book.yaml"></a>
+<div class="program_caption">
+<code>address-book.yaml</code> : data file</div>
+<pre class="program">groups:
+
+  - name:   family
+    desc:   my family
+
+  - name:   friend
+    desc:   my friends
+
+  - name:   business
+    desc:   those who works together
+
+persons:
+
+  - name:   Sumire
+    group:  family
+    birth:  2000-01-01
+    blood:  A
+
+  - name:   Shiina
+    group:  friend
+    birth:  1995-01-01
+    email:  shiina@mail.org
+
+  - name:   Sakura
+    group:  business
+    email:  cherry@mail.net
+    phone:  012-345-6789
+</pre>
+<a name="address-book.schema.yaml"></a>
+<div class="program_caption">
+<code>address-book.schema.yaml</code> : schema definition file</div>
+<pre class="program">type:  map
+<strong>classname:  AddressBook</strong>
+desc:  address-book class
+mapping:
+ "groups":
+    type:  seq
+    sequence:
+      - type:  map
+        <strong>classname:  Group</strong>
+        desc:  group class
+        mapping:
+         "name":  { type: str,  required: yes }
+         "desc":  { type: str }
+ "persons":
+    type:  seq
+    sequence:
+      - type:  map
+        <strong>classname:  Person</strong>
+        desc:  person class
+        mapping:
+         "name":  { type: str, required: yes }
+         "desc":  { type: str }
+         "group": { type: str }
+         "email": { type: str, pattern: '/@/' }
+         "phone": { type: str }
+         "birth": { type: date }
+         "blood": { type: str, enum: [A, B, O, AB] }
+</pre>
+<a name="action-genclass-ruby"></a>
+<h4 class="section3">Ruby Class Definition</h4>
+<div class="terminal_caption">
+generate class definition</div>
+<pre class="terminal">$ kwalify <strong>-a genclass-ruby</strong> -tf address-book.schema.yaml &gt; address-book.rb
+</pre>
+<a name="address-book.rb"></a>
+<div class="program_caption">
+<code>address-book.rb</code> : generated class definition</div>
+<pre class="program">## address-book class
+class AddressBook
+  def initialize(hash)
+    @persons    = (v=hash['persons']) ? v.map!{|e| e.is_a?(Person) ? e : Person.new(e)} : v
+    @groups     = (v=hash['groups']) ? v.map!{|e| e.is_a?(Group) ? e : Group.new(e)} : v
+  end
+  attr_accessor :persons    # seq
+  attr_accessor :groups     # seq
+end
+
+## person class
+class Person
+  def initialize(hash)
+    @name       = hash['name']
+    @desc       = hash['desc']
+    @phone      = hash['phone']
+    @blood      = hash['blood']
+    @group      = hash['group']
+    @birth      = hash['birth']
+    @email      = hash['email']
+  end
+  attr_accessor :name       # str
+  attr_accessor :desc       # str
+  attr_accessor :phone      # str
+  attr_accessor :blood      # str
+  attr_accessor :group      # str
+  attr_accessor :birth      # date
+  attr_accessor :email      # str
+end
+
+## group class
+class Group
+  def initialize(hash)
+    @name       = hash['name']
+    @desc       = hash['desc']
+  end
+  attr_accessor :name       # str
+  attr_accessor :desc       # str
+end
+
+</pre>
+<a name="example-address-book.rb"></a>
+<div class="program_caption">
+<code>example-address-book.rb</code> : example code of using address-book.rb</div>
+<pre class="program">require 'address-book'
+require 'yaml'
+require 'pp'
+
+str = File.read('address-book.yaml')
+ydoc = YAML.load(str)
+<strong>addrbook = AddressBook.new(ydoc)</strong>
+
+pp <strong>addrbook.groups</strong>
+pp <strong>addrbook.persons</strong>
+</pre>
+<a name="example-address-book.expected"></a>
+<div class="terminal_caption">
+result</div>
+<pre class="terminal">$ ruby example-address-book.rb
+[#&lt;Group:0xddf24 @desc="my family", @name="family"&gt;,
+ #&lt;Group:0xddf10 @desc="my friends", @name="friend"&gt;,
+ #&lt;Group:0xdde84 @desc="those who works together", @name="business"&gt;]
+[#&lt;Person:0xdefdc
+  @birth=#&lt;Date: 4903089/2,0,2299161&gt;,
+  @blood="A",
+  @desc=nil,
+  @email=nil,
+  @group="family",
+  @name="Sumire",
+  @phone=nil&gt;,
+ #&lt;Person:0xdee9c
+  @birth=#&lt;Date: 4899437/2,0,2299161&gt;,
+  @blood=nil,
+  @desc=nil,
+  @email="shiina@mail.org",
+  @group="friend",
+  @name="Shiina",
+  @phone=nil&gt;,
+ #&lt;Person:0xde8e8
+  @birth=nil,
+  @blood=nil,
+  @desc=nil,
+  @email="cherry@mail.net",
+  @group="business",
+  @name="Sakura",
+  @phone="012-345-6789"&gt;]
+</pre>
+<p>Command-line option '<code>-h -a genclass-ruby</code>' shows the commpand-line properties that template can accept.
+</p>
+<a name="option_ha.expected"></a>
+<div class="terminal_caption">
+show command-line properties</div>
+<pre class="terminal">$ kwalify -ha genclass-ruby
+  --module=name   :  module name in which class defined
+  --parent=name   :  parent class name
+  --include=name  :  module name which all classes include
+</pre>
+<div class="terminal_caption">
+example of command-line properties</div>
+<pre class="terminal">$ kwalify -a genclass-ruby --module=My --include=Kwalify::HashInterface
+</pre>
+<p>'Kwalify::HashInterface' is a module which make object accessible like as Hash.
+It is defined in 'kwalify/util/hash-interface.rb'
+</p>
+<br>
+
+<a name="action-genclass-java"></a>
+<h4 class="section3">Java Class Definition</h4>
+<a name="genclass_java.expected"></a>
+<div class="terminal_caption">
+generate java class definition</div>
+<pre class="terminal">$ kwalify <strong>-a genclass-java</strong> -tf address-book.schema.yaml
+generating ./AddressBook.java...done.
+generating ./Person.java...done.
+generating ./Group.java...done.
+</pre>
+<a name="AddressBook.java.expected"></a>
+<div class="program_caption">
+<code>AddressBook.java</code> : generated class definition</div>
+<pre class="program">// generated by kwalify from address-book.schema.yaml
+
+import java.util.*;
+
+/**
+ *  address-book class
+ */
+public class AddressBook {
+
+    private List _persons;
+    private List _groups;
+
+    public AddressBook() {}
+
+    public AddressBook(Map map) {
+        List seq;
+        Object obj;
+        if ((seq = (List)map.get("persons")) != null) {
+            for (int i = 0; i &lt; seq.size(); i++) {
+                if ((obj = seq.get(i)) instanceof Map) {
+                    seq.set(i, new Person((Map)obj));
+                }
+            }
+        }
+        _persons      = seq;
+        if ((seq = (List)map.get("groups")) != null) {
+            for (int i = 0; i &lt; seq.size(); i++) {
+                if ((obj = seq.get(i)) instanceof Map) {
+                    seq.set(i, new Group((Map)obj));
+                }
+            }
+        }
+        _groups       = seq;
+    }
+
+    public List getPersons() { return _persons; }
+    public void setPersons(List persons_) { _persons = persons_; }
+    public List getGroups() { return _groups; }
+    public void setGroups(List groups_) { _groups = groups_; }
+}
+</pre>
+<a name="Group.java.expected"></a>
+<div class="program_caption">
+<code>Group.java</code> : generated class definition</div>
+<pre class="program">// generated by kwalify from address-book.schema.yaml
+
+import java.util.*;
+
+/**
+ *  group class
+ */
+public class Group {
+
+    private String _name;
+    private String _desc;
+
+    public Group() {}
+
+    public Group(Map map) {
+        _name         = (String)map.get("name");
+        _desc         = (String)map.get("desc");
+    }
+
+    public String getName() { return _name; }
+    public void setName(String name_) { _name = name_; }
+    public String getDesc() { return _desc; }
+    public void setDesc(String desc_) { _desc = desc_; }
+}
+</pre>
+<a name="Person.java.expected"></a>
+<div class="program_caption">
+<code>Person.java</code> : generated class definition</div>
+<pre class="program">// generated by kwalify from address-book.schema.yaml
+
+import java.util.*;
+
+/**
+ *  person class
+ */
+public class Person {
+
+    private String _name;
+    private String _desc;
+    private String _phone;
+    private String _blood;
+    private String _group;
+    private Date _birth;
+    private String _email;
+
+    public Person() {}
+
+    public Person(Map map) {
+        _name         = (String)map.get("name");
+        _desc         = (String)map.get("desc");
+        _phone        = (String)map.get("phone");
+        _blood        = (String)map.get("blood");
+        _group        = (String)map.get("group");
+        _birth        = (Date)map.get("birth");
+        _email        = (String)map.get("email");
+    }
+
+    public String getName() { return _name; }
+    public void setName(String name_) { _name = name_; }
+    public String getDesc() { return _desc; }
+    public void setDesc(String desc_) { _desc = desc_; }
+    public String getPhone() { return _phone; }
+    public void setPhone(String phone_) { _phone = phone_; }
+    public String getBlood() { return _blood; }
+    public void setBlood(String blood_) { _blood = blood_; }
+    public String getGroup() { return _group; }
+    public void setGroup(String group_) { _group = group_; }
+    public Date getBirth() { return _birth; }
+    public void setBirth(Date birth_) { _birth = birth_; }
+    public String getEmail() { return _email; }
+    public void setEmail(String email_) { _email = email_; }
+}
+</pre>
+<a name="ExampleAddressBook.java"></a>
+<div class="program_caption">
+<code>ExampleAddressBook.java</code> : example code of using *.java</div>
+<pre class="program">import java.util.*;
+import kwalify.*;
+
+public class ExampleAddressBook {
+    public static void main(String args[]) throws Exception {
+        // read schema
+        String schema_str = Util.readFile("address-book.schema.yaml");
+        schema_str = Util.untabify(schema_str);
+        Object schema = new YamlParser(schema_str).parse();
+
+        // read document file
+        String document_str = Util.readFile("address-book.yaml");
+        document_str = Util.untabify(document_str);
+        YamlParser parser = new YamlParser(document_str);
+        Object document = parser.parse();
+
+        // create address book object
+        AddressBook addrbook = new AddressBook((Map)document);
+
+        // show groups
+        List groups = addrbook.getGroups();
+        if (groups != null) {
+            for (Iterator it = groups.iterator(); it.hasNext(); ) {
+                Group group = (Group)it.next();
+                System.out.println("group name: " + group.getName());
+                System.out.println("group desc: " + group.getDesc());
+                System.out.println();
+            }
+        }
+
+        // show persons
+        List persons = addrbook.getPersons();
+        if (persons != null) {
+            for (Iterator it = persons.iterator(); it.hasNext(); ) {
+                Person person = (Person)it.next();
+                System.out.println("person name:  " + person.getName());
+                System.out.println("person group: " + person.getGroup());
+                System.out.println("person email: " + person.getEmail());
+                System.out.println("person phone: " + person.getPhone());
+                System.out.println("person blood: " + person.getBlood());
+                System.out.println("person birth: " + person.getBirth());
+                System.out.println();
+            }
+        }
+    }
+
+}
+</pre>
+<a name="example-address-book-java.expected"></a>
+<div class="terminal_caption">
+result</div>
+<pre class="terminal">$ javac -classpath '.:kwalify.jar' *.java
+$ java  -classpath '.:kwalify.jar' ExampleAddressBook
+group name: family
+group desc: my family
+
+group name: friend
+group desc: my friends
+
+group name: business
+group desc: those who works together
+
+person name:  Sumire
+person group: family
+person email: null
+person phone: null
+person blood: A
+person birth: Tue Feb 01 00:00:00 JST 2000
+
+person name:  Shiina
+person group: friend
+person email: shiina@mail.org
+person phone: null
+person blood: null
+person birth: Wed Feb 01 00:00:00 JST 1995
+
+person name:  Sakura
+person group: business
+person email: cherry@mail.net
+person phone: 012-345-6789
+person blood: null
+person birth: null
+
+</pre>
+<p>Command-line option '<code>-h -a genclass-java</code>' shows the commpand-line properties that template can accept.
+</p>
+<a name="option_ha_genclass_java.expected"></a>
+<div class="terminal_caption">
+show command-line properties</div>
+<pre class="terminal">$ kwalify -ha genclass-java
+  --package=name        :  package name
+  --extends=name        :  class name to extend
+  --implements=name,... :  interface names to implement
+  --dir=path            :  directory to locate output file
+  --basedir=path        :  base directory to locate output file
+</pre>
+<div class="terminal_caption">
+example of command-line properties</div>
+<pre class="terminal">$ kwalify -a genclass-java --package=com.example.my --implements=Serializable --basedir=src
+</pre>
+<br>
+
+<br>
+
+
+<br>
+
+
+<a name="usage"></a>
+<h2 class="section1">Usage of Kwalify</h2>
+<a name="usage1"></a>
+<h3 class="section2">Usage in Command-Line</h3>
+<div class="terminal_caption">
+usage1: validate YAML document in command-line</div>
+<pre class="terminal">### kwalify-ruby
+$ kwalify -f schema.yaml document.yaml [document2.yaml ...]
+
+### kwalify-java
+$ java -classpath kwalify.jar kwalify.Main -f schema.yaml document.yaml [document2.yaml ...]
+</pre>
+<div class="terminal_caption">
+usage2: validate schema definition in command-line</div>
+<pre class="terminal">### kwalify-ruby
+$ kwalify -m schema.yaml [schema2.yaml ...]
+
+### kwalify-java
+$ java -classpath kwalify.jar kwalify.Main -m schema.yaml [schema2.yaml ...]
+</pre>
+<p>Command-line options:
+</p>
+<dl class="dl3">
+<dt class="dt3"><strong>
+<code>-h</code>, <code>--help</code> </strong></dt>
+<dd class="dd3">
+	Print help message.
+</dd>
+<dt class="dt3"><strong>
+<code>-v</code> </strong></dt>
+<dd class="dd3">
+	Print version.
+</dd>
+<dt class="dt3"><strong>
+<code>-s</code> </strong></dt>
+<dd class="dd3">
+	Silent mode.
+</dd>
+<dt class="dt3"><strong>
+<code>-f <em>schema.yaml</em></code> </strong></dt>
+<dd class="dd3">
+	Specify schema definition file.
+</dd>
+<dt class="dt3"><strong>
+<code>-m</code> </strong></dt>
+<dd class="dd3">
+	Meta-validation of schema definition.
+</dd>
+<dt class="dt3"><strong>
+<code>-t</code> </strong></dt>
+<dd class="dd3">
+	Expand tab characters to spaces automatically.
+</dd>
+<dt class="dt3"><strong>
+<code>-l</code> </strong></dt>
+<dd class="dd3">
+	Show linenumber on which error found.
+</dd>
+<dt class="dt3"><strong>
+<code>-E</code> </strong></dt>
+<dd class="dd3">
+	Show errors in Emacs-compatible style (implies '-l' option).
+</dd>
+<dt class="dt3"><strong>
+<code>-a action</code> </strong></dt>
+<dd class="dd3">
+	Do action. Currently supported action is 'genclass-ruby' and 'genclass-java'.
+	Try '-ha action' to get help about the action.
+</dd>
+</dl>
+<p>Notice that the command-line option <code>-l</code> is an experimental feature, for kwalify command use original YAML parser instead of Syck parser when this option is specified.
+</p>
+<p>If you are an Emacs user, try <code>-E</code> option that show errors in format which Emacs can parse and jump to errors.
+You can use <code>C-x `</code> (next-error) to jump into errors.
+</p>
+<br>
+
+
+<a name="usage-ruby"></a>
+<h3 class="section2">Usage in Ruby Script</h3>
+<p>The followings are example scripts for Ruby.
+</p>
+<div class="program_caption">
+validate YAML document in Ruby script</div>
+<pre class="program">require 'kwalify'
+
+## parse schema definition and create validator
+schema = YAML.load_file('schema.yaml')
+validator = Kwalify::Validator.new(schema)  # raises Kwalify::SchemaError if wrong
+
+## validate YAML document
+document = YAML.load_file('document.yaml')
+error_list = validator.validate(document)
+unless error_list.empty?
+   error_list.each do |error|     # error is instance of Kwalify::ValidationError
+      puts "[#{error.path}] #{error.message}"
+   end
+end
+</pre>
+<div class="program_caption">
+validate YAML document and show linenumber on where error is found.</div>
+<pre class="program">require 'kwalify'
+
+## parse schema definition and create validator
+schema = YAML.load_file('schema.yaml')
+validator = Kwalify::Validator.new(schema)  # raises Kwalify::SchemaError if wrong
+
+## parse YAML document with Kwalify's parser
+str = File.read('document.yaml')
+parser = Kwalify::Parser.new(str)
+document = parser.parse()
+
+## validate document and show errors
+error_list = validator.validate(document)
+unless error_list.empty?
+   parser.set_errors_linenum(error_list)  # set linenum on error
+   error_list.sort.each do |error|
+      puts "(line %d)[%s] %s" % [error.linenum, error.path, error.message]
+   end
+end
+</pre>
+<p>Kwalify's YAML parser is experimental. You should notice that Kwalify's YAML parser is limited only for basic syntax of YAML.
+</p>
+<br>
+
+
+<a name="usage-java"></a>
+<h3 class="section2">Usage in Java Program</h3>
+<p>The followings are example programs of Java.
+</p>
+<div class="program_caption">
+validate YAML document and show linenumber on where error is found.</div>
+<pre class="program">import kwalify.*;
+
+public class Test {
+
+  public static void main(String[] args) throws Exception {
+    // read schema
+    String schema_str = Util.readFile("schema.yaml");
+    schema_str = Util.untabify(schema_str);
+    Object schema = new YamlParser(schema_str).parse();
+
+    // read document file
+    String document_str = Util.readFile("document.yaml");
+    document_str = Util.untabify(document_str);
+    YamlParser parser = new YamlParser(document_str);
+    Object document = parser.parse();
+
+    // create validator and validate
+    Validator validator = new Validator(schema);
+    List errors = validator.validate(document);
+
+    // show errors
+    if (errors != null &amp;&amp; errors.size() &gt; 0) {
+      parser.setErrorsLineNumber(errors);
+      Collections.sort(errors);
+      for (Iterator it = errors.iterator(); it.hasNext(); ) {
+        ValidationException error = (ValidationException)it.next();
+        int linenum = error.getLineNumber();
+        String path = error.getPath();
+        String mesg = error.getMessage();
+        System.out.println("- " + linenum + ": [" + path + "] " + mesg);
+      }
+    }
+  }
+}
+</pre>
+<br>
+
+
 <br>