Kwalify User's Guide (for Ruby)

release: $Release: $

4   Actions

Kwalify has the command-line '-a action' which perform a certain action to schema definition. Currently only the following actions are provided.

genclass-ruby

Generate class definitions in Ruby.

genclass-java

Generate class definitions in Java.

genclass-php

Generate class definitions in Ruby.

In fact action name represents template filename. For example, action 'genclass-ruby' invokes template file 'kwalify/templates/genclass-ruby.eruby'.

Each action can accept some command-line properties. For example, action 'genclass-ruby' can accept the command-line properties '--module=name', '--parent=name', and so on. Type 'kwalify -h -a action' to show the list of command-line properties the action can accept.

It is able to add your on action template file. The command-line option '-I' (template path) will help you.

4-1   Class Definition Generation

Command-line option '-a genclass-ruby' or '-a genclass-java' generates class definition automatically from schema definition in Ruby or Java.

Assume the following data file and schema definition.

groups:

  - name:   family
    desc:   my family

  - name:   friend
    desc:   my friends

  - name:   business
    desc:   those who works together

people:

  - 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

type:  map
class:  AddressBook
desc:  address-book class
mapping:
 "groups":
    type:  seq
    sequence:
      - type:  map
        class:  Group
        desc:  group class
        mapping:
         "name":  { type: str,  required: yes }
         "desc":  { type: str }
 "people":
    type:  seq
    sequence:
      - type:  map
        class:  Person
        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] }
         "deleted": { type: bool, default: false }

4-1-1   Ruby Class Definition

$ kwalify -a genclass-ruby -tf address_book.schema.yaml > address_book.rb

## address-book class
class AddressBook
  def initialize(hash=nil)
    if hash.nil?
      return
    end
    @groups           = (v=hash['groups']) ? v.map!{|e| e.is_a?(Group) ? e : Group.new(e)} : v
    @people           = (v=hash['people']) ? v.map!{|e| e.is_a?(Person) ? e : Person.new(e)} : v
  end
  attr_accessor :groups           # seq
  attr_accessor :people           # seq
end

## group class
class Group
  def initialize(hash=nil)
    if hash.nil?
      return
    end
    @name             = hash['name']
    @desc             = hash['desc']
  end
  attr_accessor :name             # str
  attr_accessor :desc             # str
end

## person class
class Person
  def initialize(hash=nil)
    if hash.nil?
      @deleted          = false
      return
    end
    @name             = hash['name']
    @desc             = hash['desc']
    @group            = hash['group']
    @email            = hash['email']
    @phone            = hash['phone']
    @birth            = hash['birth']
    @blood            = hash['blood']
    @deleted          = (v=hash['deleted']).nil? ? false : v
  end
  attr_accessor :name             # str
  attr_accessor :desc             # str
  attr_accessor :group            # str
  attr_accessor :email            # str
  attr_accessor :phone            # str
  attr_accessor :birth            # date
  attr_accessor :blood            # str
  attr_accessor :deleted          # bool
  def deleted?      ;  @deleted      ; end
end

require 'address_book'
require 'yaml'
require 'pp'

str = File.read('address_book.yaml')
ydoc = YAML.load(str)
addrbook = AddressBook.new(ydoc)

pp addrbook.groups
pp addrbook.people

$ ruby example_address_book.rb
[#<Group:0xddf24 @desc="my family", @name="family">,
 #<Group:0xddf10 @desc="my friends", @name="friend">,
 #<Group:0xdde84 @desc="those who works together", @name="business">]
[#<Person:0xdefdc
  @birth=#<Date: 4903089/2,0,2299161>,
  @blood="A",
  @deleted=false,
  @desc=nil,
  @email=nil,
  @group="family",
  @name="Sumire",
  @phone=nil>,
 #<Person:0xdee9c
  @birth=#<Date: 4899437/2,0,2299161>,
  @blood=nil,
  @deleted=false,
  @desc=nil,
  @email="shiina@mail.org",
  @group="friend",
  @name="Shiina",
  @phone=nil>,
 #<Person:0xde8e8
  @birth=nil,
  @blood=nil,
  @deleted=false,
  @desc=nil,
  @email="cherry@mail.net",
  @group="business",
  @name="Sakura",
  @phone="012-345-6789">]

Command-line option '-h -a genclass-ruby' shows the commpand-line properties that template can accept.

$ 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
  --initialize=false :  not print initialize() method
  --hashlike      :  include Kwalify::Util::HashLike module

$ kwalify -a genclass-ruby --module=My --hashlike

If command-line property '--hashlike' (== '--hashlike=true') is specified, module Kwalify::Util::HashLike is included for each classes generated. That module is defined in 'kwalify/util/hashlike.rb'

4-1-2   Java Class Definition

$ kwalify -a genclass-java -tf address_book.schema.yaml
generating ./AddressBook.java...done.
generating ./Group.java...done.
generating ./Person.java...done.

// generated by kwalify from address_book.schema.yaml

import java.util.*;

/**
 *  address-book class
 */
public class AddressBook {

    private List _groups;
    private List _people;

    public AddressBook() {}

    public AddressBook(Map map) {
        List seq;
        Object obj;
        if ((seq = (List)map.get("groups")) != null) {
            for (int i = 0; i < seq.size(); i++) {
                if ((obj = seq.get(i)) instanceof Map) {
                    seq.set(i, new Group((Map)obj));
                }
            }
        }
        _groups       = seq;
        if ((seq = (List)map.get("people")) != null) {
            for (int i = 0; i < seq.size(); i++) {
                if ((obj = seq.get(i)) instanceof Map) {
                    seq.set(i, new Person((Map)obj));
                }
            }
        }
        _people       = seq;
    }

    public List getGroups() { return _groups; }
    public void setGroups(List groups_) { _groups = groups_; }
    public List getPeople() { return _people; }
    public void setPeople(List people_) { _people = people_; }
}

// 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_; }
}

// generated by kwalify from address_book.schema.yaml

import java.util.*;

/**
 *  person class
 */
public class Person {

    private String _name;
    private String _desc;
    private String _group;
    private String _email;
    private String _phone;
    private Date _birth;
    private String _blood;

    public Person() {}

    public Person(Map map) {
        _name         = (String)map.get("name");
        _desc         = (String)map.get("desc");
        _group        = (String)map.get("group");
        _email        = (String)map.get("email");
        _phone        = (String)map.get("phone");
        _birth        = (Date)map.get("birth");
        _blood        = (String)map.get("blood");
    }

    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 getGroup() { return _group; }
    public void setGroup(String group_) { _group = group_; }
    public String getEmail() { return _email; }
    public void setEmail(String email_) { _email = email_; }
    public String getPhone() { return _phone; }
    public void setPhone(String phone_) { _phone = phone_; }
    public Date getBirth() { return _birth; }
    public void setBirth(Date birth_) { _birth = birth_; }
    public String getBlood() { return _blood; }
    public void setBlood(String blood_) { _blood = blood_; }
}

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 people
        List people = addrbook.getPeople();
        if (people != null) {
            for (Iterator it = people.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();
            }
        }
    }

}

$ 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

Command-line option '-h -a genclass-java' shows the commpand-line properties that template can accept.

$ 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
  --constructor=false   :  not print initialize() method

$ kwalify -a genclass-java --package=com.example.my --implements=Serializable --basedir=src