slaw 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a0da8d0d88cfd753f8ef854937248c8881440390
+  data.tar.gz: 0762a47f6b0bac65d4b3fe829bc2a4997f3b23f9
+SHA512:
+  metadata.gz: 4ab788b276cd06d1735bb859a1f7fa08820f9bf65b2c6282df65ea1fd2303cbd5b42433366a3a0b2a7a20dbe227e78cc6b5caa2ab3b5cb988d6c2a27097f05ce
+  data.tar.gz: 3882e5a3b292dfcd9adecb0b2077f9cb21a5d5e76e90402a09c77f146a1ec3acb0272649daf03cc64556864bfd5d8a921d873cbb20534c626542894a02218372

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+ruby '2.1.1'
+
+# Specify your gem's dependencies in slaw.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Greg Kempe
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,31 @@
+# Slaw
+
+Slaw is a lightweight library for rendering and generating Akoma Ntoso acts from plain text and PDF documents.
+It is used to power [openbylaws.org.za](http://openbylaws.org.za).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'slaw'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install slaw
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it ( http://github.com/longhotsummer/slaw/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+end

data/lib/slaw/act.rb

@@ -0,0 +1,243 @@
+module Slaw
+  # Wraps an AkomaNtoso 2.0 XML document describing an Act.
+  class Act
+    include Slaw::Namespace
+
+    # Allow us to jump from the XML document for an act to the
+    # Act instance itself
+    @@acts = {}
+
+    attr_accessor :doc, :meta, :body, :num, :year, :id_uri
+    attr_accessor :filename, :mtime
+
+    def self.for_node(node)
+      @@acts[node.document]
+    end
+
+    # Create a new instance
+    def initialize(filename=nil)
+      self.load(filename) if filename
+    end
+
+    # Load the XML from +filename+
+    def load(filename)
+      @filename = filename
+      @mtime = File::mtime(@filename)
+
+      File.open(filename) { |f| parse(f) }
+    end
+    
+    # Parse the XML contained in the file-like object +io+
+    def parse(io)
+      @doc = Nokogiri::XML(io)
+      @meta = @doc.at_xpath('/a:akomaNtoso/a:act/a:meta', a: NS)
+      @body = @doc.at_xpath('/a:akomaNtoso/a:act/a:body', a: NS)
+
+      @@acts[@doc] = self
+
+      extract_id
+    end
+
+    def extract_id
+      @id_uri = @meta.at_xpath('./a:identification/a:FRBRWork/a:FRBRuri', a: NS)['value']
+      empty, @country, type, date, @num = @id_uri.split('/')
+
+      # yyyy-mm-dd
+      @year = date.split('-', 2)[0]
+    end
+
+    def short_title
+      unless @short_title
+        node = @meta.at_xpath('./a:identification/a:FRBRWork/a:FRBRalias', a: NS)
+        if node
+          @short_title = node['value']
+        else
+          @short_title = "Act #{num} of #{year}"
+        end
+      end
+
+      @short_title
+    end
+
+    def url_path
+      "/#{@country}/acts/#{@year}/#{@num}/"
+    end
+
+    def url_file
+      "act-#{@year}-#{@num}"
+    end
+
+    # Has this act been amended?
+    def amended?
+      @doc.at_xpath('/a:akomaNtoso/a:act', a: NS)['contains'] != 'originalVersion'
+    end
+
+    # a list of LifecycleEvent objects for amendment events, in date order
+    def amendment_events
+      @meta.xpath('./a:lifecycle/a:eventRef[@type="amendment"]', a: NS).map do |event|
+        LifecycleEvent.new(event)
+      end.sort_by { |e| e.date }
+    end
+
+    # Mark this act as being amended by another act, either +act+
+    # or the details in +opts+:
+    #
+    #   :uri: uri of the amending act
+    #   :title: title of the amending act
+    #   :date: date of the amendment
+    #
+    # It is assumed that there can be only one amendment event on a particular
+    # date. An existing amendment on this date is overwritten.
+    def amended_by!(act, opts={})
+      if act
+        opts[:uri] ||= act.id_uri
+        opts[:title] ||= act.short_title
+        opts[:date] ||= act.publication['date']
+      end
+
+      date = opts[:date]
+      source_id = "amendment-#{date}"
+
+      # assume we now hold a single version and not the original version
+      @doc.at_xpath('/a:akomaNtoso/a:act', a: NS)['contains'] = 'singleVersion'
+
+      # add the lifecycle event
+      lifecycle = @meta.at_xpath('./a:lifecycle', a: NS)
+      if not lifecycle
+        lifecycle = @doc.create_element('lifecycle', source: "#this")
+        @meta.at_xpath('./a:publication', a: NS).after(lifecycle)
+      end
+
+      event = lifecycle.at_xpath('./a:eventRef[@date="' + date + '"][@type="amendment"]', a: NS)
+      if event
+        # clear up old event
+        src = @doc.at_css(event['source'])
+        src.remove if src
+      else
+        # new event
+        event = @doc.create_element('eventRef', type: 'amendment')
+        lifecycle << event
+      end
+
+      event['date'] = date
+      event['id'] = "amendment-event-#{date}"
+      event['source'] = '#' + source_id
+
+      # add reference
+      ref = @doc.create_element('passiveRef',
+                                id: source_id,
+                                href: opts[:uri],
+                                showAs: opts[:title])
+
+      @meta.at_xpath('./a:references/a:TLCTerm', a: NS).before(ref)
+    end
+
+    # Does this Act have parts?
+    def parts?
+      !parts.empty?
+    end
+
+    def parts
+      @body.xpath('./a:part', a: NS)
+    end
+
+    def chapters?
+      !chapters.empty?
+    end
+
+    def chapters
+      @body.xpath('./a:chapter', a: NS)
+    end
+    
+    def sections
+      @body.xpath('.//a:section', a: NS)
+    end
+
+    # The XML node representing the definitions section
+    def definitions
+      # try looking for the definition list
+      defn = @body.at_css('#definitions')
+      return defn.parent if defn
+
+      # try looking for the heading
+      defn = @body.at_xpath('.//a:section/a:heading[text() = "Definitions"]', a: NS)
+      return defn.parent if defn
+
+      nil
+    end
+
+    # The XML node representing the schedules document
+    def schedules
+      @doc.at_xpath('/a:akomaNtoso/a:components/a:component/a:doc[@name="schedules"]/a:mainBody', a: NS)
+    end
+
+    # Get a map from term ids to +[term, defn]+ pairs,
+    # where +term+ is the text term NS+defn+ is
+    # the XML node with the definition in it.
+    def term_definitions
+      terms = {}
+
+      @meta.xpath('a:references/a:TLCTerm', a: NS).each do |node|
+        # <TLCTerm id="term-affected_land" href="/ontology/term/this.eng.affected_land" showAs="affected land"/>
+
+        # find the point with id 'def-term-foo'
+        defn = @body.at_xpath(".//*[@id='def-#{node['id']}']", a: NS)
+        next unless defn
+
+        terms[node['id']] = [node['showAs'], defn]
+      end
+
+      terms
+    end
+
+    # Returns the publication element, if any.
+    def publication
+      @meta.at_xpath('./a:publication', a: NS)
+    end
+
+    # Has this by-law been repealed?
+    def repealed?
+      !!repealed_on
+    end
+
+    # The date on which this act was repealed, or nil if never repealed
+    def repealed_on
+      repeal_el = repeal
+      repeal_el ? Time.parse(repeal_el['date']) : nil
+    end
+
+    # The element representing the reference that caused the repeal of this
+    # act, or nil
+    def repealed_by
+      repeal_el = repeal
+      return nil unless repeal_el
+
+      source_id = repeal_el['source'].sub(/^#/, '')
+      @meta.at_xpath("./a:references/a:passiveRef[@id='#{source_id}']", a: NS)
+    end
+
+    # The XML element representing the repeal of this act, or nil
+    def repeal
+      # <lifecycle source="#this">
+      #   <eventRef id="e1" date="2010-07-28" source="#original" type="generation"/>
+      #   <eventRef id="e2" date="2012-04-26" source="#amendment-1" type="amendment"/>
+      #   <eventRef id="e3" date="2014-01-17" source="#repeal" type="repeal"/>
+      # </lifecycle>
+      @meta.at_xpath('./a:lifecycle/a:eventRef[@type="repeal"]', a: NS)
+    end
+
+    def manifestation_date
+      node = @meta.at_xpath('./a:identification/a:FRBRManifestation/a:FRBRdate[@name="Generation"]', a: NS)
+      node && node['date']
+    end
+
+    def nature
+      "act"
+    end
+
+    def inspect
+      "<#{self.class.name} @id_uri=\"#{@id_uri}\">"
+    end
+  end
+
+end

data/lib/slaw/bylaw.rb

@@ -0,0 +1,53 @@
+require 'slaw/act'
+
+module Slaw
+  # Wraps an AkomaNtoso XML document describing an Act classed as a By-Law
+  class ByLaw < Act
+
+    attr_accessor :region, :name
+
+    def extract_id
+      # /za/by-law/cape-town/2010/public-parks
+
+      @id_uri = @meta.at_xpath('./a:identification/a:FRBRWork/a:FRBRuri', a: NS)['value']
+      empty, @country, type, @region, date, @name = @id_uri.split('/')
+
+      # yyyy[-mm-dd]
+      @year = date.split('-', 2)[0]
+    end
+
+    # ByLaws don't have numbers, use their short-name instead
+    def num
+      name
+    end
+
+    def short_title
+      unless @short_title
+        node = @meta.at_xpath('./a:identification/a:FRBRWork/a:FRBRalias', a: NS)
+        if node
+          @short_title = node['value']
+        else
+          @short_title = "(Unknown)"
+        end
+
+        if amended? and not @short_title.end_with?("as amended")
+          @short_title = @short_title + " as amended"
+        end
+      end
+
+      @short_title
+    end
+
+    def url_path
+      "/#{@country}/by-law/#{@region}/#{@year}/#{@name}/"
+    end
+
+    def url_file
+      @name
+    end
+    
+    def nature
+      "by-law"
+    end
+  end
+end

data/lib/slaw/collection.rb

@@ -0,0 +1,32 @@
+require 'forwardable'
+
+module Slaw
+  # A collection of Act instances.
+  class DocumentCollection
+
+    include Enumerable
+    extend Forwardable
+
+    attr_accessor :items
+
+    def_delegators :items, :each, :<<, :length
+
+    def initialize(items=nil)
+      @items = items || []
+    end
+
+    # Find all XML files in +path+ and return
+    # a list of instances of +cls+.
+    def discover(path, cls=Slaw::Act)
+      for fname in Dir.glob("#{path}/**/*.xml")
+        @items << cls.new(fname)
+      end
+    end
+
+    # Try to find an act who's FRBRuri matches this one,
+    # returning nil on failure
+    def for_uri(uri)
+      return @items.find { |doc| doc.id_uri == uri }
+    end
+  end
+end

data/lib/slaw/elasticsearch.rb

@@ -0,0 +1,107 @@
+require 'elasticsearch'
+require 'log4r'
+
+module Slaw
+  # Support for indexing and search using elasticsearch
+  class ElasticSearchSupport
+    attr_accessor :es, :mapping, :index, :type, :base_url
+
+    def initialize(index, type, base_url, client_params={}, es=nil)
+      @es = es || create_client(client_params)
+
+      @ix = index
+      @type = type
+      @base_url = base_url
+
+      @mapping = {
+        frbr_uri: {type: 'string', index: 'not_analyzed'},
+        url: {type: 'string', index: 'not_analyzed'},
+        title: {type: 'string', analyzer: 'english'},
+        content: {type: 'string', analyzer: 'english'},
+        published_on: {type: 'date', format: 'dateOptionalTime'},
+        region: {type: 'string', index: 'not_analyzed'},
+        region_name: {type: 'string', index: 'not_analyzed'},
+        repealed: {type: 'boolean'},
+      }
+
+      @log = Log4r::Logger['Slaw']
+    end
+
+    def create_client(client_params)
+      Elasticsearch::Client.new(client_params)
+    end
+
+    def reindex!(docs, &block)
+      define_mapping!
+      index_documents!(docs, &block)
+    end
+
+    def index_documents!(docs, &block)
+      for doc in docs
+        id = doc.id_uri.gsub('/', '-')
+
+        data = {
+          frbr_uri: doc.id_uri,
+          url: @base_url + doc.id_uri,
+          title: doc.short_title,
+          content: doc.body.text,
+          region: doc.region,
+          published_on: doc.publication['date'],
+          repealed: doc.repealed?,
+        }
+
+        yield doc, data if block_given?
+
+        @log.info("Indexing #{id}")
+        @es.index(index: @ix, type: @type, id: id, body: data)
+      end
+    end
+
+    def define_mapping!
+      @log.info("Deleting index")
+      @es.indices.create(index: @ix) unless @es.indices.exists(index: @ix)
+
+      # delete existing mapping
+      unless @es.indices.get_mapping(index: @ix, type: @type).empty?
+        @es.indices.delete_mapping(index: @ix, type: @type) 
+      end
+
+      @log.info("Defining mappings")
+      @es.indices.put_mapping(index: @ix, type: @type, body: {
+        @type => {properties: @mapping}
+      })
+    end
+
+    def search(q, from=0, size=10)
+      @es.search(index: @ix, body: {
+        query: {
+          multi_match: {
+            query: q,
+            type: 'cross_fields',
+            fields: ['title', 'content'],
+          }
+        },
+        fields: ['frbr_uri', 'repealed', 'published_on', 'title', 'url', 'region_name'],
+        highlight: {
+          order: "score",
+          fields: {
+            content: {
+              fragment_size: 80,
+              number_of_fragments: 2,
+            },
+            title: {
+              number_of_fragments: 0, # entire field
+            }
+          },
+          pre_tags: ['<mark>'],
+          post_tags: ['</mark>'],
+        },
+        from: from,
+        size: size,
+        sort: {
+          '_score' => {order: 'desc'}
+        }
+      })
+    end
+  end
+end

data/lib/slaw/lifecycle_event.rb

@@ -0,0 +1,23 @@
+module Slaw
+  # An event in the lifecycle of an act
+  class LifecycleEvent
+    include Slaw::Namespace
+
+    # Date of the event
+    attr_accessor :date
+
+    # type of the event
+    attr_accessor :type
+
+    # the source of the event, an XML reference element
+    attr_accessor :source
+
+    def initialize(element)
+      @date = element['date']
+      @type = element['type']
+
+      source_id = element['source'][1..-1]
+      @source = element.document.at_xpath("//a:references/*[@id=\"#{source_id}\"]", a: NS)
+    end
+  end
+end

data/lib/slaw/logging.rb

@@ -0,0 +1,14 @@
+require 'log4r'
+
+module Slaw
+  module Logging
+    
+    # Get an instance to a logger configured for the class that includes it.
+    # This allows log messages to include the class name
+    def logger
+      return @logger if @logger
+      
+      @logger = Log4r::Logger[self.class.name] || Log4r::Logger.new(self.class.name)
+    end
+  end
+end

data/lib/slaw/namespace.rb

@@ -0,0 +1,7 @@
+module Slaw
+  module Namespace
+    NS = "http://www.akomantoso.org/2.0"
+  end
+
+  include Namespace
+end