Weskit Build Status

Weskit gem consists of tools for interaction with Wesnoth Markup Langage and Wesnoth infrastructure. Amog this tools Ruby classes representing WML objects and WML parser are most important as understanding them is the key to understaning any other stuff bundled. This README gives quick albeit incomplete overview of Weskit WML capabilities. For more information you have to check source code and generated documentation.

WML Containers

Elements in WML document dosn't have one parent. Instead of using arrays to store multiple WML objects create instance of Weskit::WML::Root. It will let you to call advanced features avaiable for other WML objects (like formatting, modification or searching for nodes) and it is enumerable as well.

require 'weskit'
include Weskit::WML

root = Root.new

While root object can store any type of WML item there are also containers for specific item types, for example to store attributes you want to use instance of Weskit::WML::Attributes. All WML containers include Weskit::WML::Mixins::Container module and some of them are subclasses of Weskit::WML::Items.

Altering objects

While you can push instances of WML objects to elements or containers and change identifiers or values manually there is a better way of doing that. Each container has build method that comes in handy.

For example:

root.build do
  side {
    id 1
    name 'First Side', :translatable => true
    unit {
      name :John
    }
  }
end

becomes:

[side]
  id=1
  name=_"First Side"
  [unit]
    name=John
  [/unit]
[/side]

Basically Builder takes advantage of method_missing and creates attributes or elements depending of method call parameters. If there is no block suppiled new attribute is created otherwise new element is added and contents of the block are evaluated in its context. Some of the calls may interfere with existing methods of Ruby objects and to solve that issue Builder provides attribute and element methods.

In such case instead of calling:

  object_id 1
  object_id {
    name 'foo'
  }

you can do this:

  attribute(:object_id, 1)
  element(:object_id) {}

id is a helper method (as it interfers with Object#id) that is equivalent to:

  attribute :id, value

Searching for objects

You can search WML elements and containers for nodes of specific type. For example lets say there is a object tree representing such WML structure:

[a]
  [b]
    [c]
      name=foo
    [/c]
  [/b]
  [b]
    name=bar
    [c]
    [/c]
  [/b]
[/a]

To get Weskit::WML::Elements container with references to all b elements you can do this:

  root.a.b

This code takes advantage of method_missing and if you can't do that (because of method name conflicts) equivalent code can be used:

  root.find(:a).find(:b)

as missing calls are delegated to find method. There is also find_recursively method that lets you to find elements using object criteria specified in block.

Object representation

Weskit::WML objects dosn't have any representation code coupled. Special class of objects called Formatters is used to handle their display. Most commonly you will use plain text representation (default formatter) or terminal friendly colorful version of it (color formatter). Most of WML objects provide formatter seter to replace formatter associated with them but you can as well change default formatter globally by calling Formatter.default= setter method.

Whatever representation you need (JSON, XML, YAML) creating new formaters shouldn't be hard. Take look at Weskit::WML::Formatters module for further reference on that matter.

WML Parser

Parser dosn't support preprocessor (at least yet). It provides two methods: string - for parsing strings and uri - for parsing files. uri method can load remote files as well as it transparently handles archive extraction. Parsing results in return of WML object tree with one Weskit::WML::Root as the top-most element.