slightish 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8dcf08230b1ba15f62dfe96a21b16a320603501e
+  data.tar.gz: b651c070d9f46f071709a10cce04b1208856a8a8
+SHA512:
+  metadata.gz: bca0ad40555d5ce4b79c2a657fe6ddafa2f8825f3913e202c735fd98d70ea3dba8130db90bd498d8321d06b9f4fd98e49c5fe58699a165fea4d05fc1f02765a5
+  data.tar.gz: e1a340b606a1e38ec9919a77a3843c9e6493bf34defd56fa437571850837f044ec0a8bc8f81230e08b0a9825b10ea87ef55fed94f2e5b012cd60fe47166d45aa

data/.gitignore

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

data/.rubocop.yml

@@ -0,0 +1,63 @@
+AllCops:
+  Include:
+    - 'lib/**/*'
+    - 'bin/*'
+    - 'exe/*'
+    - 'test/**/*.rb'
+  Exclude:
+    - 'bin/setup'
+    - 'vendor/**/*'
+
+Style/FileName:
+  Exclude:
+    - 'Gemfile'
+    - 'Rakefile'
+
+# Using %[...] to avoid conflicts with parens in shell expansions
+Style/PercentLiteralDelimiters:
+  Exclude:
+    - 'test/**/*_test.rb'
+    - 'test/**/*_tests.rb'
+
+# Need trailing whitespace for some test suites
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'test/**/*_test.rb'
+    - 'test/**/*_tests.rb'
+
+Metrics/ParameterLists:
+  Exclude:
+    - 'test/lib/slightish_test.rb'
+
+Metrics/LineLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/BracesAroundHashParameters:
+  Enabled: false
+
+Layout/CommentIndentation:
+  Enabled: false
+
+
+# Ideally these are TODOs:
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+cache: bundler
+rvm:
+  - 2.4.0
+  - 2.2.1
+
+script:
+  - bundle exec rake test

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at tim.clem@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in slightish.gemspec
+gemspec
+
+group :development do
+  gem 'bundler'
+  gem 'minitest'
+  gem 'rake'
+  gem 'rubocop'
+  gem 'simplecov'
+  gem 'coveralls'
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Tim Clem
+
+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,140 @@
+# Slightish
+
+*Literate testing of shell scripts*
+
+[![Build Status](https://travis-ci.org/misterfifths/slightish.svg?branch=master)](https://travis-ci.org/misterfifths/slightish) [![Coverage Status](https://coveralls.io/repos/github/misterfifths/slightish/badge.svg?branch=master)](https://coveralls.io/github/misterfifths/slightish?branch=master) [![npm](https://img.shields.io/gem/v/slightish.svg)](https://rubygems.org/gems/slightish)
+
+
+### What's this then?
+
+A spiritual successor to [tush](https://github.com/darius/tush), *slightish* is a simple tool for testing command line tools using a simple syntax.
+
+### Installation
+
+*slightish* can be install through RubyGems, the Ruby package manager. Run the following command, optionally prefixing it with `sudo` if your environment requires it (you'll get some sort of permissions error if so).
+
+```sh
+gem install slightish
+```
+
+### Writing tests
+
+Write your tests interspersed among your documentation, in whatever file type you please (Markdown, plain text, HTML, etc.). For example, *this very file* can be used as a test. Blocks of text that look like shell transcripts are executed and tested:
+
+```sh
+$ echo 'this is a test'
+| this is a test
+```
+
+You can also compare stderr and exit codes:
+
+```sh
+$ echo stdout; echo stderr >&2; echo "more stdout"; exit 2
+| stdout
+| more stdout
+@ stderr
+? 2
+```
+
+That example covers 90% of the functionality. The syntax in detail works like this:
+
+- Lines that start with `$ ` are interpreted as commands to run in the shell. The `$` must be in the first column of the file and must be followed by a space.
+- Lines starting with `| ` specify the stdout of the most recent command. As with `$ `, the `|` must be in the first column and must be followed by a space. You may specify more than one `| ` line to test for multiline output.
+- Lines starting with `@ ` specify the stderr of the most recent command. You may also specify more than one `@ ` line per command.
+- A line of the form `? <positive integer>` specifies the expected exit code of the most recent command. You may omit a `? ` line for an expected exit code of zero.
+
+Specifying any of the above magic lines out of order is a syntax error; you must specify a command (`$ `), and then optionally stdout (`| `), stderr (`@ `), and the exit code (`? `). If a command is expected to produce no output and have an exit code of zero, you may omit everything but the `$ ` line:
+
+```sh
+# This passes because it exits with code 0 and produces no output
+$ echo
+```
+
+### Running tests
+
+Once you've written tests, pass the filenames to the `slightish` command:
+
+```sh
+slightish my-first-test.md my-second-test
+```
+
+This will run all the tests in all the specified files, and output details about any failures. The command will exit with status code 1 if any tests fail.
+
+Let's add a failing test real quick:
+
+```sh
+$ exit 2
+| 1
+```
+
+Now if we run `slightish` on this file, we get this output:
+
+```
+❌  README.md:64-65
+Expected stdout:
+1
+Actual stdout: empty
+
+Expected exit code: 0
+Actual exit code: 2
+
+----------
+README.md 	6 passed	1 failed
+
+Total tests: 7
+Passed: 6
+Failed: 1
+```
+
+### More features
+
+#### Sandboxes
+
+Each test file is run in its own sandbox directory, so you can safely write to files if your tests require it:
+
+```sh
+$ echo 'hello world' > test-file
+$ cat test-file
+| hello world
+```
+
+All sandbox directories are deleted at the end of testing.
+
+If you have a directory of files that your tests require ("fixtures"), you can specify it as the template for sandboxes, and its contents are copied to each sandbox before tests begin. This is done by setting the environmental variable `SLIGHTISH_TEMPLATE_DIR` before invoking the `slightish` command.
+
+Since sandboxes ensure (or at least attempt to ensure) that each test file is independent of the others, the tests in each test files are run in parallel to speed up the process. Commands within each test file are run in order, however.
+
+#### Multiline commands
+
+If you need to specify a long command, you can split it onto multiple lines by ending the `$ ` line with a backslash:
+
+```sh
+$ echo "This is a \
+very long string \
+that I wish to print."
+| This is a very long string that I wish to print.
+```
+
+Note that the backslash must be the final character on the line, or else it is not treated as a continuation.
+
+### More examples
+
+The [tests for jutil](https://github.com/misterfifths/jutil/tree/master/tests), a tool to manipulate JSON on the command line, were written in tush/slightish syntax.
+
+Also see [tests for adolfopa/cstow](https://github.com/adolfopa/cstow/blob/master/src/TESTS.md).
+
+### Acknowledgements
+
+Thanks to [darius](https://github.com/darius) for the original [tush](https://github.com/darius/tush), the syntax of which I adopted. Thanks also to [adolfopa](https://github.com/adolfopa/) for his [fork](https://github.com/adolfopa/tush) which added support for multiline commands.
+
+### Future plans
+
+In no particular order,
+
+- Regex matching for stdout and stderr
+- Expose some things (sandbox template dir) as command line arguments
+- More responsive and prettier output
+- Fail fast mode
+- Smarter threading?
+- Bless
+- Diff output

data/Rakefile

@@ -0,0 +1,17 @@
+require 'rake/testtask'
+require 'rubocop/rake_task'
+
+desc 'Run tests'
+Rake::TestTask.new do |t|
+  ENV.delete('SLIGHTISH_TEMPLATE_DIR')
+  ENV['SLIGHTISH_NO_COLOR'] = '1'
+  ENV['SLIGHTISH_NO_WARNINGS'] = '1'
+  t.test_files = FileList['test/**/*_test{s,}.rb']
+end
+task default: :test
+
+desc 'Run rubocop'
+RuboCop::RakeTask.new(:rubocop)
+
+desc 'Run rubocop'
+task lint: :rubocop

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'slightish'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/slightish

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'slightish'
+
+Slightish::Command.run(ARGV)

data/lib/slightish/command.rb

@@ -0,0 +1,63 @@
+require 'slightish/test_suite'
+
+class Slightish::Command
+  def self.run(argv)
+    if argv.empty? || argv.include?('--help') || argv.include?('-h')
+      print_usage
+      Process.exit(2)
+    else
+      new.run(argv, sandbox_template_dir: ENV['SLIGHTISH_TEMPLATE_DIR'])
+    end
+  end
+
+  def self.print_usage
+    $stderr.puts('Literate testing of shell tools')
+    $stderr.puts('usage: slightish <file...>')
+  end
+
+  def run(test_files, sandbox_template_dir: nil)
+    Thread.abort_on_exception = true
+
+    suites = []
+    worker_threads = []
+
+    test_files.each do |file|
+      suite = Slightish::TestSuite.from_file(file, sandbox_template_dir: sandbox_template_dir)
+      suites << suite
+      worker_threads << Thread.new { suite.run }
+    end
+
+    worker_threads.each(&:join)
+
+    suites.each do |suite|
+      puts(suite.failure_description) if suite.failed?
+    end
+
+    puts('----------') if suites.any?(&:failed?)
+
+    total_tests = 0
+    total_passed = 0
+    total_failed = 0
+    max_suite_name_length = suites.max_by { |suite| suite.name.length }.name.length
+    max_passed_length = suites.max_by(&:passed_count).passed_count.to_s.length
+    max_failed_length = suites.max_by(&:failed_count).failed_count.to_s.length
+
+    suites.each do |suite|
+      total_tests += suite.test_cases.length
+      total_passed += suite.passed_count
+      total_failed += suite.failed_count
+
+      line = suite.name.ljust(max_suite_name_length + 1).bold + "\t"
+      line += "#{suite.passed_count.to_s.rjust(max_passed_length)} passed".green + "\t"
+      line += "#{suite.failed_count.to_s.rjust(max_failed_length)} failed".red
+      puts(line)
+    end
+
+    puts
+    puts('Total tests: '.bold + total_tests.to_s.gray)
+    puts('Passed: '.green + total_passed.to_s.gray)
+    puts('Failed: '.red + (total_tests - total_passed).to_s.gray)
+
+    Process.exit(1) if total_failed > 0
+  end
+end

data/lib/slightish/sandbox.rb

@@ -0,0 +1,18 @@
+require 'fileutils'
+require 'tmpdir'
+
+class Slightish::Sandbox
+  attr_reader :path
+
+  def initialize(template_dir: nil, prefix: 'slightish')
+    @path = Dir.mktmpdir(prefix)
+
+    # The '.' prevents cp_r from making a new directory at the destination --
+    # kind of the equivalent of '/*' in bash.
+    FileUtils.cp_r(File.join(template_dir, '.'), @path) unless template_dir.nil?
+  end
+
+  def delete
+    FileUtils.remove_entry_secure(@path)
+  end
+end

data/lib/slightish/test_case.rb

@@ -0,0 +1,132 @@
+require 'open3'
+
+class Slightish::TestCase
+  attr_reader :source_file
+  attr_accessor :start_line, :end_line
+  attr_reader :raw_command, :command
+  attr_reader :raw_expected_output, :expected_output
+  attr_reader :raw_expected_error_output, :expected_error_output
+  attr_accessor :expected_exit_code
+  attr_reader :actual_output, :actual_error_output, :actual_exit_code
+
+  def initialize(source_file)
+    @source_file = source_file
+    @expected_exit_code = 0
+
+    @start_line = @end_line = -1
+    @raw_command = @command = nil
+    @raw_expected_output = @expected_output = nil
+    @raw_expected_error_output = @expected_error_output = nil
+    @actual_output = @actual_error_output = nil
+    @actual_exit_code = nil
+  end
+
+  def run(sandbox)
+    expand(sandbox)
+
+    @actual_output, @actual_error_output, process_status = Open3.capture3(@command, { chdir: sandbox.path })
+    @actual_output.chomp!
+    @actual_error_output.chomp!
+    @actual_exit_code = process_status.exitstatus
+  end
+
+  def passed?
+    @actual_output == @expected_output &&
+      @actual_error_output == @expected_error_output &&
+      @actual_exit_code == @expected_exit_code
+  end
+
+  def failed?
+    !passed?
+  end
+
+  def failure_description
+    res = ''
+
+    if @actual_output != (@expected_output || '')
+      if @expected_output.empty?
+        res += "Expected stdout: empty\n".red.bold
+      else
+        res += "Expected stdout:\n".red.bold
+        res += @expected_output.gray + "\n"
+      end
+
+      if @actual_output.empty?
+        res += 'Actual stdout: empty'.green.bold
+      else
+        res += "Actual stdout:\n".green.bold
+        res += @actual_output.gray
+      end
+    end
+
+    if @actual_error_output != (@expected_error_output || '')
+      res += "\n\n" unless res == ''
+      if @expected_error_output.empty?
+        res += "Expected stderr: empty\n".red.bold
+      else
+        res += "Expected stderr:\n".red.bold
+        res += (@expected_error_output || '').gray + "\n"
+      end
+
+      if @actual_error_output.empty?
+        res += 'Actual stderr: empty'.green.bold
+      else
+        res += "Actual stderr:\n".green.bold
+        res += @actual_error_output.gray
+      end
+    end
+
+    if @actual_exit_code != @expected_exit_code
+      res += "\n\n" unless res == ''
+      res += 'Expected exit code: '.red.bold + @expected_exit_code.to_s.gray + "\n"
+      res += 'Actual exit code: '.green.bold + @actual_exit_code.to_s.gray
+    end
+
+    res
+  end
+
+  def source_description
+    if @start_line == @end_line
+      "#{@source_file}:@{@start_line}"
+    else
+      "#{@source_file}:#{@start_line}-#{@end_line}"
+    end
+  end
+
+  def append_command(str)
+    if @raw_command.nil?
+      @raw_command = str
+    else
+      # bash eats newlines from multiline strings, so no \n here
+      # For example:
+      # "echo a\
+      # b"
+      # produces "ab"
+      @raw_command += str
+    end
+  end
+
+  def append_expected_output(str)
+    if @raw_expected_output.nil?
+      @raw_expected_output = str
+    else
+      @raw_expected_output += "\n" + str
+    end
+  end
+
+  def append_expected_error_output(str)
+    if @raw_expected_error_output.nil?
+      @raw_expected_error_output = str
+    else
+      @raw_expected_error_output += "\n" + str
+    end
+  end
+
+  private
+
+  def expand(sandbox)
+    @command = @raw_command.expand(chdir: sandbox.path, source: source_description)
+    @expected_output = (@raw_expected_output || '').expand(chdir: sandbox.path, source: source_description)
+    @expected_error_output = (@raw_expected_error_output || '').expand(chdir: sandbox.path, source: source_description)
+  end
+end

data/lib/slightish/test_suite.rb

@@ -0,0 +1,167 @@
+require 'slightish/sandbox'
+require 'slightish/test_case'
+
+class Slightish::TestSuite
+  attr_reader :name, :path, :test_cases
+  attr_reader :sandbox_template_dir
+
+  def self.from_file(path, sandbox_template_dir: nil)
+    new(path, File.read(path), sandbox_template_dir: sandbox_template_dir)
+  end
+
+  def initialize(path, contents, sandbox_template_dir: nil)
+    @path = path
+    @name = File.basename(path)
+    @sandbox_template_dir = sandbox_template_dir
+
+    parse(path, contents)
+  end
+
+  def run
+    sandbox = Slightish::Sandbox.new(template_dir: @sandbox_template_dir)
+
+    begin
+      @test_cases.each { |test| test.run(sandbox) }
+    ensure
+      sandbox.delete
+    end
+  end
+
+  def failure_description
+    res = ''
+    @test_cases.select(&:failed?).each do |test|
+      res += "❌  #{test.source_description}\n".bold
+      res += test.failure_description + "\n\n"
+    end
+
+    res
+  end
+
+  def passed?
+    @test_cases.all?(&:passed?)
+  end
+
+  def failed?
+    @test_cases.any?(&:failed?)
+  end
+
+  def passed_count
+    @test_cases.count(&:passed?)
+  end
+
+  def failed_count
+    @test_cases.count(&:failed?)
+  end
+
+  private
+
+  class ParseState
+    AWAITING_COMMAND = 0
+    READING_MULTILINE_COMMAND = 1
+    AWAITING_RESULT_OR_COMMAND = 2
+    AWAITING_STDERR_OR_EXIT_CODE_OR_COMMAND = 3
+
+    # Start in AWAITING_COMMAND
+
+    # AWAITING_COMMAND -> READING_MULTILINE_COMMAND on '$ .*\' (starting a new command)
+    # AWAITING_COMMAND -> AWAITING_RESULT_OR_COMMAND on '$ .*' (starting a new command)
+    # any other meaningful line on AWAITING_COMMAND is an error
+
+    # READING_MULTILINE_COMMAND -> READING_MULTILINE_COMMAND on '.*\'
+    # READING_MULTILINE_COMMAND -> AWAITING_RESULT_OR_COMMAND on anything else
+    # EOF from this state is error-ish, but eh, not worth it
+
+    # AWAITING_RESULT_OR_COMMAND -> AWAITING_RESULT_OR_COMMAND on '| .*'
+    # AWAITING_RESULT_OR_COMMAND -> AWAITING_COMMAND on '? \d+' (starting a new command)
+    # AWAITING_RESULT_OR_COMMAND -> AWAITING_STDERR_OR_EXIT_CODE_OR_COMMAND on '@ .*' (now accumulating stderr; stdout lines are no longer acceptable)
+    # inherits the AWAITING_COMMAND transitions
+
+    # AWAITING_STDERR_OR_EXIT_CODE_OR_COMMAND has same productions as AWAITING_RESULT_OR_COMMAND, except '| .*'
+    # '| .*' from here is an error
+    # EOF from here is fine; expected exit code = 0
+
+    # These are subsets of each other. So, we can test in this order and not repeat ourselves:
+    # READING_MULTILINE_COMMAND
+    # skip the line unless it begins with one of the magic strings
+    # AWAITING_RESULT_OR_COMMAND
+      # test for '| .*', else fall through
+    # AWAITING_RESULT_OR_COMMAND || AWAITING_STDERR_OR_EXIT_CODE_OR_COMMAND
+      # test for '@ .*' and '? \d+', else fall through
+    # AWAITING_COMMAND || AWAITING_RESULT_OR_COMMAND || AWAITING_STDERR_OR_EXIT_CODE_OR_COMMAND
+      # test for '$ .*\' or '$ .*'; anything else is an error
+  end
+
+  def parse(file_name, file_contents)
+    @test_cases = []
+
+    current_case = nil
+    state = ParseState::AWAITING_COMMAND
+
+    file_contents.each_line.with_index(1) do |line, line_number|
+      if state == ParseState::READING_MULTILINE_COMMAND
+        if line =~ /^(?<cmd>.*)\\$/
+          # multiline input continues
+          current_case.append_command(Regexp.last_match(:cmd))
+          current_case.end_line = line_number
+
+          state = ParseState::READING_MULTILINE_COMMAND
+        else
+          # final line of multiline input; consume the whole thing
+          current_case.append_command(line.chomp)
+          current_case.end_line = line_number
+
+          state = ParseState::AWAITING_RESULT_OR_COMMAND
+        end
+
+        next
+      end
+
+      # Skip lines not intended for us
+      next unless line =~ /^[$|@?] /
+
+      if state == ParseState::AWAITING_RESULT_OR_COMMAND
+        if line =~ /^\| (?<output>.*)$/
+          # accumulating expected stdout
+          current_case.append_expected_output(Regexp.last_match(:output))
+          current_case.end_line = line_number
+
+          state = ParseState::AWAITING_RESULT_OR_COMMAND
+          next
+        end
+      end
+
+      if [ParseState::AWAITING_RESULT_OR_COMMAND, ParseState::AWAITING_STDERR_OR_EXIT_CODE_OR_COMMAND].include?(state)
+        if line =~ /^@ (?<error_output>.*)$/
+          # accumulating expected stderr
+          current_case.append_expected_error_output(Regexp.last_match(:error_output))
+          current_case.end_line = line_number
+
+          state = ParseState::AWAITING_STDERR_OR_EXIT_CODE_OR_COMMAND
+          next
+        elsif line =~ /\? (?<exit_code>\d+)$/
+          # got exit code; only possible option from here is a new command
+          current_case.expected_exit_code = Regexp.last_match(:exit_code).to_i
+          current_case.end_line = line_number
+
+          state = ParseState::AWAITING_COMMAND
+          next
+        end
+      end
+
+      # state is anything, and we are looking for a new command
+      unless line =~ /^\$ (?<cmd>.+?)(?<multiline>\\?)$/
+        raise SyntaxError, "invalid line in test file #{file_name}:#{line_number}; expected a '$ <command>' line"
+      end
+
+      current_case = Slightish::TestCase.new(file_name)
+      current_case.start_line = current_case.end_line = line_number
+      @test_cases << current_case
+
+      current_case.append_command(Regexp.last_match(:cmd))
+
+      # entering multiline mode if we matched the slash
+      multiline = Regexp.last_match(:multiline) == '\\'
+      state = multiline ? ParseState::READING_MULTILINE_COMMAND : ParseState::AWAITING_RESULT_OR_COMMAND
+    end
+  end
+end

data/lib/slightish/version.rb

@@ -0,0 +1,3 @@
+module Slightish
+  VERSION = '0.1.0'.freeze
+end

data/lib/slightish.rb

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+
+require 'slightish/version'
+
+require 'string_mixins'
+
+require 'slightish/sandbox'
+require 'slightish/test_case'
+require 'slightish/test_suite'
+require 'slightish/command'

data/lib/string_mixins.rb

@@ -0,0 +1,78 @@
+require 'open3'
+
+class String
+  def self.color_output?
+    $stdout.isatty unless ENV['SLIGHTISH_NO_COLOR']
+  end
+
+  {
+    red: 1,
+    green: 2,
+    yellow: 3,
+    blue: 4,
+    gray: 7
+  }.each do |name, code|
+    bg_name = ('bg_' + name.to_s).to_sym
+
+    if color_output?
+      # :nocov:
+      define_method(name) { "\e[#{code + 30}m#{self}\e[39m" }
+      define_method(bg_name) { "\e[#{code + 40}m#{self}\e[49m" }
+      # :nocov:
+    else
+      define_method(name) { self }
+      define_method(bg_name) { self }
+    end
+  end
+
+  { bold: 1, faint: 2 }.each do |name, code|
+    if color_output?
+      # :nocov:
+      define_method(name) { "\e[#{code}m#{self}\e[22m" }
+      # :nocov:
+    else
+      define_method(name) { self }
+    end
+  end
+
+  def expand(chdir: nil, source: nil)
+    # Non-existent environmental variables are not replaced.
+    # A little unexpected, but it's the behavior of tush.
+    # TODO: print a warning when this happens?
+    variable_replacer = ->(match) { ENV.fetch(Regexp.last_match(:var_name), match) }
+    res = gsub(/\$(?<var_name>[[:alnum:]_]+)/, &variable_replacer) # $VARIABLE
+    res.gsub!(/\$\{(?<var_name>[[:alnum:]_]+)\}/, &variable_replacer) # ${VARIABLE}
+
+    command_replacer = ->(_) { capture_stdout_with_logging(Regexp.last_match(:cmd), chdir, source) }
+    res.gsub!(/\$\((?<cmd>[^\)]+)\)/, &command_replacer) # $(COMMAND)
+    res.gsub!(/`(?<cmd>[^`]+)`/, &command_replacer) # `COMMAND`
+
+    res
+  end
+
+  private
+
+  def capture_stdout_with_logging(cmd, chdir, source)
+    if chdir.nil?
+      stdout, stderr, status = Open3.capture3(cmd)
+    else
+      stdout, stderr, status = Open3.capture3(cmd, { chdir: chdir })
+    end
+
+    unless stderr.empty?
+      message = 'warning: stderr from command substitution ('
+      message += source + '; ' unless source.nil? || source.empty?
+      message += "'#{cmd}') will be ignored"
+      $stderr.puts(message.yellow) unless ENV['SLIGHTISH_NO_WARNINGS']
+    end
+
+    unless status.exitstatus.zero?
+      message = "warning: nonzero exit code (#{status.exitstatus}) from command substitution ("
+      message += source + '; ' unless source.nil? || source.empty?
+      message += "'#{cmd}')"
+      $stderr.puts(message.yellow) unless ENV['SLIGHTISH_NO_WARNINGS']
+    end
+
+    stdout.chomp
+  end
+end

data/slightish.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'slightish/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'slightish'
+  spec.version       = Slightish::VERSION
+  spec.required_ruby_version = '>=2.2.1'
+
+  spec.authors       = ['Tim Clem']
+  spec.email         = ['tim.clem@gmail.com']
+
+  spec.summary       = 'Literate testing of shell tools'
+  spec.description   = %(
+    slightish lets you write and run tests for shell tools in a
+    simple, flexible syntax, intermingled with any other file
+    format (Markdown, plain text, HTML). Your documentation can
+    double as your tests.
+  ).strip.gsub(/\s+/, ' ')
+  spec.homepage      = 'http://github.com/misterfifths/slightish'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: slightish
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tim Clem
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-06-14 00:00:00.000000000 Z
+dependencies: []
+description: slightish lets you write and run tests for shell tools in a simple, flexible
+  syntax, intermingled with any other file format (Markdown, plain text, HTML). Your
+  documentation can double as your tests.
+email:
+- tim.clem@gmail.com
+executables:
+- slightish
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rubocop.yml"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- exe/slightish
+- lib/slightish.rb
+- lib/slightish/command.rb
+- lib/slightish/sandbox.rb
+- lib/slightish/test_case.rb
+- lib/slightish/test_suite.rb
+- lib/slightish/version.rb
+- lib/string_mixins.rb
+- slightish.gemspec
+homepage: http://github.com/misterfifths/slightish
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Literate testing of shell tools
+test_files: []