Naseweis 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ba21648ac300ae3282685dd78622cd657aa643be
-  data.tar.gz: 3b7416d60d3a9e9ab28777b0e5bf69c73b714814
+  metadata.gz: 1daa455db84c7312b2526ca7387ec6d9675abd6c
+  data.tar.gz: 5612fb9fe210a801e9ff364aca8f7828c9f9cc24
 SHA512:
-  metadata.gz: 334a84249548f107b84dbdd691200ecbb3827ea064c2531292189015316655e02b7bfc465439940f8a9ccee03971739ae73a1d7f3a6407bb673e48ca8648791a
-  data.tar.gz: 6cf1c4adc993f537db46927d9f01ea06c72674da182822c3a7a874274ae0549538c6df227b92201c68d0dc357a1ddd0876b98ac4b1bf04ee889f6a9cd7dd803a
+  metadata.gz: 7c99b14fbc4933df198f039494b7ec8e9a3d56dfcd18001558df2979ca1c1f1fb0be57adec31bc62855b230d8df81f5d2dca9dcd4646cd1257348662743ddda8
+  data.tar.gz: 80af614856fe8c7fa21f5446668976074e41d97fb436a10665e0be9842daa8f5540de58f2f13d746c42e09f5d016095830e8fd3dcd472f4fdd948786d7decf51

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rubocop.yml

@@ -0,0 +1,23 @@
+AllCops:
+  Include:
+    - 'lib'
+  Exclude:
+    - 'Naseweis.gemspec'
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInLiteral:
+  EnforcedStyleForMultiline: comma
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/CyclomaticComplexity:
+  Max: 8
+
+Metrics/PerceivedComplexity:
+  Max: 9
+
+Metrics/AbcSize:
+  Max: 20

data/.yardopts

@@ -0,0 +1 @@
+- WEISHEIT.md CHANGELOG.md

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# 0.0.2 (unreleased)
+
+* Add `regex` and `float` types
+* Add options for `interrogate` to select the streams
+* Verify the questions in `read` to prevent errors popping up later

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in Naseweis.gemspec
+gemspec

data/Naseweis.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'naseweis/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "Naseweis"
+  spec.version       = Naseweis::VERSION
+  spec.authors       = ["Daniel Schadt"]
+  spec.email         = ["kingdread@gmx.de"]
+
+  spec.summary       = "Gather lots of information based on questionnaire files."
+  spec.description   = <<-EOF
+    Naseweis is a library that allows you to gather information based on
+    questions which are defined in yaml files. This lets you keep your data and
+    logic separated and avoids cluttering your code with many calls to
+    puts/gets. It also allows you to keep your questions organized, centralized
+    and language-agnostic.
+  EOF
+  spec.homepage      = "https://github.com/Kingdread/Naseweis"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.extra_rdoc_files = ["README.md", "WEISHEIT.md", "CHANGELOG.md"]
+  spec.rdoc_options << "--title" << "Naseweis Documentation" <<
+                       "--main" << "README.md"
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+
+  spec.add_runtime_dependency "highline", "~> 1.7"
+end

data/README.md

@@ -33,7 +33,7 @@ result["times"].times { puts "Hello, #{name}" }
 The `Weisheits` format is a normal YAML file, which defines questions, their
 target name, their type, and some more information.
 
-The full description can be found in WEISHEIT.md.
+The full description can be found in {file:WEISHEIT.md WEISHEIT.md}.
 
 ## Installation
 

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/WEISHEIT.md

@@ -0,0 +1,184 @@
+# `Weisheits`-files
+
+A `Weisheits`-fiile is a YAML file that describes the questions that should be
+asked.
+
+The top level element should be a list of questions, whereas the syntax of a
+question is described below.
+
+## question objects
+
+A question is a simple dictionary of various "modifiers", which allow you to
+customize the behaviour.
+
+Available options are:
+
+### `q`
+
+The actual question as a string, which is then used as a prompt, or a list of
+subquestions. If this attribute is a string, then the input will be saved,
+otherwise a dictionary of the sub-question responses will be saved.
+
+#### Examples
+
+```yaml
+# Simple string question
+- q: "What is your name?"
+  target: user_name
+
+# Subquestions
+- target: user_data
+  q:
+  - q: "User name?"
+    target: name
+  - q: "User email?"
+    target: email
+```
+
+In the first case, the result is available via `result["user_name"]`, in the
+second case, the name is saved as `result["user_data"]["name"]` and
+`result["user_data"]["email"]`.
+
+### `target`
+
+The name of the target variable, which will contain the user data.
+
+If the question is a normal string, the data is saved as a string.  If the
+question has subquestions, the data is a hash, which contains the subquestions
+data.  If the question is repeated, the data is saved as a list of separate
+inputs.  If the question has a type specified, it will be type-converted.
+
+### `desc`
+
+Description of the question, which will be printed before the question is
+asked. This is useful e.g. for repeating questions, as it will be displayed
+once (while the prompt will be displayed multiple times). It can also be used
+as a "print" function if no question data is gathered.
+
+#### Examples
+
+```yaml
+- desc: "Just print something"
+
+- desc: "Gather some lines, input an empty line to finish"
+  repeat: true
+  target: lines
+```
+
+### `repeat`
+
+Define if the question should be repeated. A repeated question will save its
+result as a list. The prompt is displayed at each iteration, if you only want
+to display it once, use `desc` instead.
+
+There are multiple ways a question can be repeated:
+
+* `repeat: true`: repeat until an empty line is entered.
+* `repeat: 3`: repeat 3 times.
+* `repeat: "Continue?"`: ask the given prompt, if it is answered with "yes",
+  repeat the question again.
+
+Note that the presence of the `repeat` attribute is enough to force the answer
+to be a list, even if the actual question produces 0 or 1 inputs.
+
+#### Examples
+
+```yaml
+- desc: "Enter your address, end with an empty line"
+  repeat: true
+  target: address
+
+- prompt: "Your sibling's name?"
+  target: siblings
+  repeat: "Do you have another sibling?"
+```
+
+### `type`
+
+Type of the question. This is used to both verify the input and convert it to
+the native Ruby type.
+
+Valid types are:
+
+* `int`, `integer`: Integer
+* `float`: floating point number
+* `regex`, `regexp`: valid regular expression
+
+### `choices`
+
+A list of valid choices. The user can select one of the given items, but they
+can not define their own.
+
+#### Examples
+
+```yaml
+- q: "Pick your starter"
+  choices: ["Charmander", "Bulbasaur", "Squirtle"]
+
+- q: "Pick your language"
+  choices:
+  - Ruby
+  - Python
+  - Perl
+```
+
+## Nesting questions
+
+Questions can be nested arbitrarily deep, if you want to make an address book,
+you could do something like
+
+```yaml
+- desc: "Fill your address book!"
+  repeat: "Add another contact?"
+  target: contacts
+  q:
+  - q: "Contact name?"
+    target: name
+  - q: "Contact address?"
+    target: address
+  - desc: "Additional information (end with an empty line)"
+    repeat: true
+    target: information
+```
+
+Processing the file will lead to the following interaction:
+
+```
+>>> Fill your address book!
+>>> Contact name?
+Darth Vader
+>>> Contact address?
+Death Star
+>>> Additional information (end with an empty line)
+Very nice guy!
+
+>>> Add another contact?
+yes
+>>> Contact name?
+Luke Skywalker
+>>> Contact address?
+Dagobah
+>>> Additional information (end with an empty line)
+
+>>> Add another contact?
+no
+```
+
+And finally to the Ruby structure:
+
+```ruby
+{
+  "contacts"=>[
+    {
+      "name"=>"Darth Vader",
+      "address"=>"Death Star",
+      "information"=>["Very nice guy!"]
+    },
+    {
+      "name"=>"Luke Skywalker",
+      "address"=>"Dagobah",
+      "information"=>[]
+    }
+  ]
+}
+```

data/lib/naseweis.rb

@@ -0,0 +1,160 @@
+require 'naseweis/converter'
+require 'naseweis/version'
+require 'yaml'
+require 'highline'
+
+# The Naseweis module is a module which takes a +Weisheits+-file (or short
+# +Weisfile+) and asks the user the questions that are defined in the
+# +Weisfile+.
+#
+# This is useful if you have an application that needs to ask a lot of
+# questions and you'd rather keep the questions (the data) out of the program
+# (the logic).
+#
+# This module helps by defining a "mini-language", which can be used to specify
+# questions and later retrieve their answers to process them.
+#
+# For more information about the file format see the +Weisfile+ document.
+module Naseweis
+  # Exception raised when the input file (+Weisheits+-file) is malformed
+  class WeisheitError < StandardError
+  end
+
+  # A class to read a +Weisfile+ and gather user input
+  #
+  # @attr_reader [String] filename The path to the file which is used by this
+  #   {Nase}
+  # @attr_reader [Array] questions All questions handled by this {Nase}.
+  #
+  #   To update the questions, use the {#read} method.
+  # @attr_reader [Converter] converter The converter that is used to convert
+  #   types
+  class Nase
+    attr_reader :filename, :questions, :converter
+
+    # Create a new {Nase} which reads questions from the given file
+    #
+    # @param path [String] path to the file with the questions
+    def initialize(path)
+      @filename = path
+      @questions = {}
+      @converter = Converter.new
+    end
+
+    # Update the questions and re-read them from the file that the Nase was
+    # initialized with
+    #
+    # @return [void]
+    # @raise [WeisheitError] if the input file is malformed
+    def read
+      questions = YAML.load_file(@filename)
+      verify questions
+      @questions = questions
+    end
+
+    # Check whether the given question is wellformed
+    #
+    # @param q [Hash,Array] the question or list of questions to check
+    # @return [void]
+    # @raise [WeisheitError] if the question is malformed
+    def verify(q)
+      # Currently only checks if the question type is valid
+      if q.is_a? Array
+        q.each { |x| verify x }
+        return
+      end
+      type = q['type']
+      qs = q['q']
+      well = type.nil? || @converter.supported_types.include?(type.intern)
+      raise WeisheitError, "invalid type #{type}" unless well
+      verify qs if qs.is_a? Array
+    end
+
+    # Start the question session and return the user answers
+    #
+    # @param instream [File] input stream, i.e. stream where data is read from
+    # @param outstream [File] output stream, i.e. stream where prompts are
+    #   printed to
+    # @return [Hash] Hash of the user answers, where the keys are defined by
+    #   the question file.
+    def interrogate(instream: $stdin, outstream: $stdout)
+      @io = HighLine.new instream, outstream
+      ask @questions
+      @io = nil
+    end
+
+    private
+
+    # Ask the given list of questions and return the answers as a Hash
+    #
+    # @param questions [Array] list of questions to ask
+    # @return [Hash] Hash of the user answers
+    def ask(questions)
+      namespace = {}
+      questions.each do |q|
+        answer = do_question q
+        namespace[q['target']] = answer if q.key?('target') && !answer.nil?
+      end
+      namespace
+    end
+
+    # Handle a single question and return the answer
+    #
+    # @param q [Hash] the question data
+    # @return [String] for a simple question
+    # @return [Array] for a repeating question
+    def do_question(q)
+      if q.key? 'desc'
+        # Always output the description first
+        @io.say q['desc']
+      end
+
+      repeat = q['repeat']
+      return get_valid_input q if repeat.nil?
+      return (1..repeat).collect { get_valid_input q } if repeat.is_a? Integer
+      if repeat.is_a? String
+        result = [get_valid_input(q)]
+        result.push(get_valid_input(q)) while @io.agree repeat
+      else
+        result = []
+        loop do
+          line = get_valid_input q
+          break if line.empty?
+          result << line
+        end
+      end
+      result
+    end
+
+    # Get a single line of user input that is valid for the given question
+    #
+    # @param q [Hash] the question which to get input for
+    # @return [String] if the question is a simple question
+    # @return [Hash] if the question has sub-questions
+    # @return [Object] if the question is type-converted
+    def get_valid_input(q)
+      prompt = q['q']
+      prompt = '' if prompt.nil?
+      result = nil
+      loop do
+        if prompt.is_a? Array
+          result = ask prompt
+        elsif !q['choices'].nil?
+          @io.say prompt
+          result = @io.choose(*q['choices'])
+        else
+          result = @io.ask prompt
+        end
+        break if q['type'].nil?
+        begin
+          result = @converter.convert result, q['type']
+        rescue ConversionError
+          @io.say "invalid value for type #{q['type']}"
+        else
+          break
+        end
+      end
+      result
+    end
+  end
+end

data/lib/naseweis/converter.rb

@@ -0,0 +1,69 @@
+module Naseweis
+  # A +ConversionError+ is raised when the given data can't be converted to the
+  # requested type. It acts as a common error to catch all other errors that
+  # are raised by Ruby when converting between types.
+  #
+  # @attr_reader [String] data the data that was attempted to convert
+  # @attr_reader [String] type the typename that was requested
+  class ConversionError < StandardError
+    attr_reader :data, :type
+
+    # Create a new ConversionError
+    #
+    # @param data [String] value for {#data}
+    # @param type [String] value for {#type}
+    def initialize(data, type)
+      @data = data
+      @type = type
+    end
+
+    # Get the string representation for the error
+    #
+    # @return [String] error string
+    def to_s
+      "Can't convert '#{@data}' to #{type}"
+    end
+  end
+
+  # The +Converter+ class provides a way to convert between stringy data and
+  # native Ruby types. It's used to handle the +type:+ attribute of questions.
+  #
+  # @attr_reader [Hash] converters A hash of all available types.
+  class Converter
+    attr_reader :converters
+
+    def initialize
+      @converters = {
+        int: ->(x) { Integer x },
+        integer: ->(x) { Integer x },
+        regex: ->(x) { Regexp.new x },
+        regexp: ->(x) { Regexp.new x },
+        float: ->(x) { Float x },
+      }
+    end
+
+    # Convert the data to the given target type
+    #
+    # @param data [String] the question answer
+    # @param type [String] the target type
+    # @return [Object] the converted data
+    # @raise [ConversionError] if the data cannot be converted to the given
+    #   target
+    def convert(data, type)
+      type = type.intern
+      raise ArgumentError, "Invalid type #{type}" unless @converters.key? type
+      begin
+        @converters[type][data]
+      rescue
+        raise ConversionError.new data, type
+      end
+    end
+
+    # Get a list of all supported types
+    #
+    # @return [Array] an array of supported types
+    def supported_types
+      @converters.keys
+    end
+  end
+end

data/lib/naseweis/version.rb

@@ -0,0 +1,4 @@
+module Naseweis
+  # Version of the module
+  VERSION = '0.0.2'.freeze
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: Naseweis
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Daniel Schadt
@@ -65,9 +65,20 @@ extensions: []
 extra_rdoc_files:
 - README.md
 - WEISHEIT.md
+- CHANGELOG.md
 files:
+- ".gitignore"
+- ".rubocop.yml"
+- ".yardopts"
+- CHANGELOG.md
+- Gemfile
+- Naseweis.gemspec
 - README.md
+- Rakefile
 - WEISHEIT.md
+- lib/naseweis.rb
+- lib/naseweis/converter.rb
+- lib/naseweis/version.rb
 homepage: https://github.com/Kingdread/Naseweis
 licenses:
 - MIT
@@ -97,3 +108,4 @@ signing_key:
 specification_version: 4
 summary: Gather lots of information based on questionnaire files.
 test_files: []
+has_rdoc: