weskit 0.3.0 → 0.3.1

data/README.markdown

@@ -2,7 +2,7 @@ Weskit [![Build Status](https://secure.travis-ci.org/f6p/weskit.png?branch=maste
 ====================================================================================================================
 
 Weskit gem consists of tools for interaction with Wesnoth Markup Langage and Wesnoth infrastructure.
-For more details please check out generated documentation and source code.
+For more documentation check out generated ri pages and examples directory.
 
 #### Modules
 

data/examples/builder.rb

@@ -0,0 +1,22 @@
+require 'rubygems'
+require 'weskit'
+
+include Weskit::WML
+
+unit = Root.new.build do
+  unit do
+    id 123
+    name 'Joe'
+    type :spearman
+
+    weapon do
+      name :spear
+      damage 10
+      description 'This is the weapon spearman usually uses.', :translatable => true
+    end
+  end
+end
+
+# Beware of fact that puts unit calls unit.to_ary instead of unit.to_str
+# so alwas use explicit conversion if you want string representation.
+puts unit.to_s

data/examples/formatter.rb

@@ -0,0 +1,24 @@
+require 'rubygems'
+require 'weskit'
+
+include Weskit::WML
+
+# Compared to builder example this one uses more
+# conservative approach to WML creation process.
+
+root = Root.new
+
+object  = Element.new :object
+object << Attribute.new(:name, 'orb')
+object << Attribute.new(:type, 'magic item')
+
+modificationno = Element.new :modification
+modification << Attribute.new(:hp, 100)
+
+object << modification
+root   << object
+
+# Set differend formatter globally.
+Formatter.default = Formatter.color
+
+puts root.to_s

data/examples/replay.rb

@@ -0,0 +1,15 @@
+require 'rubygems'
+require 'weskit'
+
+include Weskit::WML
+
+# For dealing with big messed up WML files use simple parser backend (specified as second parameter).
+replay = Parser.uri 'http://replays.wesnoth.org/1.10/20121112/2p__The_Freelands_Turn_16_(5909).gz', :simple
+
+puts replay[:mp_game_title], replay[:label], $/
+
+first_side = replay.replay_start.side[0]
+puts first_side[:user_description], first_side[:type], first_side[:faction_name], $/
+
+second_side = replay.replay_start.side[1]
+puts second_side[:user_description], second_side[:type], second_side[:faction_name], $/

data/lib/weskit/version.rb

@@ -1,3 +1,3 @@
 module Weskit
-  VERSION = '0.3.0'
+  VERSION = '0.3.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: weskit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-13 00:00:00.000000000 Z
+date: 2012-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: kpeg
@@ -88,8 +88,10 @@ files:
 - Gemfile
 - LICENSE
 - README.markdown
-- README.md
 - Rakefile
+- examples/builder.rb
+- examples/formatter.rb
+- examples/replay.rb
 - lib/weskit.rb
 - lib/weskit/mp.rb
 - lib/weskit/mp/adapter.rb

data/README.md

@@ -1,150 +0,0 @@
-# Weskit [![Build Status](https://secure.travis-ci.org/f6p/weskit.png?branch=master)](http://travis-ci.org/f6p/weskit)
-
-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](http://www.rubydoc.info/github/f6p/weskit/frames).
-
-## 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.
-
-```ruby
-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:
-
-```ruby
-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:
-
-```ruby
-  object_id 1
-  object_id {
-    name 'foo'
-  }
-```
-
-you can do this:
-
-```ruby
-  attribute(:object_id, 1)
-  element(:object_id) {}
-```
-
-id is a helper method (as it interfers with Object#id) that is equivalent to:
-
-```ruby
-  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:
-
-```
-[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:
-
-```ruby
-  root.a.b
-```
-
-This code takes advantage of method_missing as well and if you can't use
-it (because of method name conflicts) its equivalent can be used:
-
-```ruby
-  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.
-
-## 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.
-
-## Parser
-
-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.
-
-## Limitations
-
-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.
-
-## TODO
-
-Implement preprocessor directives as first class memebers
-that could be manipulated like any other WML node.