indentation-parser 0.0.1 → 1.0.0

data/README.md

@@ -1,8 +1,11 @@
-[![Build Status](https://secure.travis-ci.org/ssmm/indentation-parser.png)](http://travis-ci.org/ssmm/indentation-parser)
+_This is not complete yet! More to come in the next weeks, so stay tuned._
 
-# Indentation-Parser
+# Indentation-Parser 
 
-A parser for indented files.
+[![Build Status](https://secure.travis-ci.org/ssmm/indentation-parser.png)](http://travis-ci.org/ssmm/indentation-parser) 
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/ssmm/indentation-parser)
+
+Parses source code that defines context by indentation.
 
 ## How
 
@@ -37,13 +40,12 @@ You write a parser like so:
 
 ```ruby
 parser = IndentationParser.new do |p|
-  p.default do |parent, indentation, source|
+  p.default do |parent, source|
     node = OpenStruct.new
     parent.send("#{source}=", node)
     node
   end
-  
-  p.on /([^ ]+) : (.+)/ do |parent, indentation, source, captures|
+  p.on /([^ ]+) : (.+)/ do |parent, source, captures|
     node = captures[2]
     parent.send("#{captures[1]}=", node)
     node
@@ -51,7 +53,7 @@ parser = IndentationParser.new do |p|
 end
 ```
 
-Then you read your special syntax from a file, parse it and celebrate:
+Then you read your special syntax from a file and parse it:
 
 ```ruby
 source = IO.read("path/to/file")
@@ -60,4 +62,40 @@ output = parser.read(source, OpenStruct.new).value
 puts output.this.is.an.example
 puts output.this.is.the.second.one
 puts output.this.serves.as.another.example
-```
+```
+
+# Details
+
+## Hooks
+
+The following hooks are available:
+
+```ruby
+p.on /regex/ do |parent, source, captures|
+  #...
+end
+```
+
+```ruby
+p.default do |parent, source|
+  #...
+end
+```
+
+```ruby
+p.on_leaf /regex/ do |parent, source, captures|
+  #...
+end
+```
+
+```ruby
+p.on_leaf do |parent, source|
+  #...
+end
+```
+
+```ruby
+p.as_a_child_of Type do |parent, source|
+  #...
+end
+```

data/indentation-parser.gemspec

@@ -2,18 +2,19 @@
 require File.expand_path('../lib/indentation-parser/version', __FILE__)
 
 Gem::Specification.new do |gem|
+  gem.name          = "indentation-parser"
+  gem.version       = Indentation::Parser::VERSION
+  
   gem.authors       = ["Samuel Müller"]
   gem.email         = ["mueller.samu@gmail.com"]
-  gem.description   = %q{indentation-parser}
-  gem.summary       = %q{indentation-parser}
-  gem.homepage      = ""
+  gem.description   = %q{Parses source code that defines context by indentation.}
+  gem.summary       = gem.description
+  gem.homepage      = "https://github.com/ssmm/indentation-parser"
 
   gem.files         = `git ls-files`.split($\)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
-  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
-  gem.name          = "indentation-parser"
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})  
   gem.require_paths = ["lib"]
-  gem.version       = Indentation::Parser::VERSION
   
   gem.add_development_dependency "rspec", "~> 2.11"
 end

data/lib/indentation-parser.rb

@@ -18,43 +18,60 @@ class IndentationParser
   end
 
   def read text, root_value
-    
     root = IndentationParser::RootNode.new
-
     root.set_value root_value
-
     node_stack = [root]
     
     text.each_line do |line|
       line.chomp!
       next if line.length == 0 || line =~ /^\s*$/
+
       indentation, source = parse_line line
       new_node = IndentationParser::Node.new source, indentation
+      previous_node = node_stack.last
       
-      lastone = node_stack.last
-      
-      if new_node.indentation() - 1 == lastone.indentation #the current node is indented to the previous node
-        lastone.add new_node
-        handle_node lastone unless lastone.is_a? RootNode
-        node_stack.push new_node
-      elsif new_node.indentation == lastone.indentation #the current node is on the same level as the previous node
-        leaf = node_stack.pop
-        handle_leaf leaf
-        node_stack.last.add new_node
-        node_stack.push new_node
-      elsif new_node.indentation() - 1 > lastone.indentation #too large indentation -> raise an error
+      if new_node.indentation() - 1 == previous_node.indentation 
+        #the current node is indented to the previous node
+        handle_by_one_indentation previous_node, new_node, node_stack
+
+      elsif new_node.indentation == previous_node.indentation 
+        #the current node is on the same level as the previous node
+        handle_same_indentation new_node, node_stack
+
+      elsif new_node.indentation() - 1 > previous_node.indentation 
+        #too large indentation -> raise an error
         raise "ou neei"
-      else #indentation is less than previous node. Pop everything from stack until parent is found
-        leaf = node_stack.pop
-        handle_leaf leaf
-        (lastone.indentation - new_node.indentation).times do 
-          node_stack.pop          
-        end
-        node_stack.last.add new_node
-        node_stack.push new_node
+
+      else 
+        #indentation is less than previous node. 
+        #pop everything from stack until parent is found
+        handle_less_indentation previous_node, new_node, node_stack
       end
     end
     handle_leaf node_stack.last
     root
   end
+
+  def handle_by_one_indentation previous_node, new_node, node_stack
+    previous_node.add new_node
+    handle_node previous_node unless previous_node.is_a? RootNode
+    node_stack.push new_node
+  end
+
+  def handle_same_indentation new_node, node_stack
+    leaf = node_stack.pop
+    handle_leaf leaf
+    node_stack.last.add new_node
+    node_stack.push new_node
+  end
+
+  def handle_less_indentation previous_node, new_node, node_stack
+    leaf = node_stack.pop
+    handle_leaf leaf
+    (previous_node.indentation - new_node.indentation).times do 
+      node_stack.pop          
+    end
+    node_stack.last.add new_node
+    node_stack.push new_node
+  end
 end

data/lib/indentation-parser/handlers.rb

@@ -1,9 +1,13 @@
 class IndentationParser
 
+  def call_handler block, node    
+    block.call(node.parent.value, node.source)
+  end
+
   def execute_regex_handler node, regex, block
     captures = regex.match node.source
     if captures
-      node_value = block.call(node.parent.value, node.indentation, node.source, captures)
+      node_value = block.call(node.parent.value, node.source, captures)
       node.set_value node_value
       return true
     end
@@ -13,7 +17,7 @@ class IndentationParser
   def execute_child_of_handler node
     handler = @child_of_handlers[node.parent.value.class]
     if handler
-      node_value = handler.call node.parent.value, node.indentation, node.source
+      node_value = call_handler handler, node
       node.set_value node_value
       return true
     end
@@ -36,7 +40,7 @@ class IndentationParser
     
     handled = try_to_handle @node_handlers, node
     if not handled and @default
-      node_value = @default.call node.parent.value, node.indentation, node.source if @default
+      node_value = call_handler @default, node if @default
       node.set_value node_value
     end
   end
@@ -44,7 +48,7 @@ class IndentationParser
   def handle_leaf node
     handled = try_to_handle @leaf_handlers, node
     if not handled and @on_leaf
-      node_value = @on_leaf.call node.parent.value, node.indentation, node.source
+      node_value = call_handler @on_leaf, node
       node.set_value node_value
     else
       handle_node node

data/lib/indentation-parser/version.rb

@@ -1,5 +1,5 @@
 module Indentation
   module Parser
-    VERSION = "0.0.1"
+    VERSION = "1.0.0"
   end
 end

data/spec/readme_example_spec.rb

@@ -4,13 +4,12 @@ require 'ostruct'
 describe IndentationParser do
   it "does what is written in the readme" do
     parser = IndentationParser.new do |p|
-      p.default do |parent, indentation, source|
+      p.default do |parent, source|
         node = OpenStruct.new
         parent.send("#{source}=", node)
         node
       end
-      
-      p.on /([^ ]+) : (.+)/ do |parent, indentation, source, captures|
+      p.on /([^ ]+) : (.+)/ do |parent, source, captures|
         node = captures[2]
         parent.send("#{captures[1]}=", node)
         node
@@ -24,6 +23,70 @@ describe IndentationParser do
     output.this.is.an.example.should eq "First example"
     output.this.is.the.second.one.should eq "Second example"
     output.this.serves.as.another.example.should eq "Third example"
-
   end
-end
+end
+
+
+# ##### First block
+
+# ```ruby
+# p.default do |parent, indentation, source|
+#   node = OpenStruct.new
+#   parent.send("#{source}=", node)
+#   node
+# end
+# ```
+
+# This defines what the parser does with a line of code when no other hook is defined. The
+# parameters you get from the parser inside your block are:
+
+# - The `parent` node. This is the object you have set for an already parsed line.
+# - The `source`, basically the whole line the parser currently evaluates without indentation.
+
+# *Now, step by step:*
+
+# We define a new `OpenStruct` instance and store it in a variable called `node`.
+
+# Since we know that all parent objects are going to be `OpenStruct`s too, we set an attribute on
+# it. The name of the attribute is given by the `source` parameter.
+
+# Last but not least, we return the node. **This is very important!** In 
+# order to be able to pass the `parent` parameter to the block, the parser maintains an internal
+# node structure. Only if you pass the node as a return value, the parser can store it there!
+
+# ##### Second block
+
+# ```ruby
+# p.on /([^ ]+) : (.+)/ do |parent, indentation, source, captures|
+#   node = captures[2]
+#   parent.send("#{captures[1]}=", node)
+#   node
+# end
+# ```
+
+# The regular expression `/([^ ]+) : (.+)/` will match with a text that has the format 
+# `"text_without_spaces : Any text"`. Every time the parser comes along a line of code which
+# matches this expression, it will execute the block you provide. There is an additional parameter
+# you can use in this block:
+# - The `captures`, the result of matching the
+# [regular expression](http://www.ruby-doc.org/core-1.9.3/Regexp.html) to the source.
+
+# *Step by step:*
+
+# We assign the second capture, which, with the example source given, will be `"First example"` in
+# the very first case, to a local variable called `node`. 
+
+# Again, at this point, we know that our parent is an `OpenStruct`. We define an attribute on it, 
+# with the name taken from our captures object. This is what happens for each of the three cases:
+
+# ```ruby
+# #parent.send("#{captures[1]}=", node) translates to
+# parent.example = "First example"
+# parent.one = "Second example"
+# parent.example = "Third example"
+# ```
+
+# Actually, the last line of the second block is not required, since there will not be any child
+# to this node, so there is no block that would need the parent object as a parameter. You can
+# return it anyways, just for the sake of thoroughness.
+

data/spec/simple_spec.rb

@@ -3,16 +3,16 @@ require 'indentation-parser'
 describe IndentationParser do
   it "parses indented files" do
     parser = IndentationParser.new do |p|
-      p.default do |parent, indentation, source|
+      p.default do |parent, source|
         node = {}
         parent[source.to_sym] = node
         node
       end
       
-      p.on_leaf do |parent, indentation, source|
-        node = {}
-        parent[source.to_sym] = node
-        node
+      p.on_leaf do |parent, source|
+        parent[:leafs] = Array.new  unless parent[:leafs]
+        parent[:leafs] << source
+        source
       end
     end
     
@@ -22,22 +22,21 @@ describe IndentationParser do
     
     expected_hash = {
       :this => {
-        :structure => {},
         :is => {
           :crazy => {
-            :and => {}
+            :leafs => ["and"]
           }
         },
-        :weird => {}
+        :leafs => ["structure", "weird"]
       },
       :and => {
         :does => {
           :not => {
-            :make => {}
+            :leafs => ["make"]
           },
-          :any => {}
+          :leafs => ["any"]
         },
-        :sense => {}
+        :leafs => ["sense"]
       }
     }
     

data/spec/universe_spec.rb

@@ -10,39 +10,39 @@ describe IndentationParser do
   it "parses a .universe file" do
     parser = IndentationParser.new do |p|
       
-      p.on /planet = ([a-zA-Z]+)/ do |parent, indentation, source, captures|
+      p.on /planet = ([a-zA-Z]+)/ do |parent, source, captures|
         planet = Planet.new captures[1]
         planet.continents = []
         parent.planets << planet
         planet
       end
       
-      p.on /continent = ([a-zA-Z]+)/ do |parent, indentation, source, captures|
+      p.on /continent = ([a-zA-Z]+)/ do |parent, source, captures|
         continent = Continent.new captures[1]
         continent.countries = []
         parent.continents << continent
         continent
       end
       
-      p.on /country = ([a-zA-Z]+)/ do |parent, indentation, source, captures|
+      p.on /country = ([a-zA-Z]+)/ do |parent, source, captures|
         country = Country.new captures[1]
         parent.countries << country
         country
       end
       
-      p.on /population = ([0-9]+)/ do |parent, indentation, source, captures|
+      p.on /population = ([0-9]+)/ do |parent, source, captures|
         parent.population = captures[1].to_i
       end
       
-      p.on /currency = ([a-zA-Z]+)/ do |parent, indentation, source, captures|
+      p.on /currency = ([a-zA-Z]+)/ do |parent, source, captures|
         parent.currency = captures[1]
       end
       
-      p.on /specialities/ do |parent, indentation, source, captures|
+      p.on /specialities/ do |parent, source, captures|
         parent.specialities = []
       end      
       
-      p.as_a_child_of Array do |parent, indentation, source|
+      p.as_a_child_of Array do |parent, source|
         parent << source  
       end
       

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: indentation-parser
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-15 00:00:00.000000000 Z
+date: 2012-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -27,7 +27,7 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '2.11'
-description: indentation-parser
+description: Parses source code that defines context by indentation.
 email:
 - mueller.samu@gmail.com
 executables: []
@@ -52,7 +52,7 @@ files:
 - spec/readme_example_spec.rb
 - spec/simple_spec.rb
 - spec/universe_spec.rb
-homepage: ''
+homepage: https://github.com/ssmm/indentation-parser
 licenses: []
 post_install_message: 
 rdoc_options: []
@@ -75,7 +75,7 @@ rubyforge_project:
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: indentation-parser
+summary: Parses source code that defines context by indentation.
 test_files:
 - spec/material/an.example
 - spec/material/test.mylang