treebank 2.0.0 → 2.1.0

data/README

@@ -3,7 +3,7 @@
 This module supports the creation, search, manipulation, and
 serialization of tree structures.
 
-Trees are implemented with Node objects.  Each Node has a writable
+Trees are implemented with Treebank::Node objects.  Each Node has a writable
 _label_ that may be any arbitrary object and a list of other child
 Node objects.  Node objects support breadth and depth first iteration.
 
@@ -16,23 +16,25 @@ Node objects.  Node objects support breadth and depth first iteration.
    irb(main):004:0> p.create_child!('child2')
    => <Treebank::Node child2 []>
 
-Node has a subclass ParentedNode that keeps track of the parent of the
+Node has a subclass Treebank::ParentedNode that keeps track of the parent of the
 given node and has methods for iterating up the ancestor tree.
 
 The default stringification method writes a node and all its children
 in a bracketed tree format.
 
    irb(main):005:0> puts p
-   (parent (child1) (child2))
-   => nil
+   (parent
+     (child1 )
+     (child2 ))
 
 Bracketed tree strings can be used to create Node trees.
 
    irb(main):006:0> t = Treebank::Node.from_s('(parent (child1) (child2))')
    => <Treebank::Node parent [child1 child2]>
    irb(main):007:0> puts t
-   (parent (child1) (child2))
-   => nil
+   (parent
+     (child1 )
+     (child2 ))
 
 The bracketed tree format is the one used by the Penn
 Treebank[http://www.cis.upenn.edu/~treebank/] Project to annonate
@@ -43,6 +45,7 @@ linguistic structure.
 * 1-0-0 ... First release
 * 1-1-0 ... Removed unnecessary fsa dependency from gemspec
 * 2-0-0 ... Changed from_s initialization
+* 2-1-0 ... Add indented multiline stringification; Add preterminal?
 
 = See Also
 

data/lib/treebank.rb

@@ -18,7 +18,7 @@
 # Treebank is the namespace that contains all tree-related functions.
 module Treebank
 
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
 
   # An enumerable list of tokens in a string representation of a tree
   #
@@ -41,11 +41,11 @@ module Treebank
     # The right delimiter
     attr_reader :right
 
-    # Constructor
+    # Create a stream of tokens from an enumerable source.
     #
-    # * source ... the string stream to tokenize
-    # * left ... left bracket symbol
-    # * right ... right bracket symbol
+    # _source_:: The string stream to tokenize
+    # _left_:: Left bracket symbol
+    # _right_:: Right bracket symbol
     def initialize(source, left = '(', right = ')')
       @source = source
       @left = left
@@ -58,16 +58,16 @@ module Treebank
       @s_regex = Regexp.new("\\#{@left}|\\#{@right}|[^#{cc_left}#{cc_right}]+")
     end
 
-    # Enumerate the tokens in the source
+    # Enumerate the tokens in the source.
     def each
       @source.each do |string|
         tokenize_string(string) {|token| yield token}
       end
     end
 
-    # Tokenize the source string
+    # Tokenize the source string.
     #
-    # * string ... the string to tokenize
+    # _string_:: The string to tokenize
     def tokenize_string(string)
       string.scan(@s_regex) do |bracket_delimited|
         bracket_delimited.split.each {|token| yield token}
@@ -78,7 +78,7 @@ module Treebank
 
   end # TokenStream
 
-  # A parser for string representations of trees
+  # A parser for string representations of trees.
   #
   # This class uses a simplified shift-reduce parser to convert a
   # string into a list of tree structures.
@@ -87,7 +87,7 @@ module Treebank
   #   => [<Treebank::Node A []>, <Treebank::Node B [C D]>]
   #
   # The string representation of a list of trees has the following BNF
-  # definition
+  # definition:
   #
   # * trees -> node*
   # * node -> (label? children)
@@ -105,10 +105,8 @@ module Treebank
   class Parser
     include Enumerable
 
-    # Constructor
-    #
-    # * tokens ... stream of tokens to be converted into trees
-    # * node_class ... class of node to create
+    # _tokens_:: Stream of tokens to be converted into trees
+    # _node_class_:: Class of node to create
     #
     # If _tokens_ is not a kind of TokenStream object it will be used
     # as the source stream of one.
@@ -118,7 +116,7 @@ module Treebank
       @node_class = node_class
     end
 
-    # Enumerate the tokens yielding trees
+    # Enumerate the tokens yielding trees.
     def each # :yields: tree
       parse = []
       @tokens.each do |token|
@@ -140,9 +138,9 @@ module Treebank
       raise "Extra #{@tokens.left}: #{parse}" if not parse.empty?
     end
 
-    # Convert the end of the parse list into a single node
+    # Convert the end of the parse list into a single node.
     #
-    # * node_parse ... a list of labels and nodes
+    # _node_parse_:: A list of labels and nodes
     def reduce(node_parse)
       node = @node_class.new
       # The first item in the list may be a label.
@@ -175,21 +173,19 @@ module Treebank
     class BFSIterator
       include Enumerable
 
-      # Constructor
-      #
-      # * node ... the start node of the enumeration
-      # * visit ... optional enumeration control procedure
+      # _node_:: The start node of the enumeration
+      # _visit_:: Optional enumeration control procedure
       #
       # The optional _visit_ argument can be used to control which
       # children are visited by this iterator.  If specified, it is
-      # called for every node, and only those nodes returning +true+
+      # called for every node, and only those nodes returning _true_
       # will be visited.
       def initialize(node, visit = nil)
         @node = node
         @visit = visit
       end
 
-      # Enumerate the nodes
+      # Enumerate the nodes.
       def each
         @agenda = [@node]
         while node = @agenda.shift
@@ -199,9 +195,9 @@ module Treebank
         end
       end
 
-      # Function that controls enumeration recursion
+      # Function that controls enumeration recursion.
       #
-      # * children ... a list of child nodes of the current node
+      # _children_:: A list of child nodes of the current node
       #
       # The only difference between the breadth-first and depth-first
       # searches is this function.
@@ -215,7 +211,7 @@ module Treebank
 
       # Function that controls enumeration recursion
       #
-      # * children ... a list of child nodes of the current node
+      # _children_:: A list of child nodes of the current node
       #
       # The only difference between the breadth-first and depth-first
       # searches is this function.
@@ -227,21 +223,21 @@ module Treebank
     # This node's label
     attr_accessor :label
 
-    # Constructor
+    # Create a node, specifying its label and its children's labels.
     #
-    # * label ... the label of this node
-    # * child_labels ... list of labels for children of this node
+    # _label_:: The label of this node
+    # _child_labels_:: List of labels for children of this node
     def initialize(label = nil, child_labels = [])
       @label = label
       @children = []
       child_labels.each {|label| create_child!(label)}
     end
 
-    # Read the tree from a bracketed string
+    # Read the tree from a bracketed string.
     #
-    # * s ... bracketed string
-    # * left ... left bracket symbol
-    # * right ... right bracket symbol
+    # _s_:: Bracketed string
+    # _left_:: Left bracket symbol
+    # _right_:: Right bracket symbol
     #
     # This function uses a Treebank::Parser object to create the tree from
     # _s_.
@@ -251,23 +247,58 @@ module Treebank
       nodes.first
     end
 
-    # Stringify
+    # This writes to a bracketed string representation that can be read by the
+    # Parser object.
     #
-    # This writes to a bracketed string representation that can be
-    # read by the Parser object.
-    def to_s
-      space = leaf? ? '':' '
-      "(#{label}#{space}#{@children.join(' ')})"
+    # _multiline_:: The string representation is in indented multiline format
+    #               if this is _true_ and on a single line if it is _false_.
+    def to_s(multiline = true)
+      if multiline
+        multiline_to_s(0, nil, nil)
+      else
+        "(#{label} #{preterminal? ? @children.first.label :
+                                    @children.join(' ')})"
+      end
+    end
+
+    # Returns a string representation of this node and its children over
+    # multiple lines with indenting.  This matches the format used in the Penn
+    # Treebank files.
+    #
+    # _indent_:: The number of spaces to indent this node in the output
+    # _parent_:: The node's parent
+    # _left_sibling_:: The node's left sibling
+    #
+    # This algorithm is based on the stringification algorithm in the Stanford
+    # Natural Language Parser.
+    def multiline_to_s(indent, parent, left_sibling)
+      # Insert a new line and indenting before this node as needed.  Stay on
+      # the same line if this is the top of the tree, if the parent label is
+      # empty or if this node and all preceeding siblings are preterminals.
+      parent_empty = (parent.nil? or parent.label.to_s.empty?)
+      left_preterm = (left_sibling.nil? or left_sibling.preterminal?)
+      same_line = (parent_empty or (preterminal? and left_preterm))
+      s = parent.nil? ? "" : (same_line ? " " : "\n" + " " * indent)
+      # Recursively stringify this node and its children.
+      if leaf? or preterminal?
+        s << to_s(false)
+      else
+        s << "(#{label}"
+        @children.each_with_index do |child, index|
+          left_sibling = index.zero? ? nil : @children[index-1]
+          s << child.multiline_to_s(indent+2, self, left_sibling)
+        end
+        s << ")"
+      end
+      s
     end
 
-    # Interactive stringification
+    # Show this node's label and the labels of its children.
     def inspect
       child_labels = @children.collect {|n| n.label}
       "<#{self.class} #{@label} [#{child_labels.join(' ')}]>"
     end
 
-    # Tree equivalence operator
-    #
     # If the other object is a tree and every node label in the
     # corresponding nodes of the two depth first enumerations match,
     # the trees are equivalent.
@@ -281,28 +312,22 @@ module Treebank
       mismatch.nil?
     end
 
-    # Create a new node and add it as a child of this node
-    #
-    # * label ... the label of a node to create
-    # * index ... optional insertion index
+    # Create a new node and add it as a child of this node.
     #
-    # If _index_ is not specified, the node is added to the end of the
-    # child list.
+    # _label_:: The label of a node to create
+    # _index_:: Optional insertion index.  If unspecified, the node is added
+    #           to the end of the child list.
     #
     # This function returns the added Node object.
     def create_child!(label, index = nil)
       attach_child!(self.class.new(label), index)
     end
 
-    # Attach an existing node as the child of this node
+    # Attach an existing node as the child of this node.
     #
-    # * node ... the node to add
-    # * index ... optional insertion index
-    #
-    # _node_ must be the same type as this node.
-    #
-    # If _index_ is not specified, the node is added to the end of the
-    # child list.
+    # _node_:: The node to add.  It must be the same type as this node.
+    # _index_:: Optional insertion index.    If unspecified, the node is added
+    #           to the end of the child list.
     #
     # This function returns the added Node object.
     def attach_child!(node, index = nil)
@@ -315,11 +340,9 @@ module Treebank
       node
     end
 
-    # Detach a child node
-    #
-    # * node ... the node to detach
+    # Removes the specfied node from this node's child list.
     #
-    # This removes the specfied node from this node's child list.
+    # _node_:: The node to detach
     def detach_child!(node)
       raise "#{node} is not a child of #{self}" if @children.delete(node).nil?
     end
@@ -331,7 +354,7 @@ module Treebank
     
     # Enumerate all the nodes beneath this one breadth-first
     #
-    # * visit ... optional enumeration control procedure
+    # _visit_:: Optional enumeration control procedure
     #
     # The _visit_ parameter is passed down to the BFSIterator.
     def each_breadth_first(visit = nil)
@@ -340,36 +363,43 @@ module Treebank
 
     # Enumerate all the nodes beneath this one depth-first
     #
-    # * visit ... optional enumeration control procedure
+    # _visit_:: Optional enumeration control procedure
     #
     # The _visit_ parameter is passed down to the DFSIterator.
     def each_depth_first(visit = nil)
       DFSIterator.new(self, visit)
     end
 
-    # Is this a leaf node?
+    # A leaf node has no children.
     def leaf?
       @children.empty?
     end
 
-    # Is this node empty?
+    # An empty node has no label and no children.
     def empty?
       @label.nil? and @children.empty?
     end
 
-    # All the leaf nodes beneath this node
+    # A preterminal node dominates a single leaf node.
+    def preterminal?
+      @children.length == 1 and @children.first.leaf?
+    end
+
+    # Return all the leaf nodes beneath this node.
     #
-    # * block ... an optional block to run on each leaf
+    # _block_:: An optional block to run on each leaf
     def leaves(&block)
       leaves = each_depth_first.find_all {|node| node.leaf?}
       leaves = leaves.collect {|leaf| block.call(leaf)} if not block.nil?
       leaves
     end
 
+    protected :multiline_to_s
+
   end # Node
 
 
-  # A Node in a Tree that can locate its parent
+  # A Node in a Tree that can locate its parent.
   #
   # The ParentedNode adds a pointer back to the parent node to
   # the Node class.
@@ -382,14 +412,12 @@ module Treebank
     class ParentIterator
       include Enumerable
 
-      # Constructor
-      #
-      # * node ... the start node of the enumeration
+      # _node_:: The start node of the enumeration
       def initialize(node)
         @node = node
       end
 
-      # Enumerate the ancestor chain
+      # Enumerate the ancestor chain.
       def each
         node = @node
         while not node.nil?
@@ -400,11 +428,12 @@ module Treebank
 
     end # ParentIterator
 
-    # Constructor
+    # Create a node specifying its parent, its label, and its children's
+    # labels.
     #
-    # * label ... the label of this node
-    # * child_labels ... list of labels for children of this node
-    # * parent ... the parent of this node
+    # _label_:: The label of this node
+    # _child_labels_:: List of labels for children of this node
+    # _parent_:: The parent of this node
     def initialize(label = nil, child_labels = [], parent = nil)
       super(label, child_labels)
       @parent = parent
@@ -423,17 +452,15 @@ module Treebank
       node.parent = nil
     end
 
-    # Set the parent of this node
-    #
-    # * parent ... the parent node
+    # Set the parent of this node.  This does not change the child list of
+    # _parent_.
     #
-    # This is a protected utility function.  It does not change the
-    # child list of _parent_.
+    # _parent_:: The parent node
     def parent=(parent)
       @parent = parent
     end
 
-    # Enumerate the ancestors of this node
+    # Enumerate the ancestors of this node.
     def each_parent
       ParentIterator.new(self)
     end

data/test/test_treebank.rb

@@ -155,19 +155,36 @@ module NodeTestMixin
 
   # Read from/to a string
   def test_stringify
-    s = '(S (NP (D (the)) (N (boy))) (VP (V (ran))))'
-    multiline_s = \
-'(S 
-     (NP 
-        (D (the))
-        (N (boy)))
-     (VP
-        (V (ran))))'
-    t = @node_class.from_s(s)
+    singleline = "(S (NP (D the) (N boy)) (VP (V ran)))"
+    multiline = "(S\n  (NP (D the) (N boy))\n  (VP (V ran)))"
+    t = @node_class.from_s(singleline)
     assert_kind_of @node_class, t, 'from_s'
-    assert_equal s, "#{t}", 'to_s'
-    m = @node_class.from_s(multiline_s)
-    assert_equal t, m, 'Single-/multi-line equal'
+    assert_equal t.to_s, t.to_s(true), 'to_s == to_s(true)'
+    assert_equal multiline, t.to_s(true), 'to_s(true)'
+    assert_equal singleline, t.to_s(false), 'to_s(false)'
+    m = @node_class.from_s(multiline)
+    assert_equal t, m, 'Single-/multi-line initialization equal'
+  end
+
+  # Read to and from a typical Wall Street Journal treebank string
+  def test_wsj_sentence_stringify
+    s = 
+"( (S
+    (NP-SBJ (CD Two) (VBG leading) (NN constitutional-law) (NNS experts))
+    (VP (VBD said)
+      (SBAR (-NONE- 0)
+        (S
+          (NP-SBJ (NNP President) (NNP Bush))
+          (VP (VBZ does) (RB n't)
+            (VP (VB have)
+              (NP (DT the) (JJ legal) (NN authority)
+                (S
+                  (NP-SBJ (-NONE- *))
+                  (VP (TO to)
+                    (VP (VB exercise)
+                      (NP (DT a) (JJ line-item) (NN veto)))))))))))
+    (. .)))"
+    assert_equal s, @node_class.from_s(s).to_s, 'Stringify WSJ sentence'
   end
 
   # Simple enumeration

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.8.11
+rubygems_version: 0.9.2
 specification_version: 1
 name: treebank
 version: !ruby/object:Gem::Version 
-  version: 2.0.0
-date: 2007-01-12 00:00:00 -08:00
+  version: 2.1.0
+date: 2007-12-11 00:00:00 -08:00
 summary: Treebank implements support for ordered n-ary branching tree structures
 require_paths: 
 - lib
@@ -25,6 +25,7 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
 platform: ruby
 signing_key: 
 cert_chain: 
+post_install_message: 
 authors: 
 - W.P. McNeill
 files: