rticles 0.1.0

data/README.md

@@ -0,0 +1,52 @@
+Rticles
+=======
+
+Rticles is a Rails plugin that allows for web-based editing of legal documents. It lets you create nested, numbered paragraphs, along with intra-document references that remain accurate as paragraphs are inserted, removed and moved.
+
+This is a technology test for [One Click Orgs](http://github.com/oneclickorgs/one-click-orgs/).
+
+License
+-------
+
+Rticles is licensed under the [GNU Affero General Public License, Version 3](http://www.fsf.org/licensing/licenses/agpl-3.0.html).
+
+    Rticles
+    Copyright (C) 2011, 2012 Circus Foundation
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as
+    published by the Free Software Foundation, either version 3 of the
+    License, or (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+Rticles incorporates work covered by the following copyright and permission notice:
+
+    activerecord
+
+    Copyright (c) 2004-2011 David Heinemeier Hansson
+
+    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/Rakefile

@@ -0,0 +1,30 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Rticles'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :default => :spec
+
+Bundler::GemHelper.install_tasks

data/lib/rticles.rb

@@ -0,0 +1,8 @@
+module Rticles
+end
+
+require 'rticles/version'
+require 'rticles/numbering'
+require 'rticles/document'
+require 'rticles/paragraph'
+require 'rticles/railtie'

data/lib/rticles/document.rb

@@ -0,0 +1,200 @@
+# encoding: UTF-8
+
+require 'yaml'
+
+module Rticles
+  class Document < ActiveRecord::Base
+    NAME_RE = /\A#rticles#name#([A-Za-z_]+) /
+    TOPIC_RE = /\A#rticles#topic#([A-Za-z_]+) /
+    CONTINUATION_RE = /\A#rticles#continue /
+    HEADING_RE = /\A#rticles#heading(#\d+|) /
+
+    has_many :paragraphs, :order => 'position'
+    has_many :top_level_paragraphs, :class_name => 'Paragraph', :order => 'position', :conditions => "parent_id IS NULL"
+
+    alias_method :children, :paragraphs
+
+    attr_accessor :insertions, :choices
+
+    after_initialize :after_initialize
+    def after_initialize
+      set_up_insertions
+      set_up_choices
+    end
+
+    def set_up_insertions
+      self.insertions ||= {}
+      self.insertions = insertions.with_indifferent_access
+    end
+
+    def set_up_choices
+      self.choices ||= {}
+      self.choices = choices.with_indifferent_access
+    end
+
+    def outline(options={})
+      options = options.with_indifferent_access
+      for_display = options[:for_display]
+
+      o = []
+      top_level_paragraphs.each do |tlp|
+        body = for_display ? tlp.body_for_display({:insertions => insertions, :choices => choices}.merge(options)) : tlp.body
+        if body
+          o.push(for_display ? tlp.body_for_display({:insertions => insertions, :choices => choices}.merge(options)) : tlp.body)
+          unless tlp.children.empty?
+            o.push(sub_outline(tlp, options))
+          end
+        end
+      end
+      o
+    end
+
+    def to_html
+      html = "<section>"
+      html += Rticles::Paragraph.generate_html(top_level_paragraphs,
+        :insertions => insertions,
+        :choices => choices,
+        :numbering_config => numbering_config
+      )
+      html += "</section>"
+      html.html_safe
+    end
+
+    def to_yaml
+      outline.to_yaml
+    end
+
+    def self.from_yaml(yaml)
+      parsed_yaml = YAML.load(yaml)
+      document = self.create
+
+      create_paragraphs_from_array(document, nil, parsed_yaml)
+
+      document
+    end
+
+    def self.create_paragraphs_from_array(document, parent, array)
+      array.each do |text_or_sub_array|
+        case text_or_sub_array
+        when String
+          name = nil
+          topic = nil
+          continuation = false
+          heading = nil
+
+          if name_match = text_or_sub_array.match(NAME_RE)
+            text_or_sub_array = text_or_sub_array.sub(NAME_RE, '')
+            name = name_match[1]
+          end
+
+          if topic_match = text_or_sub_array.match(TOPIC_RE)
+            text_or_sub_array = text_or_sub_array.sub(TOPIC_RE, '')
+            topic = topic_match[1]
+          end
+
+          if text_or_sub_array.match(CONTINUATION_RE)
+            text_or_sub_array = text_or_sub_array.sub(CONTINUATION_RE, '')
+            continuation = true
+          end
+
+          if heading_match = text_or_sub_array.match(HEADING_RE)
+            text_or_sub_array = text_or_sub_array.sub(HEADING_RE, '')
+            if heading_match[1].empty?
+              heading = 1
+            else
+              heading = heading_match[1].sub(/\A#/, '').to_i
+            end
+          end
+          document.paragraphs.create(
+            :parent_id => parent ? parent.id : nil,
+            :body => text_or_sub_array,
+            :name => name,
+            :topic => topic,
+            :heading => heading,
+            :continuation => continuation
+          )
+        when Array
+          paragraphs_relation = parent ? parent.children : document.paragraphs.select{|p| p.parent_id.nil?}
+          if paragraphs_relation.empty?
+            raise RuntimeError, "jump in nesting at: #{text_or_sub_array.first}"
+          end
+          create_paragraphs_from_array(
+            document,
+            paragraphs_relation.last,
+            text_or_sub_array
+          )
+        end
+      end
+    end
+
+    def paragraph_for_reference(raw_reference)
+      # TODO optimise
+      Rails.logger.debug("Finding raw reference: #{raw_reference}")
+      paragraphs.all.detect{|p| p.full_index == raw_reference}
+    end
+
+    def paragraph_numbers_for_topic(topic, consolidate=false)
+      relevant_paragraphs = paragraphs.where(:topic => topic)
+      relevant_paragraphs = relevant_paragraphs.for_choices(choices)
+      paragraph_numbers = relevant_paragraphs.map{|p| p.full_index(true, choices)}.select{|i| !i.nil?}.sort
+
+      if consolidate
+        consolidate_paragraph_numbers(paragraph_numbers)
+      else
+        paragraph_numbers.join(', ')
+      end
+    end
+
+    def numbering_config
+      @numbering_config ||= Rticles::Numbering::Config.new
+    end
+
+  protected
+
+    def consolidate_paragraph_numbers(numbers)
+      numbers = numbers.sort
+      consolidated_numbers = []
+      current_run = []
+      numbers.each do |n|
+        if current_run.empty? || is_adjacent?(current_run.last, n)
+          current_run.push(n)
+        else
+          if current_run.length == 1
+            consolidated_numbers.push(current_run[0])
+          else
+            consolidated_numbers.push("#{current_run[0]}–#{current_run[-1]}")
+          end
+          current_run = [n]
+        end
+      end
+      if current_run.length == 1
+        consolidated_numbers.push(current_run[0])
+      else
+        consolidated_numbers.push("#{current_run[0]}–#{current_run[-1]}")
+      end
+      consolidated_numbers.join(', ')
+    end
+
+    def is_adjacent?(a, b)
+      # TODO Make this smart enough to handle sub-numbers like '2.4', '2.6'
+      b.to_i == a.to_i + 1
+    end
+
+    def sub_outline(p, options={})
+      options = options.with_indifferent_access
+      for_display = options[:for_display]
+
+      o = []
+      p.children.each do |c|
+        body = for_display ? c.body_for_display({:insertions => insertions, :choices => choices}.merge(options)) : c.body
+        if body
+          o.push(body)
+          unless c.children.empty?
+            o.push(sub_outline(c, options))
+          end
+        end
+      end
+      o
+    end
+  end
+end

data/lib/rticles/generators/install_generator.rb

@@ -0,0 +1,18 @@
+module Rticles
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('../templates', __FILE__)
+
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def create_migration
+        migration_template 'create_documents_and_paragraphs.rb', 'db/migrate/create_documents_and_paragraphs.rb'
+      end
+    end
+  end
+end

data/lib/rticles/generators/templates/create_documents_and_paragraphs.rb

@@ -0,0 +1,24 @@
+class CreateDocumentsAndParagraphs < ActiveRecord::Migration
+  def self.up
+    create_table :documents do |t|
+      t.string 'title'
+      t.timestamps
+    end
+    create_table :paragraphs do |t|
+      t.text 'body'
+      t.integer 'position'
+      t.integer 'parent_id'
+      t.integer 'document_id'
+      t.integer 'heading'
+      t.boolean 'continuation'
+      t.string 'name'
+      t.string 'topic'
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :paragraphs
+    drop_table :documents
+  end
+end

data/lib/rticles/numbering.rb

@@ -0,0 +1,56 @@
+require 'roman-numerals'
+
+module Rticles
+  module Numbering
+    DECIMAL = :decimal
+    LOWER_ALPHA = :lower_alpha
+    LOWER_ROMAN = :lower_roman
+
+    def self.number_to_string(number, style)
+      case style
+      when DECIMAL
+        number.to_s
+      when LOWER_ALPHA
+        number_to_alpha(number)
+      when LOWER_ROMAN
+        RomanNumerals.to_roman(number).downcase
+      end
+    end
+
+    class Config
+      attr_accessor :separator, :innermost_only
+
+      def initialize
+        self.separator = '.'
+        @level_configs = []
+      end
+
+      def [](level)
+        @level_configs[level] ||= LevelConfig.new
+      end
+
+      class LevelConfig
+        attr_accessor :style, :format
+
+        def initialize
+          self.style = Rticles::Numbering::DECIMAL
+          self.format = '#'
+        end
+      end
+    end
+
+  protected
+
+    def self.number_to_alpha(number)
+      numerator = number
+      result = ''
+      while numerator > 0 do
+        modulo = (numerator - 1) % 26
+        result = (97 + modulo).chr + result
+        numerator = (numerator - modulo) / 26
+      end
+      result
+    end
+
+  end
+end

data/lib/rticles/paragraph.rb

@@ -0,0 +1,315 @@
+require 'acts_as_list'
+
+module Rticles
+  class Paragraph < ActiveRecord::Base
+    attr_accessible :body, :parent_id, :after_id, :position, :before_id, :heading, :continuation,
+      :name, :topic
+
+    belongs_to :document
+    belongs_to :parent, :class_name => 'Paragraph'
+    has_many :children, :class_name => 'Paragraph', :foreign_key => 'parent_id', :order => 'position', :dependent => :destroy
+
+    acts_as_list :scope => [:document_id, :parent_id]
+
+    scope :for_choices, lambda {|choices|
+        choices_condition = ["", {}]
+        choices.each do |k, v|
+          choices_condition[0] += "AND body NOT LIKE :#{k}"
+          choices_condition[1][k.to_sym] = "#rticles##{v ? 'false' : 'true'}##{k}%"
+        end
+        choices_condition[0].sub!(/\AAND /, '')
+        where(choices_condition)
+    }
+
+    before_create :set_document_id
+    def set_document_id
+      if parent
+        self.document_id ||= parent.document_id
+      end
+    end
+
+    attr_accessor :before_id, :after_id
+
+    after_create :set_parent_and_position
+    def set_parent_and_position
+      if before_id.present?
+        sibling = self.class.find(before_id)
+        self.update_attribute(:parent_id, sibling.parent_id)
+        insert_at(sibling.position)
+      elsif after_id.present?
+        sibling = self.class.find(after_id)
+        self.update_attribute(:parent_id, sibling.parent_id)
+        insert_at(self.class.find(after_id).position + 1)
+      end
+    end
+
+    def heading?
+      heading && heading > 0
+    end
+
+    def heading_level
+      ancestors.length + (heading ? heading : 0)
+    end
+
+    def level
+      ancestors.length + 1
+    end
+
+    def index(choices=nil)
+      return nil if heading? || continuation?
+
+      predecessors = higher_items.where(['(heading = 0 OR heading IS NULL) AND (continuation = ? OR continuation IS NULL)', false])
+
+      if choices.present?
+        predecessors = predecessors.for_choices(choices)
+      end
+
+      predecessors.count + 1
+    end
+
+    def full_index(recalculate=false, choices=nil, numbering_config=nil)
+      return nil if heading? || continuation?
+
+      return @full_index if @full_index && !recalculate
+
+      if numbering_config.nil?
+        numbering_config = Rticles::Numbering::Config.new
+      end
+
+      if numbering_config.innermost_only
+        @full_index = numbering_config[level].format.sub('#', Rticles::Numbering.number_to_string(index(choices), numbering_config[level].style))
+      else
+        @full_index = ancestors.unshift(self).reverse.map do |p|
+          numbering_config[p.level].format.sub('#', Rticles::Numbering.number_to_string(p.index(choices), numbering_config[p.level].style))
+        end
+        @full_index = @full_index.join(numbering_config.separator)
+      end
+    end
+
+    def ancestors
+      node = self
+      nodes = []
+      nodes.push(node = node.parent) while node.parent
+      nodes
+    end
+
+    def can_move_lower?
+      !!lower_item
+    end
+
+    def can_move_higher?
+      !!higher_item
+    end
+
+    def can_indent?
+      !!higher_item
+    end
+
+    def indent!
+      return unless can_indent?
+      new_parent_id = higher_item.id
+      remove_from_list
+      update_attribute(:parent_id, new_parent_id)
+      send(:assume_bottom_position)
+    end
+
+    def can_outdent?
+      !!parent_id
+    end
+
+    def outdent!
+      return unless can_outdent?
+      new_parent_id = parent.parent_id
+      new_position = parent.position + 1
+      reparent_lower_items_under_self
+      remove_from_list
+      update_attribute(:parent_id, new_parent_id)
+      insert_at(new_position)
+    end
+
+    def higher_items
+      return nil unless in_list?
+      acts_as_list_class.where(
+        "#{scope_condition} AND #{position_column} < #{(send(position_column).to_i).to_s}"
+      )
+    end
+
+    def lower_items
+      return nil unless in_list?
+      acts_as_list_class.where(
+        "#{scope_condition} AND #{position_column} > #{(send(position_column).to_i).to_s}"
+      )
+    end
+
+    def reparent_lower_items_under_self
+      return unless in_list?
+      acts_as_list_class.update_all(
+        "#{position_column} = (#{position_column} - #{position}), parent_id = #{id}", "#{scope_condition} AND #{position_column} > #{send(position_column).to_i}"
+      )
+    end
+
+    before_save :normalise_references
+    def normalise_references
+      return if body.blank?
+      raw_reference_re = /!(\d\.)*\d/
+      Rails.logger.debug("Body: #{body}")
+      self.body = body.gsub(raw_reference_re) do |match|
+        raw_reference = match.sub('!', '')
+        '#rticles#' + document.paragraph_for_reference(raw_reference).id.to_s
+      end
+    end
+
+    def body_for_display(options={})
+      options = options.with_indifferent_access
+
+      if options[:insertions]
+        @insertions = options[:insertions]
+      end
+
+      if options[:choices]
+        @choices = options[:choices]
+      end
+
+      with_meta_characters = options[:with_meta_characters] || false
+
+      result = resolve_choices(body)
+      return result if result.nil?
+
+      result = resolve_references(result, with_meta_characters)
+      result = resolve_insertions(result)
+
+      if options[:with_index] && full_index(true, choices, options[:numbering_config])
+        result = "#{full_index} #{result}"
+      end
+
+      result
+    end
+
+    def body_with_resolved_references(with_meta_characters=false)
+      resolve_references(body, with_meta_characters)
+    end
+
+    def resolve_references(string, with_meta_characters=false)
+      return string if string.blank?
+      normalised_reference_re = /#rticles#(\d+)/
+      string.gsub(normalised_reference_re) do |match|
+        normalised_reference = match.sub('#rticles#', '')
+        result = with_meta_characters ? '!' : ''
+        result += document.paragraphs.find(normalised_reference).full_index
+        result
+      end
+    end
+
+    def resolve_insertions(string)
+      return string if string.blank?
+      insertion_re = /#rticles#([A-Za-z_]+)/
+      string.gsub(insertion_re) do |match|
+        insertion_name = match.sub('#rticles#', '')
+        if insertions[insertion_name].present?
+          insertions[insertion_name]
+        else
+          "[#{insertion_name.humanize.upcase}]"
+        end
+      end
+    end
+
+    def resolve_choices(string)
+      choice_re = /\A#rticles#(true|false)#([A-Za-z_]+) /
+      match = string.match(choice_re)
+      return string if !match
+
+      choice_name = match[2]
+      choice_parameter = match[1]
+
+      if (choices[choice_name] && choice_parameter == 'true') || (!choices[choice_name] && choice_parameter == 'false')
+        string.sub(choice_re, '')
+      else
+        nil
+      end
+    end
+
+    def prepare_for_editing
+      self.body = body_with_resolved_references(true)
+      self
+    end
+
+    def self.generate_html(paragraphs, options={})
+      paragraph_groups = []
+      paragraphs.each do |paragraph|
+        if paragraph.continuation?
+          paragraph_groups.last.push(paragraph)
+        else
+          paragraph_groups.push([paragraph])
+        end
+      end
+      generate_html_for_paragraph_groups(paragraph_groups, options)
+    end
+
+  protected
+
+    def self.generate_html_for_paragraph_groups(paragraph_groups, options={})
+      previous_type = nil
+      html = paragraph_groups.inject("") do |memo, paragraph_group|
+        # FIXME: Don't generate HTML by interpolating into a string;
+        # use some standard library function that provides some safe
+        # escaping defaults, etc..
+        if paragraph_group.first.heading?
+          if previous_type == :paragraph
+            memo += "</ol>"
+          end
+          if paragraph_group.length == 1
+            memo += generate_html_for_paragraphs(paragraph_group, options)
+          else
+            memo += "<hgroup>#{generate_html_for_paragraphs(paragraph_group, options)}</hgroup>"
+          end
+          previous_type = :heading
+        else
+          unless previous_type == :paragraph
+            memo += "<ol>"
+          end
+          memo += "<li>#{generate_html_for_paragraphs(paragraph_group, options)}</li>"
+          previous_type = :paragraph
+        end
+        memo
+      end
+      if previous_type == :paragraph
+        html += "</ol>"
+      end
+    end
+
+    def self.generate_html_for_paragraphs(paragraphs, options={})
+      paragraphs.inject("") do |memo, paragraph|
+        body = paragraph.body_for_display({:with_index => true}.merge(options))
+        return memo if body.nil?
+
+        if paragraph.heading?
+          memo += "<h#{paragraph.heading_level}>#{body}</h#{paragraph.heading_level}>"
+        else
+          memo += body
+        end
+
+        if !paragraph.children.empty?
+          memo += generate_html(paragraph.children, options)
+        end
+        memo
+      end
+    end
+
+    def insertions
+      return @insertions.with_indifferent_access if @insertions
+      begin
+        (parent || document).insertions.with_indifferent_access
+      rescue NoMethodError
+        raise RuntimeError, "parent was nil when finding insertions; I am: #{self.inspect}"
+      end
+    end
+
+    def choices
+      if @choices
+        @choices.with_indifferent_access
+      else
+        {}.with_indifferent_access
+      end
+    end
+  end
+end