Add TaskList base, Filter, Updatable with tests

Author: mtodd

lib/task_list.rb

@@ -0,0 +1,169 @@
+require 'task_list/version'
+
+class TaskList
+  attr_reader :source
+
+  Incomplete  = "[ ]".freeze
+  Complete    = "[x]".freeze
+
+  # Pattern used to identify all task list items.
+  # Useful when you need iterate over all items.
+  ItemPattern = /
+    ^
+    (?:\s*[-+*]|(?:\d+\.))? # optional list prefix
+    \s*                     # optional whitespace prefix
+    (                       # checkbox
+      #{Regexp.escape(Complete)}|
+      #{Regexp.escape(Incomplete)}
+    )
+    (?=\s)                  # followed by whitespace
+  /x
+
+  # Used to filter out code fences from the source for comparison only.
+  # http://rubular.com/r/x5EwZVrloI
+  CodeFencesPattern = /
+    ^`{3}           # ```
+      (?:\s*\w+)?$  # followed by optional language
+    .+?             # code
+    ^`{3}$          # ```
+  /xm
+
+  # Used to filter out potential mismatches (items not in lists).
+  # http://rubular.com/r/OInl6CiePy
+  ItemsInParasPattern = /
+    ^
+    (
+      #{Regexp.escape(Complete)}|
+      #{Regexp.escape(Incomplete)}
+    )
+    .+
+    $
+  /x
+
+  # `source` is the Markdown source text with task list items following the
+  # syntax as follows:
+  #
+  #   - [ ] a task list item
+  #   - [ ] another item
+  #   - [x] a completed item
+  #
+  def initialize(source)
+    @source = source || ''
+  end
+
+  # Internal: the source cleaned of any potential false matches.
+  def cleaned_source
+    @cleaned_source ||= source.
+      gsub("\r", '').
+      gsub(CodeFencesPattern, '').
+      gsub(ItemsInParasPattern, '')
+  end
+
+  # Public: return the TaskList::Summary for this task list.
+  #
+  # Returns a TaskList::Summary.
+  def summary
+    @summary ||= TaskList::Summary.new(self)
+  end
+
+  # Public: The TaskList::Item objects for the source text.
+  #
+  # FIXME: not very dry with #update.
+  #
+  # Returns an Array of TaskList::Item objects.
+  def items
+    @items ||=
+      begin
+        items = []
+        lines = source.split("\n")
+        clean = cleaned_source.split("\n")
+
+        id = 0
+        lines.each do |line|
+          if match = item?(line) and clean.include?(line.chomp)
+            id += 1
+            items << Item.new(id, match, line)
+          end
+        end
+
+        items
+      end
+  end
+
+  # Public: updates the task list item's checked state in the source.
+  #
+  # The source is the original Markdown text where the task list item was
+  # identified.
+  #
+  # Returns a new TaskList with the updated source.
+  def update(item_id, checked)
+    item_id = Integer(item_id)
+    result  = source.split("\n")
+    clean   = cleaned_source.split("\n")
+
+    id = 0
+    result.map! do |line|
+      if item?(line) && clean.include?(line.chomp)
+        id += 1
+        # the item to update
+        if item_id == id
+          if checked
+            # swap incomplete for complete
+            line.sub! Incomplete, Complete
+          else
+            # and vice versa
+            line.sub! Complete,   Incomplete
+          end
+        end
+      end
+      line
+    end
+
+    self.class.new(result.join("\n"))
+  end
+
+  # Internal: shorthand for TaskList.item?
+  def item?(text)
+    self.class.item?(text)
+  end
+
+  # Public: analyze the text to determine if it is a task list item.
+  #
+  # Returns the matched item String, nil otherwise.
+  def self.item?(text)
+    text.chomp =~ ItemPattern && $1
+  end
+
+  class Item < Struct.new(:index, :checkbox_text, :source)
+    def complete?
+      checkbox_text == Complete
+    end
+  end
+
+  class Summary < Struct.new(:task_list)
+    # Internal: just use TaskList#items.
+    def items
+      task_list.items
+    end
+
+    # Public: returns true if there are any TaskList::Item objects.
+    def items?
+      item_count > 0
+    end
+
+    # Public: returns the number of TaskList::Item objects.
+    def item_count
+      items.size
+    end
+
+    # Public: returns the number of complete TaskList::Item objects.
+    def complete_count
+      items.select{ |i| i.complete? }.size
+    end
+
+    # Public: returns the number of incomplete TaskList::Item objects.
+    def incomplete_count
+      items.select{ |i| !i.complete? }.size
+    end
+  end
+end

lib/task_list/filter.rb

@@ -0,0 +1,160 @@
+# encoding: utf-8
+require 'html/pipeline'
+
+class TaskList
+  # Returns a `Nokogiri::DocumentFragment` object.
+  def self.filter(*args)
+    Filter.call(*args)
+  end
+
+  # TaskList filter replaces task list item markers (`[ ]` and `[x]`) with
+  # checkboxes, marked up with metadata and behavior.
+  #
+  # This should be run on the HTML generated by the Markdown filter, after the
+  # SanitizationFilter.
+  #
+  # Syntax
+  # ------
+  #
+  # Task list items must be in a list format:
+  #
+  # ```
+  # - [ ] incomplete
+  # - [x] complete
+  # ```
+  #
+  # Results
+  # -------
+  #
+  # The following keys are written to the result hash:
+  #   :task_list_items - An array of TaskList::Item objects.
+  class Filter < HTML::Pipeline::Filter
+
+    ListSelector = [
+      # select UL/OL
+      ".//li[starts-with(text(),'[ ]')]/..",
+      ".//li[starts-with(text(),'[x]')]/..",
+      # and those wrapped in Ps
+      ".//li/p[1][starts-with(text(),'[ ]')]/../..",
+      ".//li/p[1][starts-with(text(),'[x]')]/../.."
+    ].join(' | ').freeze
+
+    # Selects all LIs from a TaskList UL/OL
+    ItemSelector = ".//li".freeze
+
+    # Selects first P tag of an LI, if present
+    ItemParaSelector = ".//p[1]".freeze
+
+    attr_accessor :index
+
+    def initialize(*)
+      @index = 0
+      super
+    end
+
+    # Private: increments and returns the next item index Integer.
+    def next_index
+      @index += 1
+    end
+
+    # List of `TaskList::Item` objects that were recognized in the document.
+    # This is available in the result hash as `:task_list_items`.
+    #
+    # Returns an Array of TaskList::Item objects.
+    def task_list_items
+      result[:task_list_items] ||= []
+    end
+
+    # Renders the item checkbox in a span including the item index and state.
+    #
+    # Returns an HTML-safe String.
+    def render_item_checkbox(item)
+      %(<input type="checkbox"
+        class="task-list-item-checkbox"
+        data-item-index="#{item.index}"
+        #{'checked="checked"' if item.complete?}
+        data-item-complete="#{item.complete? ? 1 : 0}"
+        disabled="disabled"
+      />)
+    end
+
+    # Public: Marks up the task list item checkbox with metadata and behavior.
+    #
+    # NOTE: produces a string that, when assigned to a Node's `inner_html`,
+    # will corrupt the string contents' encodings. Instead, we parse the
+    # rendered HTML and explicitly set its encoding so that assignment will
+    # not change the encodings.
+    #
+    # See [this pull](https://github.com/github/github/pull/8505) for details.
+    #
+    # Returns the marked up task list item Nokogiri::XML::NodeSet object.
+    def render_task_list_item(item)
+      Nokogiri::HTML.fragment <<-html, 'utf-8'
+        <label>#{
+          item.source.sub(TaskList::ItemPattern, render_item_checkbox(item))
+        }</label>
+      html
+    end
+
+    # Public: Select all task lists from the `doc`.
+    #
+    # Returns an Array of Nokogiri::XML::Element objects for ordered and
+    # unordered lists.
+    def task_lists
+      doc.xpath(ListSelector)
+    end
+
+    # Public: filters a Nokogiri::XML::Element ordered/unordered list, marking
+    # up the list items in order to add behavior and include metadata.
+    #
+    # Modifies the provided node.
+    #
+    # Returns nothing.
+    def filter_list(node)
+      add_css_class(node, 'task-list')
+
+      node.xpath(ItemSelector).each do |li|
+        outer, inner =
+          if p = li.xpath(ItemParaSelector)[0]
+            [p, p.inner_html]
+          else
+            [li, li.inner_html]
+          end
+        if match = TaskList.item?(inner)
+          item = TaskList::Item.new(next_index, match, inner)
+          task_list_items << item
+
+          add_css_class(li, 'task-list-item')
+          outer.inner_html = render_task_list_item(item)
+        end
+      end
+    end
+
+    # Filters the source for task list items.
+    #
+    # Each item is wrapped in HTML to identify, style, and layer
+    # useful behavior on top of.
+    #
+    # Modifications apply to the parsed document directly.
+    #
+    # Returns nothing.
+    def filter!
+      task_lists.each do |node|
+        filter_list node
+      end
+    end
+
+    def call
+      filter!
+      doc
+    end
+
+    # Private: adds a CSS class name to a node, respecting existing class
+    # names.
+    def add_css_class(node, *new_class_names)
+      class_names = (node['class'] || '').split(' ')
+      class_names.concat(new_class_names)
+      node['class'] = class_names.uniq.join(' ')
+    end
+  end
+end

lib/task_list/updatable.rb

@@ -0,0 +1,25 @@
+# Include in models that need to update task list items.
+module TaskList::Updatable
+  # Public: updates the task list item to match `checked`.
+  #
+  #   - item:     the item index Integer number
+  #   - checked:  the Boolean checked value
+  #
+  # Returns true if updated.
+  def update_task_list(item, checked, key = instrument_task_list_update_key)
+    updated = TaskList.new(body).update(item, checked)
+    attribute = respond_to?(:description=) ? :description : :body
+    update_attributes! attribute => updated.source
+    instrument :update_task_list, :checked => checked,
+      :class_key => key if instrument_task_list_update?
+  end
+
+  # Internal: whether to instrument task list updates.
+  def instrument_task_list_update?
+    true
+  end
+
+  def instrument_task_list_update_key
+    self.class.name.underscore
+  end
+end