Kwalify Users' Guide (for Ruby and Java)

3   Actions

Kwalify has the command-line '-a action' which perform a certain action to schema definition. Currently only the following action is supported.

genclass-ruby
Generate class definitions in Ruby.
genclass-java
Generate class definitions in Java.

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.

3-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.

address-book.yaml : data file
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
address-book.schema.yaml : schema definition file
type:  map
classname:  AddressBook
desc:  address-book class
mapping:
 "groups":
    type:  seq
    sequence:
      - type:  map
        classname:  Group
        desc:  group class
        mapping:
         "name":  { type: str,  required: yes }
         "desc":  { type: str }
 "persons":
    type:  seq
    sequence:
      - type:  map
        classname:  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] }

3-1-1   Ruby Class Definition

generate class definition
$ kwalify -a genclass-ruby -tf address-book.schema.yaml > address-book.rb
address-book.rb : generated class definition
## 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

example-address-book.rb : example code of using address-book.rb
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.persons
result
$ 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",
  @desc=nil,
  @email=nil,
  @group="family",
  @name="Sumire",
  @phone=nil>,
 #<Person:0xdee9c
  @birth=#<Date: 4899437/2,0,2299161>,
  @blood=nil,
  @desc=nil,
  @email="shiina@mail.org",
  @group="friend",
  @name="Shiina",
  @phone=nil>,
 #<Person:0xde8e8
  @birth=nil,
  @blood=nil,
  @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.

show command-line properties
$ 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
example of command-line properties
$ kwalify -a genclass-ruby --module=My --include=Kwalify::HashInterface

'Kwalify::HashInterface' is a module which make object accessible like as Hash. It is defined in 'kwalify/util/hash-interface.rb'

3-1-2   Java Class Definition

generate java class definition
$ kwalify -a genclass-java -tf address-book.schema.yaml
generating ./AddressBook.java...done.
generating ./Person.java...done.
generating ./Group.java...done.
AddressBook.java : generated class definition
// 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 < 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 < 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_; }
}
Group.java : generated class definition
// 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_; }
}
Person.java : generated class definition
// 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_; }
}
ExampleAddressBook.java : example code of using *.java
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();
            }
        }
    }

}
result
$ 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.

show command-line properties
$ 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
example of command-line properties
$ kwalify -a genclass-java --package=com.example.my --implements=Serializable --basedir=src