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.


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


  name=_"First 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)

And oh well... Let's not forget that after all builder block is Ruby code so you can use any langague construct inside it as well.

Tree searching

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:


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


This code takes advantage of method_missing as well and if you can't use it that (because of method name conflicts) its equivalent can be used:


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.


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


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


Lack of preprocessor support as WML module is supposed to work with preprocessed files (at least for now). Preprocessor directives will be consumed as comments and that can lead to unexpected behaviour at times. For example if you have macro defined its contents will be added to parent element.


Implement preprocessor directives as first class memebers that could be manipulated like any other WML node.