lunokhod 0.0.1.pre

data/.gitignore

@@ -0,0 +1,3 @@
+*.sw?
+.rbx
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - rbx-19mode
+  - jruby-19mode
+  - 1.9.3

data/CHANGELOG

@@ -0,0 +1,4 @@
+0.0.1.pre (2013-03-08)
+----------------------
+
+First public release

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2013 David Yip
+
+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

@@ -0,0 +1,65 @@
+1. Lunokhod
+
+Lunokhod is a set of tools for parsing and compiling Surveyor[1] surveys.
+
+2. Relationship to Surveyor
+
+Surveyor does not provide access to a survey parse tree.  It also does not
+expose any public hooks for compiling Surveyor surveys to any form except the
+form expected by Surveyor's ActionView partials and compatible views.
+
+Lunokhod is intended to be a more flexible design.  It provides tools to
+generate an AST of a survey, perform some basic verifications on it (e.g.
+checking for unresolvable or duplicate question references), and a compiler
+that provides hooks for various backends.  A backend that prints out the parse
+tree is provided as an example.  A backend that generates surveys as a Web page
+with Javascript providing dependency evaluation logic is in progress.
+
+Currently, Lunokhod is not at feature parity with Surveyor.  Nevertheless,
+the present state of Lunokhod is still useful for survey tasks where
+loading surveys into a Rails application is not necessary and/or
+time-consuming.  Tasks that generate products based on survey structure (e.g.
+generating or verifying translation files) often fall into this category.
+
+3. Development and usage
+
+You will need a Ruby 1.9 implementation; Lunokhod makes heavy use of Ruby
+1.9 features, such as BasicObject and fibers.  Lunokhod is known to work
+on Rubinius 2.0.0.rc1, JRuby 1.7.2, and Ruby 1.9.3.
+
+The short version:
+
+  $ bundle install
+  $ ruby bin/lunokhod-driver [SURVEYOR SURVEY]
+
+By default, lunokhod-driver will use the pretty-printer backend.  Read the
+backend and AST to see how to use the tree visitor and what properties you can
+access on each node.
+
+Survey data may be piped in over standard input:
+
+  $ cat kitchen_sink_survey.rb | bin/lunokhod-driver
+
+You can use the webpage backend by setting the BACKEND environment variable:
+
+  $ BACKEND=Webpage ruby bin/lunokhod-driver [SURVEY]
+
+Keep in mind, however, that the webpage backend is currently very incomplete.
+
+Lunokhod does not have an automated test suite, but should.
+
+4. Authorship and license
+
+Lunokhod was written by David Yip at NUBIC[2] when he wanted a faster way
+to work with Surveyor surveys.
+
+Lunokhod is released under the MIT license.  See LICENSE for details.
+
+5. Special thanks
+
+How to destroy angels_, Kimbra, Little Boots, The Reign of Kindo, Dot Dot Dot.
+
+[1]: https://github.com/NUBIC/surveyor
+[2]: http://projects.nubic.northwestern.edu/
+
+# vim:ts=2:sw=2:et:tw=78

data/Rakefile

@@ -0,0 +1,8 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec

data/TODO

@@ -0,0 +1,6 @@
+* Implement proper operator precedence for dependencies (see
+  lib/lunokhod/rule_parsing.rb)
+* Test suite
+* Webpage generator
+* Ruby program generator (to be used in tandem with the webpage for server-side
+  validation, querying, etc.)

data/bin/lunokhod-driver

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+
+require 'lunokhod/backends/debug'
+require 'lunokhod/backends/webpage'
+require 'lunokhod/version'
+require 'lunokhod'
+
+backend = Lunokhod::Backends.const_get(ENV['BACKEND'] || 'Debug')
+$stderr.puts "Lunokhod #{Lunokhod::VERSION} - backend: #{backend}"
+
+file = ARGV[0]
+
+data = file ? File.read(file) : $stdin.read
+
+p = Lunokhod::Parser.new(data, file || '(stdin)')
+p.parse
+
+ep = Lunokhod::ErrorReport.new(p.surveys)
+ep.run
+
+if ep.errors?
+  $stderr.puts ep
+  exit 1
+end
+
+b = backend.new
+c = Lunokhod::Compiler.new(p.surveys, b)
+c.compile
+b.write

data/kitchen_sink_survey.rb

@@ -0,0 +1,282 @@
+# encoding: UTF-8
+survey "Kitchen Sink survey" do
+  translations :es => 'translations/languages.es.yml',
+    :he => 'translations/languages.he.yml'
+
+  section_one "One" do
+    g_hello "Hello" do
+      q_name "What is your name?"
+      a_name :string, :help_text => "My name is..."
+    end
+  end
+
+  section "Basic questions" do
+    # A label is a question that accepts no answers
+    label "These questions are examples of the basic supported input types"
+
+    # A basic question with radio buttons
+    question_1 "What is your favorite color?", :pick => :one
+    answer "red"
+    answer "blue"
+    answer "green"
+    answer "yellow"
+    answer :other
+
+    # A basic question with checkboxes
+    # "question" and "answer" may be abbreviated as "q" and "a"
+    q_2 "Choose the colors you don't like", :pick => :any
+    a_1 "red"
+    a_2 "blue"
+    a_3 "green"
+    a_4 "yellow"
+    a :omit
+
+    # A dependent question, with conditions and rule to logically join them
+    # the question's reference identifier is "2a", and the answer's reference_identifier is "1"
+    # question reference identifiers used in conditions need to be unique on a survey for the lookups to work
+    q_2a "Please explain why you don't like this color?"
+    a_1 "explanation", :text, :help_text => "Please give an explanation for each color you don't like"
+    dependency :rule => "A or B or C or D"
+    condition_A :q_2, "==", :a_1
+    condition_B :q_2, "==", :a_2
+    condition_C :q_2, "==", :a_3
+    condition_D :q_2, "==", :a_4
+
+    # A dependant question demonstrating the count operator. The
+    # dependency condition checks the answer count for the referenced question.
+    # It understands conditions of the form count> count< count>= count<=
+    # count!=
+    q_2b "Please explain why you dislike so many colors?"
+    a_1 "explanation", :text
+    dependency :rule => "Z"
+    condition_Z :q_2, "count>2"
+
+    # When :pick isn't specified, the default is :none (no checkbox or radio button)
+    q_montypython3 "What... is your name? (e.g. It is 'Arthur', King of the Britons)"
+    a_1 :string
+
+    # Dependency conditions can refer to any value, not just answer_id. An answer_reference still needs to be specified, to know which answer you would like to check
+    q_montypython4 "What... is your quest? (e.g. To seek the Holy Grail)"
+    a_1 :string
+    dependency :rule => "A"
+    condition_A :q_montypython3, "==", {:string_value => "It is 'Arthur', King of the Britons", :answer_reference => "1"}
+
+    # http://www.imdb.com/title/tt0071853/quotes
+    q_montypython5 "What... is the air-speed velocity of an unladen swallow? (e.g. What do you mean? An African or European swallow?)"
+    a_1 :string
+    dependency :rule => "A"
+    condition_A :q_montypython4, "==", {:string_value => "To seek the Holy Grail", :answer_reference => "1"}
+
+    label "Huh? I-- I don't know that! Auuuuuuuugh!"
+    dependency :rule => "A"
+    condition_A :q_montypython5, "==", {:string_value => "What do you mean? An African or European swallow?", :answer_reference => "1"}
+
+    q_cooling_1 "How do you cool your home?", :pick => :one
+    a_1 "Fans"
+    a_2 "Window AC"
+    a_3 "Central AC"
+    a_4 "Passive"
+
+    # When using !=, also use count>0 if you want to make sure the user responds
+    q_cooling_2 "How much does it cost to run your non-passive cooling solutions? (This question hidden until you respond 'How do you cool your home?')"
+    dependency :rule => "A and B"
+    condition_A :q_cooling_1, "!=", :a_4
+    condition_B :q_cooling_1, "count>0"
+    a_1 "$", :float
+
+    # Using != alone means the dependent question is shown by default
+    label "Please consider passive cooling solutions (This question always shown, unless you respond 'Passive')"
+    dependency :rule => "A"
+    condition_A :q_cooling_1, "!=", :a_4
+
+    # Surveys, sections, questions, groups, and answers all take the following reference arguments
+    # :reference_identifier   # usually from paper
+    # :data_export_identifier # data export
+    # :common_namespace       # maping to a common vocab
+    # :common_identifier      # maping to a common vocab
+    q "Get me started on an improv sketch", :reference_identifier => "improv_start", :data_export_identifier => "i_s", :common_namespace => "sketch comedy questions", :common_identifier => "get me started"
+    a "who", :string
+    a "what", :string
+    a "where", :string
+
+    # Various types of responses can be accepted, and validated
+    q "How many pets do you own?"
+    a :integer
+    validation :rule => "A"
+    condition_A ">=", :integer_value => 0
+
+    # Surveys, sections, questions, groups, and answers also take a custom css class for covenience in custom styling
+    q "What is your address?", :custom_class => 'address'
+    a :text, :custom_class => 'mapper'
+    # validations can use regexp values
+    validation :rule => "A"
+    condition_A "=~", :regexp => "[0-9a-zA-z\. #]"
+
+    # Questions, groups, and answers take a custom renderer (a partial in the application's views dir)
+    # defaults are "/partials/question_group", "/partials/question", "/partials/answer", so the custom renderers should have a different name
+    q "Pick your favorite date AND time" #, :custom_renderer => "/partials/custom_question"
+    a :datetime
+
+    q_time_lunch "What time do you usually take a lunch break?"
+    a_1 :time
+
+    q "When would you like to meet for dinner?"
+    a :date
+
+    # Sliders deprecate to select boxes when javascript is off
+    # Valid Ruby code may be used to shorten repetitive tasks
+    q "Adjust the slider to reflect your level of awesomeness", :pick => :one, :display_type => :slider
+    (1..10).to_a.each{|num| a num.to_s}
+
+    q "How much do you like Ruby?", :pick => :one, :display_type => :slider
+    ["not at all", "a little", "some", "a lot", "a ton"].each{|level| a level}
+
+    # The "|" pipe is used to place labels before or after the input elements
+    q "How much money do you want?"
+    a "$|USD", :float
+
+    # Questions may be grouped
+    group "How much oil do you use per day?", :display_type => :inline do
+      q "Quantity"
+      a :float
+
+      q "Unit", :pick => :one, :display_type => :dropdown
+      a "Barrels"
+      a "Gallons"
+      a "Quarts"
+    end
+
+    q "Choose your Illinois county", :pick => :one, :display_type => :dropdown
+    ["Adams","Alexander","Bond", "Boone",
+        "Brown","Bureau","Calhoun","Carroll","Cass",
+        "Champaign", "Christian", "Clark","Clay",
+        "Clinton", "Coles", "Cook", "Crawford","Cumberland","DeKalb",
+        "De Witt","Douglas","DuPage","Edgar", "Edwards",
+        "Effingham","Fayette", "Ford","Franklin","Fulton",
+        "Gallatin","Greene", "Grundy", "Hamilton","Hancock",
+        "Hardin","Henderson","Henry","Iroquois","Jackson",
+        "Jasper", "Jefferson","Jersey","Jo Daviess","Johnson",
+        "Kane","Kankakee","Kendall","Knox", "La Salle",
+        "Lake", "Lawrence", "Lee","Livingston","Logan",
+        "Macon","Macoupin","Madison","Marion","Marshall", "Mason",
+        "Massac","McDonough","McHenry","McLean","Menard",
+        "Mercer","Monroe", "Montgomery","Morgan","Moultrie",
+        "Ogle","Peoria","Perry","Piatt","Pike","Pope",
+        "Pulaski","Putnam","Randolph","Richland","Rock Island",
+        "Saline","Sangamon","Schuyler","Scott","Shelby",
+        "St. Clair","Stark", "Stephenson","Tazewell","Union",
+        "Vermilion","Wabash","Warren","Washington","Wayne",
+        "White","Whiteside","Will","Williamson","Winnebago","Woodford"].each{ |county| a county}
+
+    # When an is_exclusive answer is checked, it unchecks all other options and disables them (using Javascript)
+    q "Choose your favorite meats", :display_type => :inline, :pick => :any
+    a "Chicken"
+    a "Pork"
+    a "Beef"
+    a "Shellfish"
+    a "Fish"
+    a "I don't eat meats!!!", :is_exclusive => true
+
+    q "All out of ideas for questions?", :pick => :one, :display_type => :inline
+    a "yes"
+    a "maybe"
+    a "no"
+    a "I don't know"
+  end
+
+  section "Complicated questions" do
+
+    # Grids are useful for repeated questions with the same set of answers, which are specified before the questions
+    grid "Tell us how often do you cover these each day" do
+      a "1"
+      a "2"
+      a "3"
+      q "Head", :pick => :one
+      q "Knees", :pick => :one
+      q "Toes", :pick => :one
+    end
+
+    # "grid" is a shortcut for group with :display_type => :grid
+    # The answers will be repeated every 10 rows, but long grids aren't recommended as they are generally tedious
+    grid "Tell us how you feel today day" do
+      a "-2"
+      a "-1"
+      a "0"
+      a "1"
+      a "2"
+      q "down|up" , :pick => :one
+      q "sad|happy", :pick => :one
+      q "limp|perky", :pick => :one
+    end
+
+    grid "For each of the car types checked, what type of options would you prefer?" do
+      a "Leather seats"
+      a "Shiny rims"
+      a "Subwoofer"
+      a "Sunroof"
+      a "Turbocharger"
+      q "SUV", :pick => :any
+      q "Sedan", :pick => :any
+      q "Coupe", :pick => :any
+      q "Convertible", :pick => :any
+      q "Minivan", :pick => :any
+      q "Crossover", :pick => :any
+      q "Wagon", :pick => :any
+      q "Other", :pick => :any
+    end
+
+    q "Please rank the following foods based on how much you like them"
+    a "|pizza", :integer
+    a "|salad", :integer
+    a "|sushi", :integer
+    a "|ice cream", :integer
+    a "|breakfast ceral", :integer
+
+    # :other, :string allows someone to specify both the "other" and some other information
+    q "Choose your favorite utensils and enter frequency of use (daily, weekly, monthly, etc...)", :pick => :any
+    a "spoon", :string
+    a "fork", :string
+    a "knife", :string
+    a :other, :string
+
+    q "What is your birth date?", :pick => :one
+    a "I was born on", :date
+    a "Refused"
+
+    q "At what time were you born?", :pick => :any
+    a "I was born at", :time
+    a "This time is approximate"
+
+    q "When would you like to schedule your next appointment?"
+    a :datetime
+
+    q_car "Do you own a car?", :pick => :one
+    a_y "Yes"
+    a_n "No"
+
+    # Repeaters allow multiple responses to a question or set of questions
+    repeater "Tell us about the cars you own" do
+      dependency :rule => "A"
+      condition_A :q_car, "==", :a_y
+      q "Make", :pick => :one, :display_type => :dropdown
+      a "Toyota"
+      a "Ford"
+      a "GMChevy"
+      a "Ferrari"
+      a "Tesla"
+      a "Honda"
+      a "Other weak brand"
+      q "Model"
+      a :string
+      q "Year"
+      a :string
+    end
+
+    repeater "Tell us the name and age of your siblings" do
+      q "Sibling"
+      a "Name", :string
+      a "Age|years", :integer
+    end
+
+  end
+end

data/lib/lunokhod.rb

@@ -0,0 +1,3 @@
+require 'lunokhod/compiler'
+require 'lunokhod/parser'
+require 'lunokhod/error_report'

data/lib/lunokhod/ast.rb

@@ -0,0 +1,263 @@
+require 'lunokhod/condition_parsing'
+require 'lunokhod/rule_parsing'
+require 'uuidtools'
+
+module Lunokhod
+  module Ast
+    LUNOKHOD_V0_NAMESPACE = UUIDTools::UUID.parse('ecab6cb2-8755-11e2-8caf-b8f6b111aef5')
+
+    module Identifiable
+      def identity
+        @identity ||= ident(self)
+      end
+
+      def ident(o)
+        case o
+        when NilClass, TrueClass, FalseClass, Numeric, Symbol, String then o.to_s
+        when Hash then o.keys.sort.map { |k| ident([k, o[k]]) }.flatten.join
+        when Array then o.map { |v| ident(v) }.flatten.join
+        when Struct then o.values.map { |v| ident(v) }.flatten.join
+        else raise "Cannot derive identity of #{o.class}"
+        end
+      end
+
+      def uuid
+        UUIDTools::UUID.sha1_create(LUNOKHOD_V0_NAMESPACE, identity)
+      end
+    end
+
+    module CommonOptions
+      %w(help_text custom_class display_type pick).each do |m|
+        class_eval <<-END
+          def #{m}
+            options[:#{m}]
+          end
+        END
+      end
+    end
+
+    module SurveyorTag
+      ##
+      # Surveyor interprets tags from two places:
+      #
+      # 1. the method tag
+      # 2. the :reference_identifier option
+      #
+      # This override is not intentional; it's just that the method's tag and
+      # the :reference_identifier option end up in the same column in
+      # Surveyor's database.
+      #
+      # There is no documented precedence rule, but analysis of Surveyor code
+      # and experiments have shown me that #2 usually overrides #1.
+      def surveyor_tag
+        options[:reference_identifier] || tag
+      end
+    end
+
+    class Survey < Struct.new(:line, :name, :options, :sections, :translations, :source)
+      include CommonOptions
+      include Identifiable
+
+      attr_accessor :parent
+
+      def initialize(*)
+        super
+
+        self.sections ||= []
+        self.translations ||= []
+      end
+
+      def children
+        translations + sections
+      end
+    end
+
+    class Translation < Struct.new(:line, :lang, :path)
+      include Identifiable
+
+      attr_accessor :parent
+
+      def children
+        []
+      end
+    end
+
+    class Section < Struct.new(:line, :tag, :name, :options, :questions)
+      include CommonOptions
+      include Identifiable
+      include SurveyorTag
+
+      attr_accessor :parent
+
+      alias_method :survey, :parent
+
+      def initialize(*)
+        super
+
+        self.questions ||= []
+      end
+
+      def children
+        questions
+      end
+    end
+
+    class Label < Struct.new(:line, :text, :tag, :options, :dependencies)
+      include CommonOptions
+      include Identifiable
+      include SurveyorTag
+
+      attr_accessor :parent
+
+      def initialize(*)
+        super
+
+        self.dependencies ||= []
+      end
+
+      def children
+        dependencies
+      end
+    end
+
+    class Question < Struct.new(:line, :text, :tag, :options, :answers, :dependencies)
+      include CommonOptions
+      include Identifiable
+      include SurveyorTag
+
+      attr_accessor :parent
+
+      def initialize(*)
+        super
+
+        self.answers ||= []
+        self.dependencies ||= []
+      end
+
+      def children
+        answers + dependencies
+      end
+    end
+
+    class Answer < Struct.new(:line, :text, :type, :other, :tag, :validations, :options)
+      include CommonOptions
+      include Identifiable
+      include SurveyorTag
+
+      attr_accessor :parent
+
+      def initialize(*)
+        super
+
+        self.validations ||= []
+        self.other ||= false
+      end
+
+      def children
+        validations
+      end
+
+      def other?
+        other
+      end
+    end
+
+    class Dependency < Struct.new(:line, :rule, :conditions)
+      include Identifiable
+      include RuleParsing
+
+      attr_accessor :parent
+
+      def initialize(*)
+        super
+
+        self.conditions ||= []
+      end
+
+      def children
+        conditions
+      end
+    end
+
+    class Validation < Struct.new(:line, :rule, :conditions)
+      include Identifiable
+      include RuleParsing
+
+      attr_accessor :parent
+
+      def initialize(*)
+        super
+
+        self.conditions ||= []
+      end
+
+      def children
+        conditions
+      end
+    end
+
+    class Group < Struct.new(:line, :tag, :name, :options, :questions, :dependencies)
+      include CommonOptions
+      include Identifiable
+      include SurveyorTag
+
+      attr_accessor :parent
+
+      def initialize(*)
+        super
+
+        self.questions ||= []
+        self.dependencies ||= []
+      end
+
+      def children
+        questions + dependencies
+      end
+    end
+
+    class Condition < Struct.new(:line, :tag, :predicate)
+      include Identifiable
+      include ConditionParsing
+
+      attr_accessor :parent
+
+      def children
+        []
+      end
+    end
+
+    class Grid < Struct.new(:line, :tag, :text, :questions, :answers)
+      include Identifiable
+
+      attr_accessor :parent
+
+      def initialize(*)
+        super
+
+        self.answers ||= []
+        self.questions ||= []
+      end
+
+      def children
+        questions + answers
+      end
+    end
+
+    class Repeater < Struct.new(:line, :tag, :text, :questions, :dependencies)
+      include Identifiable
+
+      attr_accessor :parent
+
+      def initialize(*)
+        super
+
+        self.questions ||= []
+        self.dependencies ||= []
+      end
+
+      def children
+        questions + dependencies
+      end
+    end
+  end
+end