seeing_is_believing 3.0.0.beta.4 → 3.0.0.beta.5

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: seeing_is_believing
 version: !ruby/object:Gem::Version
-  version: 3.0.0.beta.4
+  version: 3.0.0.beta.5
 platform: ruby
 authors:
 - Josh Cheek
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-06 00:00:00.000000000 Z
+date: 2015-01-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parser
@@ -16,7 +16,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: 2.2.0.2
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: 2.2.0.2
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
@@ -124,8 +124,8 @@ files:
 - Readme.md
 - bin/seeing_is_believing
 - docs/example.gif
-- docs/for-presentations
 - docs/frog-brown.png
+- docs/sib-streaming.gif
 - features/deprecated-flags.feature
 - features/errors.feature
 - features/examples.feature
@@ -140,12 +140,13 @@ files:
 - lib/seeing_is_believing/binary/align_line.rb
 - lib/seeing_is_believing/binary/annotate_end_of_file.rb
 - lib/seeing_is_believing/binary/annotate_every_line.rb
-- lib/seeing_is_believing/binary/annotate_xmpfilter_style.rb
-- lib/seeing_is_believing/binary/comment_formatter.rb
+- lib/seeing_is_believing/binary/annotate_marked_lines.rb
 - lib/seeing_is_believing/binary/comment_lines.rb
 - lib/seeing_is_believing/binary/commentable_lines.rb
-- lib/seeing_is_believing/binary/interpret_flags.rb
-- lib/seeing_is_believing/binary/parse_args.rb
+- lib/seeing_is_believing/binary/config.rb
+- lib/seeing_is_believing/binary/data_structures.rb
+- lib/seeing_is_believing/binary/engine.rb
+- lib/seeing_is_believing/binary/format_comment.rb
 - lib/seeing_is_believing/binary/remove_annotations.rb
 - lib/seeing_is_believing/binary/rewrite_comments.rb
 - lib/seeing_is_believing/code.rb
@@ -154,20 +155,26 @@ files:
 - lib/seeing_is_believing/evaluate_by_moving_files.rb
 - lib/seeing_is_believing/event_stream/consumer.rb
 - lib/seeing_is_believing/event_stream/events.rb
+- lib/seeing_is_believing/event_stream/handlers/debug.rb
+- lib/seeing_is_believing/event_stream/handlers/record_exitstatus.rb
+- lib/seeing_is_believing/event_stream/handlers/stream_json_events.rb
+- lib/seeing_is_believing/event_stream/handlers/update_result.rb
 - lib/seeing_is_believing/event_stream/producer.rb
-- lib/seeing_is_believing/event_stream/update_result.rb
 - lib/seeing_is_believing/hard_core_ensure.rb
-- lib/seeing_is_believing/inspect_expressions.rb
-- lib/seeing_is_believing/parser_helpers.rb
+- lib/seeing_is_believing/hash_struct.rb
 - lib/seeing_is_believing/result.rb
 - lib/seeing_is_believing/the_matrix.rb
 - lib/seeing_is_believing/version.rb
 - lib/seeing_is_believing/wrap_expressions.rb
+- lib/seeing_is_believing/wrap_expressions_with_inspect.rb
 - seeing_is_believing.gemspec
-- spec/binary/comment_formatter_spec.rb
+- spec/binary/alignment_specs.rb
 - spec/binary/comment_lines_spec.rb
-- spec/binary/interpret_flags_spec.rb
-- spec/binary/parse_args_spec.rb
+- spec/binary/config_spec.rb
+- spec/binary/engine_spec.rb
+- spec/binary/format_comment_spec.rb
+- spec/binary/marker_spec.rb
+- spec/binary/options_spec.rb
 - spec/binary/remove_annotations_spec.rb
 - spec/binary/rewrite_comments_spec.rb
 - spec/code_spec.rb
@@ -175,6 +182,7 @@ files:
 - spec/evaluate_by_moving_files_spec.rb
 - spec/event_stream_spec.rb
 - spec/hard_core_ensure_spec.rb
+- spec/hash_struct_spec.rb
 - spec/seeing_is_believing_spec.rb
 - spec/spec_helper.rb
 - spec/wrap_expressions_spec.rb
@@ -250,10 +258,13 @@ test_files:
 - features/regression.feature
 - features/support/env.rb
 - features/xmpfilter-style.feature
-- spec/binary/comment_formatter_spec.rb
+- spec/binary/alignment_specs.rb
 - spec/binary/comment_lines_spec.rb
-- spec/binary/interpret_flags_spec.rb
-- spec/binary/parse_args_spec.rb
+- spec/binary/config_spec.rb
+- spec/binary/engine_spec.rb
+- spec/binary/format_comment_spec.rb
+- spec/binary/marker_spec.rb
+- spec/binary/options_spec.rb
 - spec/binary/remove_annotations_spec.rb
 - spec/binary/rewrite_comments_spec.rb
 - spec/code_spec.rb
@@ -261,6 +272,7 @@ test_files:
 - spec/evaluate_by_moving_files_spec.rb
 - spec/event_stream_spec.rb
 - spec/hard_core_ensure_spec.rb
+- spec/hash_struct_spec.rb
 - spec/seeing_is_believing_spec.rb
 - spec/spec_helper.rb
 - spec/wrap_expressions_spec.rb

data/docs/for-presentations

@@ -1,33 +0,0 @@
-# intro
-  # show the website!
-  # omg, what's it do?
-  # integrates with the editors
-
-# walk through example of how to use it
-  # make a user class or something
-  # show the -n flag
-
-# features
-  # iteration
-  # method and invocations
-  # multilinezzz
-  # mutliple levels of nesting (e.g. class definition)
-  # printing to stdout/stderr, respecting DATA segment
-  # respecting macros
-  # exceptions displayed where they occur
-  # records hash results
-  # syntax errors
-  # total fucking failure
-
-# show the snippets
-  # s_arb
-  # s_sinatra
-  # s_nokogiri
-  # s_reflection
-
-# Show how to customize
-  # --line-length n
-  # --result-length n
-  # --alignment-strategy name
-  # --timeout n
-  # --debug

data/lib/seeing_is_believing/binary/annotate_xmpfilter_style.rb

@@ -1,128 +0,0 @@
-require 'seeing_is_believing/code'
-
-class SeeingIsBelieving
-  module Binary
-    class AnnotateXmpfilterStyle
-      def self.prepare_body(uncleaned_body, marker_regexes)
-        require 'seeing_is_believing/binary/remove_annotations'
-        RemoveAnnotations.call uncleaned_body, false, marker_regexes
-      end
-
-      def self.expression_wrapper(markers, marker_regexes)
-        lambda do |program, filename, number_of_captures|
-          inspect_linenos = []
-          pp_linenos      = []
-          Code.new(program).inline_comments.each do |c|
-            next unless c.text[marker_regexes[:value]]
-            c.whitespace_col == 0 ? pp_linenos      << c.line_number - 1
-                                  : inspect_linenos << c.line_number
-          end
-
-          InspectExpressions.call program,
-                                  filename,
-                                  number_of_captures,
-                                  before_all: -> {
-                                    # TODO: this is duplicated with the InspectExpressions class
-                                    number_of_captures_as_str = number_of_captures.inspect
-                                    number_of_captures_as_str = 'Float::INFINITY' if number_of_captures == Float::INFINITY
-                                    "require 'pp'; $SiB.filename = #{filename.inspect}; $SiB.max_line_captures = #{number_of_captures_as_str}; $SiB.num_lines = #{program.lines.count}; "
-                                  },
-                                  after_each: -> line_number {
-                                    should_inspect = inspect_linenos.include?(line_number)
-                                    should_pp      = pp_linenos.include?(line_number)
-                                    inspect        = "$SiB.record_result(:inspect, #{line_number}, v)"
-                                    pp             = "$SiB.record_result(:pp, #{line_number}, v) { PP.pp v, '', 74 }" # TODO: Is 74 the right value? Prob not, I think it's 80(default width) - 1(comment width) - 5(" => {"), but if I allow indented `# => `, then that would need to be less than 74 (idk if I actually do this or not, though :P)
-
-                                    if    should_inspect && should_pp then ").tap { |v| #{inspect}; #{pp} }"
-                                    elsif should_inspect              then ").tap { |v| #{inspect} }"
-                                    elsif should_pp                   then ").tap { |v| #{pp} }"
-                                    else                                   ")"
-                                    end
-                                  }
-        end
-      end
-
-      def self.call(body, results, options)
-        new(body, results, options).call
-      end
-
-      def initialize(body, results, options={})
-        @options = options
-        @body    = body
-        @results = results
-      end
-
-      # TODO: I think that this should respect the alignment strategy
-      # and we should just add a new alignment strategy for default xmpfilter style
-      def call
-        @new_body ||= begin
-          # TODO: doesn't currently realign output markers, do we want to do that?
-          require 'seeing_is_believing/binary/rewrite_comments'
-          require 'seeing_is_believing/binary/comment_formatter'
-          always_rewrite = []
-
-          if @results.has_exception?
-            exception_result  = sprintf "%s: %s", @results.exception.class_name, @results.exception.message.gsub("\n", '\n')
-            exception_lineno  = @results.exception.line_number
-            always_rewrite << exception_lineno
-          end
-
-          new_body = RewriteComments.call @body, always_rewrite: always_rewrite do |comment|
-            exception_on_line  = exception_lineno == comment.line_number
-            annotate_this_line = comment.text[value_regex]
-            pp_annotation      = annotate_this_line && comment.whitespace_col.zero?
-            normal_annotation  = annotate_this_line && !pp_annotation
-            if exception_on_line && annotate_this_line
-              [comment.whitespace, CommentFormatter.call(comment.text_col, value_marker, exception_result, @options)]
-            elsif exception_on_line
-              whitespace = comment.whitespace
-              whitespace = " " if whitespace.empty?
-              [whitespace, CommentFormatter.call(comment.line_number, exception_marker, exception_result, @options)]
-            elsif normal_annotation
-              result = @results[comment.line_number].map { |result| result.gsub "\n", '\n' }.join(', ')
-              [comment.whitespace, CommentFormatter.call(comment.text_col, value_marker, result, @options)]
-            elsif pp_annotation
-              # result = sprintf "%s: %s", @results.exception.class_name, @results.exception.message.gsub("\n", '\n')
-              # CommentFormatter.call(line.size, exception_marker, result, options)
-              # TODO: check that having multiple mult-line output values here looks good (e.g. avdi's example in a loop)
-              result          = @results[comment.line_number-1, :pp].map { |result| result.chomp }.join(', ')
-              comment_lines   = result.each_line.map.with_index do |comment_line, result_offest|
-                if result_offest == 0
-                  CommentFormatter.call(comment.whitespace_col, value_marker, comment_line.chomp, @options)
-                else
-                  CommentFormatter.call(comment.whitespace_col, nextline_marker, comment_line.chomp, @options)
-                end
-              end
-              [comment.whitespace, comment_lines.join("\n")]
-            else
-              [comment.whitespace, comment.text]
-            end
-          end
-
-          require 'seeing_is_believing/binary/annotate_end_of_file'
-          AnnotateEndOfFile.add_stdout_stderr_and_exceptions_to new_body, @results, @options
-
-          # What's w/ this debugger? maybe this should move higher?
-          @options.fetch(:debugger).context "OUTPUT"
-          new_body
-        end
-      end
-
-      def value_marker
-        @value_marker ||= @options.fetch(:markers).fetch(:value)
-      end
-
-      def nextline_marker
-        @xnextline_marker ||= ('#' + ' '*value_marker.size.pred)
-      end
-
-      def exception_marker
-        @exception_marker ||= @options.fetch(:markers).fetch(:exception)
-      end
-
-      def value_regex
-        @value_regex ||= @options.fetch(:marker_regexes).fetch(:value)
-      end
-    end
-  end
-end

data/lib/seeing_is_believing/binary/interpret_flags.rb

@@ -1,156 +0,0 @@
-# Debugger initialization happens here
-require 'seeing_is_believing/debugger'
-
-# Alignment decision happens here
-require 'seeing_is_believing/binary/align_file'
-require 'seeing_is_believing/binary/align_line'
-require 'seeing_is_believing/binary/align_chunk'
-
-# Evaluator decision happens here
-require 'seeing_is_believing/evaluate_by_moving_files'
-
-# Annotator decision happens here
-require 'seeing_is_believing/binary/annotate_every_line'
-require 'seeing_is_believing/binary/annotate_xmpfilter_style'
-
-class SeeingIsBelieving
-  module Binary
-    class InterpretFlags
-      def self.to_regex(string)
-        flag_to_bit = {'i' => 0b001, 'x' => 0b010, 'm' => 0b100}
-        string =~ %r{\A/(.*)/([mxi]*)\Z}
-        Regexp.new ($1||string),
-                   ($2||"").each_char.inject(0) { |bits, flag| bits|flag_to_bit[flag] }
-      end
-
-
-      def self.attr_predicate(name)
-        define_method("#{name}?") { predicates.fetch name }
-      end
-      attr_predicate :print_version
-      attr_predicate :inherit_exit_status
-      attr_predicate :result_as_json
-      attr_predicate :print_help
-      attr_predicate :print_cleaned
-      attr_predicate :provided_filename_dne
-      attr_predicate :file_is_on_stdin
-
-      def self.attr_attribute(name)
-        define_method(name) { attributes.fetch name }
-      end
-      attr_attribute :annotator
-      attr_attribute :help_screen
-      attr_attribute :debugger
-      attr_attribute :markers
-      attr_attribute :marker_regexes
-      attr_attribute :timeout
-      attr_attribute :filename
-      attr_attribute :body
-      attr_attribute :annotator_options
-      attr_attribute :prepared_body
-      attr_attribute :lib_options
-      attr_attribute :errors
-
-      def initialize(flags, stdin, stdout)
-        # Some simple attributes
-        self.attributes = {}
-        attributes[:errors]         = flags.fetch(:errors)
-        attributes[:markers]        = flags.fetch(:markers) # TODO: Should probably object-ify these
-        attributes[:marker_regexes] = flags.fetch(:marker_regexes).each_with_object({}) { |(k, v), rs| rs[k] = self.class.to_regex v }
-        attributes[:timeout]        = flags.fetch(:timeout) # b/c binary prints this out in the error message  TODO: rename seconds_until_timeout
-        attributes[:filename]       = flags.fetch(:filename)
-
-        # All predicates
-        self.predicates = {}
-        predicates[:print_version]         = flags.fetch(:version) # TODO: rename rhs to print_version ?
-        predicates[:inherit_exit_status]   = flags.fetch(:inherit_exit_status)
-        predicates[:result_as_json]        = flags.fetch(:result_as_json)
-        predicates[:print_help]            = !!flags.fetch(:help)
-        predicates[:print_cleaned]         = flags.fetch(:clean) # TODO: Better name on rhs
-        predicates[:provided_filename_dne] = !!(filename && !File.exist?(filename)) # TODO: Should this just be an error in errors table?
-        predicates[:file_is_on_stdin]      = (!filename && !flags.fetch(:program_from_args))
-
-        # Polymorphism, y'all!
-        attributes[:annotator]   = (flags.fetch(:xmpfilter_style) ? AnnotateXmpfilterStyle                     : AnnotateEveryLine)
-        attributes[:help_screen] = flags.fetch(:help) == 'help'   ? flags.fetch(:short_help_screen)            : flags.fetch(:long_help_screen)
-        attributes[:debugger]    = flags.fetch(:debug)            ? Debugger.new(stream: stdout, colour: true) : Debugger.new(stream: nil)
-        attributes[:body]        = ((print_version? || print_help?) && String.new)    ||
-                                   flags.fetch(:program_from_args)                    ||
-                                   (file_is_on_stdin? && stdin.read)                  ||
-                                   (File.read filename unless provided_filename_dne?) ||
-                                   String.new
-
-        # Attributes that depend on predicates
-        attributes[:prepared_body] = body && annotator.prepare_body(body, marker_regexes)
-
-        # The lib's options (passed to SeeingIsBelieving.new)
-        attributes[:lib_options] = {
-          evaluate_with:      EvaluateByMovingFiles,
-          filename:           (flags.fetch(:as) || filename),
-          stdin:              (file_is_on_stdin? ? '' : stdin),
-          require:            (['seeing_is_believing/the_matrix'] + flags.fetch(:require)), # TODO: rename requires: files_to_require, or :requires or maybe :to_require
-          load_path:          ([File.expand_path('../../..', __FILE__)] + flags.fetch(:load_path)),
-          encoding:           flags.fetch(:encoding),
-          timeout:            timeout,
-          debugger:           debugger,
-          number_of_captures: flags.fetch(:number_of_captures), # TODO: Rename to max_number_of_captures
-          record_expressions: annotator.expression_wrapper(markers, marker_regexes), # TODO: rename to wrap_expressions
-        }
-
-        # The annotator's options (passed to annotator.call)
-        attributes[:annotator_options] = {
-          alignment_strategy: extract_alignment_strategy(flags.fetch(:alignment_strategy), errors),
-          debugger:           debugger,
-          markers:            markers,
-          marker_regexes:     marker_regexes,
-          max_line_length:    flags.fetch(:max_line_length),
-          max_result_length:  flags.fetch(:max_result_length),
-        }
-
-        # Some error checking
-        if 1 < flags.fetch(:filenames).size
-          errors << "Can only have one filename, but had: #{flags.fetch(:filenames).map(&:inspect).join ', '}"
-        elsif filename && flags.fetch(:program_from_args)
-          errors << "You passed the program in an argument, but have also specified the filename #{filename.inspect}"
-        end
-      end
-
-      def inspect
-        inspected = "#<#{self.class.name.inspect}\n"
-        inspected << "  --PREDICATES--\n"
-        predicates.each do |predicate, value|
-          inspected << inspect_line(sprintf "    %-25s %p", predicate.to_s+"?", value)
-        end
-        inspected << "  --ATTRIBUTES--\n"
-        attributes.each do |predicate, value|
-          inspected << inspect_line(sprintf "    %-20s %p", predicate.to_s, value)
-        end
-        inspected << ">"
-        inspected
-      end
-
-      private
-
-      attr_accessor :predicates, :attributes
-
-      def extract_alignment_strategy(strategy_name, errors)
-        strategies = {'file' => AlignFile, 'chunk' => AlignChunk, 'line' => AlignLine}
-        if strategies[strategy_name]
-          strategies[strategy_name]
-        elsif strategy_name
-          errors << "alignment-strategy does not know #{strategy_name}, only knows: #{strategies.keys.join(', ')}"
-        else
-          errors << "alignment-strategy expected an alignment strategy as the following argument but did not see one"
-        end
-      end
-
-      def inspect_line(line)
-        if line.size < 78
-          line << "\n"
-        else
-          line[0, 75] << "...\n"
-        end
-      end
-    end
-  end
-end

data/lib/seeing_is_believing/binary/parse_args.rb

@@ -1,263 +0,0 @@
-# encoding: utf-8
-
-require 'seeing_is_believing/version' # We print the version in the output
-
-class SeeingIsBelieving
-  module Binary
-    class ParseArgs
-      def self.default_markers
-        { value:     '# => ',
-          exception: '# ~> ',
-          stdout:    '# >> ',
-          stderr:    '# !> ',
-        }
-      end
-
-      # TODO: rename to default_marker_regexes ...or turn into fkn objects
-      def self.marker_regexes
-        { value:     '^#\s*=>\s*',
-          exception: '^#\s*~>\s*',
-          stdout:    '^#\s*>>\s*',
-          stderr:    '^#\s*!>\s*',
-        }
-      end
-
-      def self.call(args)
-        new(args).call
-      end
-
-      def initialize(args)
-        self.args = args.dup
-      end
-
-      def call
-        @result ||= begin
-          until args.empty?
-            case (arg = args.shift)
-            when '-h',  '--help'                then flags[:help]                = 'help'
-            when '-h+', '--help+'               then flags[:help]                = 'help+'
-            when '-c',  '--clean'               then flags[:clean]               = true
-            when '-v',  '--version'             then flags[:version]             = true
-            when '-x',  '--xmpfilter-style'     then flags[:xmpfilter_style]     = true
-            when '-i',  '--inherit-exit-status' then flags[:inherit_exit_status] = true
-            when '-j',  '--json'                then flags[:result_as_json]      = true
-            when '-g',  '--debug'               then flags[:debug]               = true
-            when        '--safe'                then flags[:safe]                = true
-            when '-d',  '--line-length'         then extract_positive_int_for :max_line_length,    arg
-            when '-D',  '--result-length'       then extract_positive_int_for :max_result_length,  arg
-            when '-n',  '--number-of-captures'  then extract_positive_int_for :number_of_captures, arg
-            when '-t',  '--timeout'             then extract_non_negative_float_for :timeout,      arg
-            when '-r',  '--require'             then next_arg("#{arg} expected a filename as the following argument but did not see one")  { |filename|   flags[:require]           << filename }
-            when '-I',  '--load-path'           then next_arg("#{arg} expected a directory as the following argument but did not see one") { |dir|        flags[:load_path]         << dir }
-            when '-e',  '--program'             then next_arg("#{arg} expected a program as the following argument but did not see one")   { |program|    flags[:program_from_args] =  program }
-            when '-a',  '--as'                  then next_arg("#{arg} expected a filename as the following argument but did not see one")  { |filename|   flags[:as]                =  filename }
-            when '-s',  '--alignment-strategy'  then flags[:alignment_strategy] = args.shift
-            when /\A-K(.+)/                     then flags[:encoding] = $1
-            when '-K', '--encoding'             then next_arg("#{arg} expects an encoding, see `man ruby` for possibile values") { |encoding| flags[:encoding] = encoding }
-            when        '--shebang'             then next_arg("#{arg} is deprecated, SiB now uses the Ruby it was invoked with")           { |executable| flags[:deprecated_flags] << '--shebang' << executable }
-            when /^(-.|--.*)$/                  then flags[:errors] << "Unknown option: #{arg.inspect}" # unknown flags
-            when /^-[^-]/                       then args.unshift *normalize_shortflags(arg)
-            else
-              flags[:filenames] << arg
-              flags[:filename] = arg
-            end
-          end
-          flags
-        end
-      end
-
-
-
-      private
-
-      attr_accessor :args
-
-      def flags
-        @flags ||= {
-          as:                  nil,
-          filenames:           [],
-          help:                nil,
-          encoding:            nil,
-          debug:               false,
-          version:             false,
-          clean:               false,
-          xmpfilter_style:     false,
-          inherit_exit_status: false,
-          program_from_args:   nil,
-          filename:            nil,
-          max_line_length:     Float::INFINITY,
-          max_result_length:   Float::INFINITY,
-          number_of_captures:  Float::INFINITY,
-          timeout:             0, # timeout lib treats this as infinity
-          errors:              [],
-          require:             ['seeing_is_believing/the_matrix'],
-          load_path:           [],
-          alignment_strategy:  'chunk',
-          result_as_json:      false,
-          markers:             self.class.default_markers,
-          marker_regexes:      self.class.marker_regexes,
-          short_help_screen:   self.class.help_screen(false),
-          long_help_screen:    self.class.help_screen(true),
-          safe:                false,
-          deprecated_flags:    [],
-        }
-      end
-
-      def normalize_shortflags(consolidated_shortflag)
-        shortflags = consolidated_shortflag[1..-1].chars.to_a # to_a for 1.9.3 -.-
-        plusidx    = shortflags.index('+') || 0
-        if 0 < plusidx
-          shortflags[plusidx-1] << '+'
-          shortflags.delete_at plusidx
-        end
-        shortflags.map { |flag| "-#{flag}" }
-      end
-
-      def next_arg(error_message, &success_block)
-        arg = args.shift
-        arg ? success_block.call(arg) : (flags[:errors] << error_message)
-      end
-
-      def extract_positive_int_for(key, flag)
-        string = args.shift
-        int    = string.to_i
-        if int.to_s == string && 0 < int
-          flags[key] = int
-        else
-          flags[:errors] << "#{flag} expects a positive integer argument"
-        end
-      end
-
-      def extract_non_negative_float_for(key, flag)
-        float = Float args.shift
-        raise if float < 0
-        flags[key] = float
-      rescue
-        flags[:errors] << "#{flag} expects a positive float or integer argument"
-      end
-    end
-
-    def ParseArgs.help_screen(include_examples, markers=default_markers)
-      value_marker     = markers.fetch(:value)
-      exception_marker = markers.fetch(:exception)
-      stdout_marker    = markers.fetch(:stdout)
-      stderr_marker    = markers.fetch(:stderr)
-
-<<FLAGS + if include_examples then <<EXAMPLES else '' end
-Usage: seeing_is_believing [options] [filename]
-
-  seeing_is_believing is a program and library that will evaluate a Ruby file and capture/display the results.
-
-  If no filename is provided, the binary will read the program from standard input.
-
-  -d,  --line-length n           # max length of the entire line (only truncates results, not source lines)
-  -D,  --result-length n         # max length of the portion after the "#{value_marker}"
-  -n,  --number-of-captures n    # how many results to capture for a given line
-                                   if you had 1 million results on a line, it could take a long time to record
-                                   and serialize them, you might limit it to 1000 results as an optimization
-  -s,  --alignment-strategy name # select the alignment strategy:
-                                   chunk (DEFAULT) =>  each chunk of code is at the same alignment
-                                   file            =>  the entire file is at the same alignment
-                                   line            =>  each line is at its own alignment
-  -t,  --timeout n               # timeout limit in seconds when evaluating source file (ex. -t 0.3 or -t 3)
-  -I,  --load-path dir           # a dir that should be added to the $LOAD_PATH
-  -r,  --require file            # additional files to be required before running the program
-  -e,  --program program         # Pass the program to execute as an argument
-  -K,  --encoding encoding       # sets file encoding, equivalent to Ruby's -Kx (see `man ruby` for valid values)
-  -a,  --as filename             # run the program as if it was the specified filename
-  -c,  --clean                   # remove annotations from previous runs of seeing_is_believing
-  -g,  --debug                   # print debugging information (useful if program is fucking up, or to better understand what SiB does)
-  -x,  --xmpfilter-style         # annotate marked lines instead of every line
-  -j,  --json                    # print results in json format (i.e. so another program can consume them)
-  -i,  --inherit-exit-status     # exit with the exit status of the program being evaluated
-       --shebang ruby-executable # if you want SiB to use some ruby other than the one in the path
-  -v,  --version                 # print the version (#{VERSION})
-  -h,  --help                    # help screen without examples
-  -h+, --help+                   # help screen with examples
-FLAGS
-
-Examples: A few examples, for a more comprehensive set of examples, check out features/flags.feature
-
-  Run the file f.rb
-    $ echo __FILE__ > f.rb; seeing_is_believing f.rb
-    __FILE__  #{value_marker}"f.rb"
-
-  Aligning comments
-    $ ruby -e 'puts "123\\n4\\n\\n567890"' > f.rb
-
-
-    $ seeing_is_believing f.rb -s line
-    123  #{value_marker}123
-    4  #{value_marker}4
-
-    567890  #{value_marker}567890
-
-
-    $ seeing_is_believing f.rb -s chunk
-    123  #{value_marker}123
-    4    #{value_marker}4
-
-    567890  #{value_marker}567890
-
-
-    $ seeing_is_believing f.rb -s file
-    123     #{value_marker}123
-    4       #{value_marker}4
-
-    567890  #{value_marker}567890
-
-  Run against standard input
-    $ echo '3.times { |i| puts i }' | seeing_is_believing
-    2.times { |i| puts i }  #{value_marker}2
-
-    #{stdout_marker}0
-    #{stdout_marker}1
-
-  Run against a library you're working on by fixing the load path
-    $ seeing_is_believing -I lib f.rb
-
-  Load up some library (can be used in tandem with -I)
-    $ seeing_is_believing -r pp -e 'pp [[*1..15],[*15..30]]; nil'
-    pp [[*1..15],[*15..30]]; nil  #{value_marker}nil
-
-    #{stdout_marker}[[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
-    #{stdout_marker} [15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30]]
-
-  Only update the lines you've marked
-    $ ruby -e 'puts "1\\n2 # =>\\n3"' | seeing_is_believing -x
-    1
-    2 #{value_marker}2
-    3
-
-  Set a timeout (especially useful if running via an editor)
-    $ seeing_is_believing -e 'loop { sleep 1 }' -t 3
-    Timeout Error after 3.0 seconds!
-
-  Set the encoding to utf-8
-    $ seeing_is_believing -Ku -e '"⛄ "'
-    "⛄ "  #{value_marker}"⛄ "
-
-  The exit status will be 1 if the error is displayable inline
-    $ seeing_is_believing -e 'raise "omg"'; echo $?
-    raise "omg"  #{exception_marker}RuntimeError: omg
-    1
-
-  The exit status will be 2 if the error is not displayable
-    $ seeing_is_believing -e 'a='; echo $status
-    -:1: syntax error, unexpected $end
-    2
-
-  Run with previous output
-    $ echo "1+1  #{value_marker}old-value" | seeing_is_believing
-    1+1  #{value_marker}2
-
-    $ echo "1+1  #{value_marker}old-value" | seeing_is_believing --clean
-    1+1
-
-  If your Ruby binary is named something else (e.g. ruby2.0)
-    $ ruby2.0 -S seeing_is_believing --shebang ruby2.0 -e '123'
-    123  #{value_marker}123
-EXAMPLES
-    end
-  end
-end