infoboxer 0.1.0

data/lib/infoboxer/tree/nodes.rb

@@ -0,0 +1,185 @@
+# encoding: utf-8
+module Infoboxer
+  module Tree
+    # List of nodes, which tries to be useful both as array, and as proxy
+    # to its contents.
+    #
+    # Many of Infoboxer's methods (especially {Navigation}'s) return
+    # `Nodes`, and in most cases you don't have to think about it. Same
+    # approach can be seen in jQuery or Nokogiri. You just do things
+    # like those:
+    #
+    # ```ruby
+    # document.sections.                  # => Nodes returned, 
+    #   select{|section|                  #    you can treat them as array, but also...
+    #     section.text.length > 1000      #
+    #   }.                                #
+    #   lookup(:Wikilink, text: /Chile/). #    ...use Infoboxer's methods
+    #   follow.                           #    ...even to receive lists of other pages
+    #   infoboxes.                        #    ...and use methods on them
+    #   fetch('leader_name1').            #    ...including those which only some node types support
+    #   map(&:text)                       #    ...and still have full-functioning Array
+    # ```
+    #
+    class Nodes < Array
+
+      # @!method select(&block)
+      #    Just like Array#select, but returns Nodes
+
+      # @!method reject(&block)
+      #    Just like Array#reject, but returns Nodes
+
+      # @!method sort_by(&block)
+      #    Just like Array#sort_by, but returns Nodes
+
+      # @!method flatten
+      #    Just like Array#flatten, but returns Nodes
+
+      # @!method compact
+      #    Just like Array#compact, but returns Nodes
+
+      # @!method -(other)
+      #    Just like Array#-, but returns Nodes
+
+      [:select, :reject, :sort_by, :flatten, :compact, :-].each do |sym|
+        define_method(sym){|*args, &block|
+          Nodes[*super(*args, &block)]
+        }
+      end
+
+      # Just like Array#first, but returns Nodes, if provided with `n` of elements.
+      def first(n = nil)
+        if n.nil?
+          super()
+        else
+          Nodes[*super(n)]
+        end
+      end
+
+      # Just like Array#last, but returns Nodes, if provided with `n` of elements.
+      def last(n = nil)
+        if n.nil?
+          super()
+        else
+          Nodes[*super(n)]
+        end
+      end
+
+      # Just like Array#map, but returns Nodes, **if** all map results are Node
+      def map
+        res = super
+        if res.all?{|n| n.is_a?(Node) || n.is_a?(Nodes)}
+          Nodes[*res]
+        else
+          res
+        end
+      end
+
+      # @!method prev_siblings
+      #   Previous siblings (flat list) of all nodes inside.
+      
+      # @!method next_siblings
+      #   Next siblings (flat list) of all nodes inside.
+
+      # @!method siblings
+      #   Siblings (flat list) of all nodes inside.
+
+      # @!method fetch
+      #   Fetches by name(s) variables for all templates inside.
+      #
+      #   See {Templates::Base#fetch} for explanation.
+      
+      [
+        :prev_siblings, :next_siblings, :siblings,
+        :fetch
+      ].each do |sym|
+        define_method(sym){|*args|
+          make_nodes map{|n| n.send(sym, *args)}
+        }
+      end
+
+      # By list of variable names, fetches hashes of `{name => value}`
+      # from all templates inside.
+      #
+      # See {Templates::Base#fetch_hash} for explanation.
+      #
+      # @return [Array<Hash>]
+      def fetch_hashes(*args)
+        map{|t| t.fetch_hash(*args)}
+      end
+
+      # Just join of all {Node#to_tree Node#to_tree} strings inside.
+      def to_tree
+        map(&:to_tree).join("\n")
+      end
+
+      def inspect
+        '[' + 
+          case
+          when count > MAX_CHILDREN
+            self[0...MAX_CHILDREN].map(&:inspect).join(', ') + ", ...#{count - MAX_CHILDREN} more nodes"
+          else
+            map(&:inspect).join(', ')
+          end + ']'
+      end
+
+      # Just join of all {Node#text Node#text}s inside.
+      def text
+        map(&:text).join
+      end
+
+      # Fetches pages by ALL wikilinks inside in ONE query to MediaWiki
+      # API.
+      #
+      # **NB**: for now, if there's more then 50 wikilinks (limitation for
+      # one request to API), Infoboxer **will not** try to do next page.
+      # It will be fixed in next releases.
+      #
+      # @return [Nodes<MediaWiki::Page>] It is still `Nodes`, so you
+      #   still can process them uniformely.
+      def follow
+        links = select{|n| n.respond_to?(:link)}.map(&:link)
+        return Nodes[] if links.empty?
+        page = first.lookup_parents(MediaWiki::Page).first or
+          fail("Not in a page from real source")
+        page.client or fail("MediaWiki client not set")
+        page.client.get(*links)
+      end
+
+      # Internal, used by {Parser}
+      def <<(node)
+        if node.kind_of?(Array)
+          node.each{|n| self << n}
+        elsif last && last.can_merge?(node)
+          last.merge!(node)
+        else
+          return if !node || node.empty?
+          node = Text.new(node) if node.is_a?(String)
+          super
+        end
+      end
+
+      # Internal, used by {Parser}
+      def strip
+        res = dup
+        res.pop while res.last.is_a?(Text) && res.last.raw_text =~ /^\s*$/
+        res.last.raw_text.sub!(/\s+$/, '') if res.last.is_a?(Text)
+        res
+      end
+
+      # Internal, used by {Parser}
+      def flow_templates
+        make_nodes map{|n| n.is_a?(Paragraph) ? n.to_templates? : n}
+      end
+
+      private
+
+      # @private For inspect shortening
+      MAX_CHILDREN = 5
+
+      def make_nodes(arr)
+        Nodes[*arr.flatten]
+      end
+    end
+  end
+end

data/lib/infoboxer/tree/paragraphs.rb

@@ -0,0 +1,122 @@
+# encoding: utf-8
+module Infoboxer
+  module Tree
+    # Base class for all "paragraph-level" nodes: {Paragraph}, {ListItem},
+    # {Heading}. It should be convenient to use it in {Navigation::Lookup::Node#_lookup Node#lookup}
+    # and similar methods like this:
+    #
+    # ```ruby
+    # page.lookup(:BaseParagraph) # => flat list of paragraph-levels
+    # ```
+    class BaseParagraph < Compound
+      def text
+        super.strip + "\n\n"
+      end
+    end
+
+    # @private
+    # Internal! Nothing to see here! Just YARD `@private` tag not working at class level
+    class EmptyParagraph < Node
+      def initialize(text)
+        @text = text
+      end
+
+      # should never be left in nodes flow
+      def empty?
+        true
+      end
+
+      attr_reader :text
+    end
+
+    # @private
+    # Internal! Nothing to see here! Just YARD `@private` tag not working at class level
+    module Mergeable
+      def can_merge?(other)
+        !closed? && self.class == other.class
+      end
+
+      def merge!(other)
+        if other.is_a?(EmptyParagraph)
+          @closed = true
+        else
+          [splitter, *other.children].each do |c|
+            @children << c
+          end
+          @closed = other.closed?
+        end
+      end
+    end
+    
+    # @private
+    # Internal! Nothing to see here! Just YARD `@private` tag not working at class level
+    class MergeableParagraph < BaseParagraph
+      include Mergeable
+
+      def can_merge?(other)
+        !closed? &&
+          (self.class == other.class || other.is_a?(EmptyParagraph))
+      end
+    end
+
+    # Represents plain text paragraph.
+    class Paragraph < MergeableParagraph
+      # Internal, used by {Parser} for merging
+      def splitter
+        Text.new(' ')
+      end
+
+      # Internal, used by {Parser}
+      def templates_only?
+        children.all?{|c| c.is_a?(Template) || c.is_a?(Text) && c.raw_text.strip.empty?}
+      end
+
+      # Internal, used by {Parser}
+      def to_templates
+        children.select(&filter(itself: Template))
+      end
+
+      # Internal, used by {Parser}
+      def to_templates?
+        templates_only? ? to_templates : self
+      end
+    end
+
+    # Represents horisontal ruler splitter. Rarely seen in modern wikis.
+    class HR < Node
+    end
+
+    # Represents heading.
+    #
+    # NB: min heading level in MediaWiki is 2, Heading level 1 (page
+    # title) is not seen in page flaw.
+    class Heading < BaseParagraph
+      def initialize(children, level)
+        super(children, level: level)
+      end
+
+      # @!attribute [r] level
+      #   @return [Fixnum] lesser numbers is more important heading
+      def_readers :level
+    end
+
+    # Represents preformatted text chunk.
+    #
+    # Paragraph-level thing, can contain many lines of text.
+    class Pre < MergeableParagraph
+      # Internal, used by {Parser}
+      def merge!(other)
+        if other.is_a?(EmptyParagraph) && !other.text.empty?
+          @children.last.raw_text << "\n" << other.text.sub(/^ /, '')
+        else
+          super
+        end
+      end
+
+      # Internal, used by {Parser} for merging
+      def splitter
+        Text.new("\n")
+      end
+    end
+  end
+end

data/lib/infoboxer/tree/ref.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+module Infoboxer
+  module Tree
+    # Represents footnote.
+    #
+    # Is not rendered in text flow, so, wikitext like
+    #
+    # ```
+    # ...pushed it back into underdevelopment,<ref>...tons of footnote text...</ref> though it nevertheless...
+    # ```
+    # when parsed and {Node#text} called, will return text like:
+    #
+    # ```
+    # ...pushed it back into underdevelopment, though it nevertheless...
+    # ```
+    # ...which most times is most reasonable thing to do.
+    class Ref < Compound
+      # @!attribute [r] name
+      def_readers :name
+
+      # Internal, used by {Parser}
+      def empty?
+        # even empty tag should not be dropped!
+        false
+      end
+      
+      def text
+        # because we want "clean" text,
+        # without references & footnotes messed up in it
+        '' 
+      end
+    end
+  end
+end

data/lib/infoboxer/tree/table.rb

@@ -0,0 +1,89 @@
+# encoding: utf-8
+require 'terminal-table'
+
+module Infoboxer
+  module Tree
+    # Represents table. Tables are complicated!
+    class Table < Compound
+      # Internal, used by {Parser}
+      def empty?
+        false
+      end
+
+      # All table rows.
+      def rows
+        children.select(&fltr(itself: TableRow))
+      end
+
+      # Table caption, if exists.
+      def caption
+        children.detect(&fltr(itself: TableCaption))
+      end
+
+      # For now, returns first table row, if it consists only of
+      # {TableHeading}s.
+      #
+      # FIXME: it can easily be several table heading rows
+      def heading_row
+        rows.first.children.all?(&call(matches?: TableHeading)) ?
+          rows.first : nil
+      end
+
+      # For now, returns all table rows except {heading_row}
+      def body_rows
+        rows.first.children.all?(&call(matches?: TableHeading)) ?
+          rows[1..-1] :
+          rows
+      end
+
+      def text
+        table = Terminal::Table.new
+        if caption
+          table.title = caption.text.sub(/\n+\Z/, '')
+        end
+        
+        if heading_row
+          table.headings = heading_row.children.map(&:text).
+            map(&call(sub: [/\n+\Z/, '']))
+        end
+
+        table.rows = body_rows.map{|r|
+          r.children.map(&:text).
+            map(&call(sub: [/\n+\Z/, '']))
+        }
+        table.to_s + "\n\n"
+      end
+    end
+
+    # Represents one table row.
+    class TableRow < Compound
+      alias_method :cells, :children
+
+      def empty?
+        false
+      end
+    end
+
+    # Represents any table cell, either {TableCell cell} or
+    # {TableHeading heading}.
+    #
+    # Can be used for lookups (same way as {BaseParagraph}).
+    class BaseCell < Compound
+      def empty?
+        false
+      end
+    end
+
+    # Represents ordinary table cell (`td` in HTML).
+    class TableCell < BaseCell
+    end
+
+    # Represents table heading cell (`th` in HTML).
+    class TableHeading < BaseCell
+    end
+
+    # Represents table caption.
+    class TableCaption < Compound
+    end
+  end
+end

data/lib/infoboxer/tree/template.rb

@@ -0,0 +1,82 @@
+# encoding: utf-8
+module Infoboxer
+  module Tree
+    # Template variable.
+    #
+    # It's basically the thing with name and ANY nodes inside, can be
+    # seen only as a direct child of {Template}.
+    class Var < Compound
+      attr_reader :name
+
+      def initialize(name, children = Nodes[])
+        super(children)
+        @name = name
+      end
+
+      # Internal, used by {Parser}
+      def empty?
+        false
+      end
+
+      protected
+
+      def descr
+        "#{clean_class}(#{name})"
+      end
+
+      def _eq(other)
+        other.name == name && other.children == children
+      end
+    end
+
+    # Wikipedia template.
+    #
+    # Templates are complicated! Also, they are useful.
+    #
+    # You'd need to understand them from [Wikipedia docs](https://en.wikipedia.org/wiki/Wikipedia:Templates)
+    # and then use much of Infoboxer's goodness provided with {Templates}
+    # separate module.
+    class Template < Compound
+      attr_reader :name, :variables
+
+      def initialize(name, variables = Nodes[])
+        super(Nodes[], extract_params(variables))
+        @name  = name 
+        @variables = Nodes[*variables].each{|v| v.parent = self}
+      end
+
+      # See {Node#to_tree}
+      def to_tree(level = 0)
+        '  ' * level + "<#{descr}>\n" +
+          variables.map{|var| var.to_tree(level+1)}.join
+      end
+
+      # Internal, used by {Parser}.
+      def empty?
+        false
+      end
+
+      protected
+
+      def _eq(other)
+        other.name == name && other.variables == variables
+      end
+
+      def clean_class
+        "Template[#{name}]"
+      end
+      
+      def extract_params(vars)
+        # NB: backports' to_h is cleaner but has performance penalty :(
+        Hash[*vars.
+          select{|v| v.children.count == 1 && v.children.first.is_a?(Text)}.
+          map{|v| [v.name, v.children.first.raw_text]}.flatten(1)]
+      end
+
+      def inspect_variables(depth)
+        variables.to_a[0..1].map{|name, var| "#{name}: #{var.inspect(depth+1)}"}.join(', ') +
+          (variables.count > 2 ? ', ...' : '')
+      end
+    end
+  end
+end