govspeak 1.3.0 → 1.4.0

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+## 1.4.0
+
+Added `#structured_headers` method to provide heirarchically structured
+headers extracted from markdown text heading tags.

data/lib/govspeak.rb

@@ -1,5 +1,6 @@
 require 'kramdown'
 require 'govspeak/header_extractor'
+require 'govspeak/structured_header_extractor'
 require 'govspeak/html_validator'
 require 'govspeak/html_sanitizer'
 require 'kramdown/parser/kramdown_with_automatic_external_links'
@@ -55,6 +56,10 @@ module Govspeak
       Govspeak::HeaderExtractor.convert(kramdown_doc).first
     end
 
+    def structured_headers
+      Govspeak::StructuredHeaderExtractor.new(self).call
+    end
+
     def preprocess(source)
       @@extensions.each do |title,regexp,block|
         source.gsub!(regexp) {|match|

data/lib/govspeak/structured_header_extractor.rb

@@ -0,0 +1,97 @@
+module Govspeak
+
+  StructuredHeader = Struct.new(:text, :level, :id, :headers) do
+    def top_level
+      2
+    end
+
+    def top_level?
+      level == top_level
+    end
+  end
+
+  class StructuredHeaderExtractor
+    def initialize(document)
+      @doc = document
+      @structured_headers = []
+      reset_stack
+    end
+
+    def call
+      headers_list.each do |header|
+        next if header_higher_than_top_level?(header)
+
+        if header.top_level?
+          add_top_level(header)
+        elsif header_at_same_level_as_prev?(header)
+          add_sibling(header)
+        elsif header_one_level_lower_than_prev?(header)
+          add_child(header)
+        elsif header_at_higher_level_than_prev?(header)
+          add_uncle_or_aunt(header)
+        else
+          next # ignore semantically invalid headers
+        end
+
+        stack.push(header)
+      end
+
+      structured_headers
+    end
+
+    attr_reader :doc, :stack, :structured_headers
+    private :doc, :stack, :structured_headers
+
+    def headers_list
+      @headers_list ||= doc.headers.map { |h|
+        StructuredHeader.new(h.text, h.level, h.id, [])
+      }
+    end
+
+    def add_top_level(header)
+      structured_headers.push(header)
+      reset_stack
+    end
+
+    def add_sibling(header)
+      stack.pop
+      stack.last.headers << header
+    end
+
+    def add_child(header)
+      stack.last.headers << header
+    end
+
+    def add_uncle_or_aunt(header)
+      pop_stack_to_level(header)
+      stack.last.headers << header
+    end
+
+    def header_higher_than_top_level?(header)
+      header.level < header.top_level
+    end
+
+    def header_at_same_level_as_prev?(header)
+      stack.last && stack.last.level == header.level
+    end
+
+    def header_one_level_lower_than_prev?(header)
+      # lower level means level integer is higher
+      stack.last && (stack.last.level - header.level == -1)
+    end
+
+    def header_at_higher_level_than_prev?(header)
+      # higher level means level integer is lower
+      stack.last && (stack.last.level > header.level)
+    end
+
+    def pop_stack_to_level(header)
+      times_to_pop = stack.last.level - header.level + 1
+      times_to_pop.times { stack.pop }
+    end
+
+    def reset_stack
+      @stack = []
+    end
+  end
+end

data/lib/govspeak/version.rb

@@ -1,3 +1,3 @@
 module Govspeak
-  VERSION = "1.3.0"
+  VERSION = "1.4.0"
 end

data/test/govspeak_structured_headers_test.rb

@@ -0,0 +1,103 @@
+require 'test_helper'
+
+class GovspeakStructuredHeadersTest < Test::Unit::TestCase
+
+  def document_body
+    %{
+## Heading 1
+
+## Heading 2
+
+### Sub heading 2.1
+
+### Sub heading 2.2
+
+#### Sub sub heading 2.2.1
+
+### Sub heading 2.3
+
+## Heading 3
+
+## Heading 4
+
+### Sub heading 4.1
+
+#### Sub heading 4.1.1
+
+##### Sub heading 4.1.1.1
+
+### Sub heading 4.2
+
+## Heading 5
+
+    }
+  end
+
+  def doc
+    @doc ||= Govspeak::Document.new(document_body)
+  end
+
+  def structured_headers
+    doc.structured_headers
+  end
+
+  test "Headings with no sub-headings have an empty headings collection" do
+    assert_empty structured_headers.first.headers
+  end
+
+  test "h2s are extracted as top level headings" do
+    expected_headings =  ["Heading 1", "Heading 2", "Heading 3", "Heading 4", "Heading 5"]
+
+    assert_equal expected_headings, structured_headers.map(&:text)
+  end
+
+  test "headings can have multiple sub-headings" do
+    expected_heading_texts = ["Sub heading 2.1", "Sub heading 2.2", "Sub heading 2.3"]
+    assert_equal expected_heading_texts, structured_headers[1].headers.map(&:text)
+  end
+
+  test "h3 following h2s are nested within them" do
+    assert_equal "Sub heading 2.1", structured_headers[1].headers[0].text
+  end
+
+  test "h4 following h3s are nested within them" do
+    assert_equal "Sub sub heading 2.2.1", structured_headers[1].headers[1].headers[0].text
+  end
+
+  test "h3 can follow an h5" do
+    assert_equal "Sub heading 4.2", structured_headers[3].headers[1].text
+  end
+
+  def invalid_document_body
+    %{
+### Invalid heading (h3)
+
+## Heading 1
+
+#### Invalid heading (h4)
+
+### Sub heading 1.1
+
+# Invalid heading (h1)
+
+    }
+  end
+
+  def invalid_doc
+    @invalid_doc ||= Govspeak::Document.new(invalid_document_body)
+  end
+
+  def invalid_structured_headers
+    invalid_doc.structured_headers
+  end
+
+  test "semantically invalid headers are ignored" do
+    assert_equal ["Heading 1"], invalid_structured_headers.map(&:text)
+
+    assert_equal ["Sub heading 1.1"], invalid_structured_headers.first.headers.map(&:text)
+  end
+
+  test "document with single h1 produces no headers" do
+    assert_equal [], Govspeak::Document.new("# Heading\n").structured_headers
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: govspeak
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-03 00:00:00.000000000 Z
+date: 2014-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: kramdown
@@ -140,13 +140,16 @@ files:
 - lib/govspeak/version.rb
 - lib/govspeak/html_sanitizer.rb
 - lib/govspeak/header_extractor.rb
+- lib/govspeak/structured_header_extractor.rb
 - README.md
+- CHANGELOG.md
 - Gemfile
 - Rakefile
 - test/govspeak_test_helper.rb
 - test/html_validator_test.rb
 - test/govspeak_test.rb
 - test/html_sanitizer_test.rb
+- test/govspeak_structured_headers_test.rb
 - test/test_helper.rb
 homepage: http://github.com/alphagov/govspeak
 licenses: []
@@ -162,7 +165,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3587010685364545485
+      hash: -3957971095230574253
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -171,7 +174,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3587010685364545485
+      hash: -3957971095230574253
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -183,4 +186,5 @@ test_files:
 - test/html_validator_test.rb
 - test/govspeak_test.rb
 - test/html_sanitizer_test.rb
+- test/govspeak_structured_headers_test.rb
 - test/test_helper.rb