smartdown 0.0.1

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (C) 2014 HM Government (Government Digital Service)
+
+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,204 @@
+# Smartdown
+
+Smartdown is an [external
+DSL](http://www.martinfowler.com/bliki/DomainSpecificLanguage.html) for
+representing a series of questions and logical rules which determine the order
+in which the questions are asked, according to user input.
+
+The language is designed to look like
+[Markdown](http://daringfireball.net/projects/markdown/), with some extensions
+to allow expression of logical rules, questions and conditional blocks of
+text.
+
+## Overview
+
+A single smartdown flow has a cover sheet, a set of questions, a set of
+outcomes and a set of test scenarios. Cover sheets, questions and outcomes are
+all types of node. A node represents a single user interaction (normally a web
+page, but in other media may be presented differently).
+
+Each question and outcome is held in a separate file. The name of the files
+are used to identify each question. Here's an example of the check-uk-visa
+flow:
+
+```
+-- check-uk-visa
+   |-- outcomes
+   |   |-- general_y.txt
+   |   |-- joining_family_m.txt
+   |   |-- joining_family_y.txt
+   |   |-- marriage.txt
+   |   |-- medical_n.txt
+   |   |-- medical_y.txt
+   |   `-- ...
+   |-- scenarios
+   |   |-- 1.test
+   |   |-- 2.test
+   |   `-- 3.test
+   |-- questions
+   |   |-- planning_to_leave_airport.txt
+   |   |-- purpose_of_visit.txt
+   |   |-- staying_for_how_long.txt
+   |   |-- what_passport_do_you_have.txt
+   `-- check-uk-visa.txt
+```
+
+## General node file syntax
+
+Each file has three parts: front-matter, a model definition, rules/logic. Only the model definition is required.
+
+* **front-matter** defines metadata in the form `property: value`
+* the **model definition** is a markdown-like block which defines a flow, question or outcome.
+* **rules/logic** defines 'next node' transition rules or other logic/predicate definitions
+
+## Cover sheet node
+
+The cover sheet starts the flow off, its filename should match the flow name, e.g. 'check-uk-visa.txt'.
+
+It has initial 'front matter' which defines metadata for the flow, including
+the first question. It then defines the copy for the cover sheet in markdown
+format. The h1 title is compulsory and used as the title for the smart answer.
+
+```
+meta_description: You may need a visa to come to the UK to visit, study or work.
+satisfies_need: 100982
+start_with: what_passport_do_you_have
+
+# Check if you need a UK visa
+
+You may need a visa to come to the UK to visit, study or work.
+```
+
+## Question nodes
+
+A question model definition has optional front matter, followed by a title and
+question type.
+
+The next sections define the various question types
+
+### Multiple choice
+
+```markdown
+# Will you pass through UK Border Control?
+
+You might pass through UK Border Control even if you don't leave the airport -
+eg your bags aren't checked through and you need to collect them before transferring
+to your outbound flight.
+
+* yes: Yes
+* no: No
+```
+
+### Country
+
+```markdown
+# What passport do you have?
+
+[country]
+```
+
+Presents a drop-down list of countries from the built-in list.
+
+Use front matter to exclude/include countries
+
+```
+exclude_countries: country1, country2
+include_countries: {country3: "Country 3", country4: "Country 4"}
+
+[country]
+```
+
+### Date
+
+```markdown
+# What is the baby’s due date?
+
+[d/m/y: -1...+1]
+```
+
+Asks for a specific date in the given range. Ranges can be expressed as a relative number of years or absolute dates in YYYY-MM-DD format.
+
+### Value
+
+```markdown
+[value]
+```
+
+Asks for an arbitrary text input.
+
+### Money
+
+```markdown
+[money]
+```
+
+Asks for a numerical input which can have decimals and optional thousand-separating commas.
+
+### Salary
+
+```markdown
+[salary]
+```
+
+Asks for salary which can be expressed as either a weekly or monthly money amount. The user chooses between weekly/monthly
+
+### Checkbox
+
+```markdown
+# Will you pass through UK Border Control?
+
+* [ ] yes: Yes
+* [ ] no: No
+```
+
+## Next node rules
+
+Logical rules for transitioning to the next node are defined in 'Next node' section. This is declared using a markdown h1 'Next node'.
+
+There are two constructs for defining rules:
+
+```
+# Next node
+
+* predicate => outcome
+```
+
+defines a conditional transition
+
+```
+# Next node
+
+* predicate1
+  * predicate2 => outcome1
+  * predicate3 => outcome2
+```
+
+defines nested rules.
+
+## Predicates
+
+```
+variable_name is 'string'
+```
+
+## Conditional blocks in outcomes
+
+## Processing model
+
+Each response to a question is assigned to a variable which corresponds to the question name (as determined by the filename).
+
+## Named predicates
+
+Named predicates
+
+## Plugin API
+
+A plugin API will be provided to allow more complex calculations to be defined
+in an external ruby class.
+
+## Software design
+
+The software design can be seen in this diagram:
+
+![Software design](https://raw.githubusercontent.com/alphagov/smartdown/master/doc/design.png)
+

data/bin/smartdown

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH << File.expand_path("../lib/", File.dirname(__FILE__))
+
+require 'smartdown/parser/directory_input'
+require 'smartdown/parser/flow_interpreter'
+require 'smartdown/engine'
+require 'pp'
+
+def usage
+  $stderr.puts "USAGE: <coversheet path> [responses...]"
+end
+
+if ARGV.size == 0
+  usage
+  exit(1)
+else
+  coversheet_path, *responses = ARGV
+  begin
+    input = Smartdown::Parser::DirectoryInput.new(coversheet_path)
+    flow = Smartdown::Parser::FlowInterpreter.new(input).interpret
+    engine = Smartdown::Engine.new(flow)
+    end_state = engine.process(responses)
+
+    puts "RESPONSES: " + end_state.get(:responses).join(" / ")
+    puts "PATH: " + (end_state.get(:path) + [end_state.get(:current_node)]).join(" -> ")
+    node = flow.node(end_state.get(:current_node))
+    puts "# #{node.title}\n\n"
+    node.questions.each do |q|
+      pp q.choices
+    end
+
+    puts node.body
+  rescue Smartdown::Parser::ParseError => error
+    $stderr.puts error
+    exit(1)
+  rescue Smartdown::Engine::IndeterminateNextNode => error
+    $stderr.puts error.message
+    exit(1)
+  end
+end

data/lib/smartdown/engine/errors.rb

@@ -0,0 +1,5 @@
+module Smartdown
+  class Engine
+    class IndeterminateNextNode < StandardError; end
+  end
+end

data/lib/smartdown/engine/predicate_evaluator.rb

@@ -0,0 +1,23 @@
+module Smartdown
+  class Engine
+    class PredicateEvaluator
+      def evaluate(predicate, state)
+        evaluator_for(predicate).call(state)
+      end
+
+    private
+      def evaluator_for(predicate)
+        case predicate
+        when Smartdown::Model::Predicate::Equality
+          ->(state) { state.get(predicate.varname) == predicate.expected_value }
+        when Smartdown::Model::Predicate::SetMembership
+          ->(state) { predicate.values.include?(state.get(predicate.varname)) }
+        when Smartdown::Model::Predicate::Named
+          ->(state) { state.get(predicate.name) }
+        else
+          raise "Unknown predicate type #{predicate.class}"
+        end
+      end
+    end
+  end
+end

data/lib/smartdown/engine/state.rb

@@ -0,0 +1,63 @@
+require 'set'
+
+module Smartdown
+  class Engine
+    class UndefinedValue < StandardError; end
+
+    class State
+      def initialize(data = {})
+        @data = duplicate_and_normalize_hash(data)
+        @data["path"] ||= []
+        @data["responses"] ||= []
+        @cached = {}
+        raise ArgumentError, "must specify current_node" unless has_key?("current_node")
+      end
+
+      def has_key?(key)
+        @data.has_key?(key.to_s)
+      end
+
+      def has_value?(key, expected_value)
+        has_key?(key) && fetch(key) == expected_value
+      end
+
+      def get(key)
+        value = fetch(key)
+        if value.respond_to?(:call)
+          evaluate(value)
+        else
+          value
+        end
+      end
+
+      def put(name, value)
+        State.new(@data.merge(name.to_s => value))
+      end
+
+      def keys
+        Set.new(@data.keys)
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && other.keys == self.keys && @data.all? { |k, v| other.has_value?(k, v) }
+      end
+
+    private
+      def duplicate_and_normalize_hash(hash)
+        ::Hash[hash.map { |key, value| [key.to_s, value] }]
+      end
+
+      def fetch(key)
+        if has_key?(key)
+          @data.fetch(key.to_s)
+        else
+          raise UndefinedValue
+        end
+      end
+
+      def evaluate(callable)
+        @cached[callable] ||= callable.call(self)
+      end
+    end
+  end
+end

data/lib/smartdown/engine/transition.rb

@@ -0,0 +1,65 @@
+require 'smartdown/engine/predicate_evaluator'
+require 'smartdown/engine/errors'
+
+module Smartdown
+  class Engine
+    class Transition
+      attr_reader :state, :node, :input
+
+      def initialize(state, node, input, options = {})
+        @state = state
+        @node = node
+        @input = input
+        @predicate_evaluator = options[:predicate_evaluator] || PredicateEvaluator.new
+      end
+
+      def next_node
+        first_matching_rule(next_node_rules.rules).outcome
+      end
+
+      def next_state
+        state_with_input
+          .put(:path, state.get(:path) + [node.name])
+          .put(:responses, state.get(:responses) + [input])
+          .put(node.name, input)
+          .put(:current_node, next_node)
+      end
+
+    private
+      attr_reader :predicate_evaluator
+
+      def next_node_rules
+        node.elements.find { |e| e.is_a?(Smartdown::Model::NextNodeRules) } or \
+          raise Smartdown::Engine::IndeterminateNextNode, "No next node rules defined for '#{node.name}'"
+      end
+
+      def first_matching_rule(rules)
+        catch(:match) do
+          throw_first_matching_rule_in(rules)
+        end
+      end
+
+      def throw_first_matching_rule_in(rules)
+        rules.each do |rule|
+          case rule
+          when Smartdown::Model::Rule
+            if predicate_evaluator.evaluate(rule.predicate, state_with_input)
+              throw(:match, rule)
+            end
+          when Smartdown::Model::NestedRule
+            if predicate_evaluator.evaluate(rule.predicate, state_with_input)
+              throw_first_matching_rule_in(rule.children)
+            end
+          else
+            raise "Unknown rule type"
+          end
+        end
+        raise Smartdown::Engine::IndeterminateNextNode
+      end
+
+      def state_with_input
+        state.put(node.name, input)
+      end
+    end
+  end
+end

data/lib/smartdown/engine.rb

@@ -0,0 +1,33 @@
+require 'smartdown/engine/transition'
+require 'smartdown/engine/state'
+
+module Smartdown
+  class Engine
+    attr_reader :flow
+
+    def initialize(flow)
+      @flow = flow
+    end
+
+    def default_start_state
+      Smartdown::Engine::State.new(
+        default_predicates.merge(
+          current_node: flow.name
+        )
+      )
+    end
+
+    def default_predicates
+      {
+        otherwise: ->(_) { true }
+      }
+    end
+
+    def process(responses, start_state = nil)
+      responses.inject(start_state || default_start_state) do |state, input|
+        current_node = flow.node(state.get(:current_node))
+        Transition.new(state, current_node, input).next_state
+      end
+    end
+  end
+end

data/lib/smartdown/model/element/markdown_heading.rb

@@ -0,0 +1,7 @@
+module Smartdown
+  module Model
+    module Element
+      MarkdownHeading = Struct.new(:content)
+    end
+  end
+end

data/lib/smartdown/model/element/markdown_paragraph.rb

@@ -0,0 +1,7 @@
+module Smartdown
+  module Model
+    module Element
+      MarkdownParagraph = Struct.new(:content)
+    end
+  end
+end

data/lib/smartdown/model/element/multiple_choice.rb

@@ -0,0 +1,7 @@
+module Smartdown
+  module Model
+    module Element
+      MultipleChoice = Struct.new(:name, :choices)
+    end
+  end
+end

data/lib/smartdown/model/element/start_button.rb

@@ -0,0 +1,7 @@
+module Smartdown
+  module Model
+    module Element
+      StartButton = Struct.new(:start_node)
+    end
+  end
+end

data/lib/smartdown/model/flow.rb

@@ -0,0 +1,24 @@
+module Smartdown
+  module Model
+    class Flow
+      attr_reader :name, :nodes
+
+      def initialize(name, nodes = [])
+        @name = name
+        @nodes = nodes
+      end
+
+      def coversheet
+        node(name)
+      end
+
+      def node(node_name)
+        @nodes.find {|n| n.name.to_s == node_name.to_s } || raise("Unable to find #{node_name}")
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && other.nodes == self.nodes && other.name == self.name
+      end
+    end
+  end
+end

data/lib/smartdown/model/front_matter.rb

@@ -0,0 +1,37 @@
+module Smartdown
+  module Model
+    class FrontMatter
+      def initialize(attributes = {})
+        @attributes = attributes
+      end
+
+      def method_missing(method_name, *args, &block)
+        if has_attribute?(method_name)
+          fetch(method_name)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        has_attribute?(method_name)
+      end
+
+      def has_attribute?(name)
+        @attributes.has_key?(name.to_s)
+      end
+
+      def fetch(name)
+        @attributes.fetch(name.to_s)
+      end
+
+      def to_hash
+        @attributes.dup
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && self.to_hash == other.to_hash
+      end
+    end
+  end
+end

data/lib/smartdown/model/nested_rule.rb

@@ -0,0 +1,5 @@
+module Smartdown
+  module Model
+    NestedRule = Struct.new(:predicate, :children)
+  end
+end

data/lib/smartdown/model/next_node_rules.rb

@@ -0,0 +1,5 @@
+module Smartdown
+  module Model
+    NextNodeRules = Struct.new(:rules)
+  end
+end

data/lib/smartdown/model/node.rb

@@ -0,0 +1,47 @@
+require 'smartdown/model/front_matter'
+
+module Smartdown
+  module Model
+    Node = Struct.new(:name, :elements, :front_matter) do
+      def initialize(name, elements, front_matter = nil)
+        super(name, elements, front_matter || Smartdown::Model::FrontMatter.new)
+      end
+
+      def questions
+        elements_of_kind(Smartdown::Model::Element::MultipleChoice)
+      end
+
+      def title
+        h1s.first ? h1s.first.content : ""
+      end
+
+      def markdown_blocks
+        elements_of_kind(Smartdown::Model::Element::MarkdownHeading, Smartdown::Model::Element::MarkdownParagraph)
+      end
+
+      def h1s
+        elements_of_kind(Smartdown::Model::Element::MarkdownHeading)
+      end
+
+      def body
+        markdown_blocks[1..-1].map { |block| as_markdown(block) }.compact.join("\n")
+      end
+
+    private
+      def elements_of_kind(*kinds)
+        elements.select {|e| kinds.any? {|k| e.is_a?(k)} }
+      end
+
+      def as_markdown(block)
+        case block
+        when Smartdown::Model::Element::MarkdownHeading
+          "# #{block.content}\n"
+        when Smartdown::Model::Element::MarkdownParagraph
+          block.content
+        else
+          raise "Unknown markdown block type '#{block.class.to_s}'"
+        end
+      end
+    end
+  end
+end

data/lib/smartdown/model/predicate/equality.rb

@@ -0,0 +1,7 @@
+module Smartdown
+  module Model
+    module Predicate
+      Equality = Struct.new(:varname, :expected_value)
+    end
+  end
+end

data/lib/smartdown/model/predicate/named.rb

@@ -0,0 +1,7 @@
+module Smartdown
+  module Model
+    module Predicate
+      Named = Struct.new(:name)
+    end
+  end
+end

data/lib/smartdown/model/predicate/set_membership.rb

@@ -0,0 +1,7 @@
+module Smartdown
+  module Model
+    module Predicate
+      SetMembership = Struct.new(:varname, :values)
+    end
+  end
+end

data/lib/smartdown/model/rule.rb

@@ -0,0 +1,5 @@
+module Smartdown
+  module Model
+    Rule = Struct.new(:predicate, :outcome)
+  end
+end

data/lib/smartdown/parser/base.rb

@@ -0,0 +1,35 @@
+require 'parslet'
+
+module Smartdown
+  module Parser
+    class Base < Parslet::Parser
+      rule(:eof) { any.absent? }
+      rule(:ws_char) { match('\s') }
+      rule(:space_char) { str(" ") }
+      rule(:non_ws_char) { match('\S') }
+      rule(:newline) { str("\r\n") | str("\n\r") | str("\n") | str("\r") }
+      rule(:line_ending) { eof | newline }
+
+      rule(:optional_space) { space_char.repeat }
+      rule(:some_space) { space_char.repeat(1) }
+      rule(:ws) { ws_char.repeat }
+      rule(:non_ws) { non_ws.repeat }
+
+      rule(:whitespace_terminated_string) {
+        non_ws_char >> (non_ws_char | space_char.repeat(1) >> non_ws_char).repeat
+      }
+
+      rule(:identifier) {
+        match('[a-zA-Z_0-9-]').repeat(1)
+      }
+
+      rule(:question_identifier) {
+        identifier >> str('?').maybe
+      }
+
+      rule(:bullet) {
+        match('[*-]')
+      }
+    end
+  end
+end