Module: SeeingIsBelieving::Binary

Defined in:

lib/seeing_is_believing/binary.rb,
lib/seeing_is_believing/binary/config.rb,
lib/seeing_is_believing/binary/engine.rb,
lib/seeing_is_believing/binary/align_file.rb,
lib/seeing_is_believing/binary/align_line.rb,
lib/seeing_is_believing/binary/align_chunk.rb,
lib/seeing_is_believing/binary/comment_lines.rb,
lib/seeing_is_believing/binary/format_comment.rb,
lib/seeing_is_believing/binary/data_structures.rb,
lib/seeing_is_believing/binary/rewrite_comments.rb,
lib/seeing_is_believing/binary/commentable_lines.rb,
lib/seeing_is_believing/binary/remove_annotations.rb,
lib/seeing_is_believing/binary/annotate_every_line.rb,
lib/seeing_is_believing/binary/annotate_end_of_file.rb,
lib/seeing_is_believing/binary/annotate_marked_lines.rb

Defined Under Namespace

Modules: AnnotateEndOfFile, RewriteComments Classes: AlignChunk, AlignFile, AlignLine, AnnotateEveryLine, AnnotateMarkedLines, AnnotatorOptions, CommentLines, CommentableLines, Config, Engine, ErrorMessage, FormatComment, Marker, Markers, MustEvaluateFirst, RemoveAnnotations, SyntaxErrorMessage

Constant Summary

SUCCESS_STATUS =

0

DISPLAYABLE_ERROR_STATUS =

e.g. user code raises an exception (we can display this in the output)

1

NONDISPLAYABLE_ERROR_STATUS =

e.g. SiB was invoked incorrectly

2

Class Method Summary

• .call(argv, stdin, stdout, stderr) ⇒ Object
• .help_screen(markers) ⇒ Object
• .help_screen_extended(markers) ⇒ Object

Class Method Details

.call(argv, stdin, stdout, stderr) ⇒ Object

# File 'lib/seeing_is_believing/binary.rb', line 11

def self.call(argv, stdin, stdout, stderr)
  config = Config.new.parse_args(argv).finalize(stdin, stdout, stderr, File)
  engine = Engine.new config

  if config.print_help?
    stdout.puts config.help_screen
    return SUCCESS_STATUS
  end

  if config.print_version?
    stdout.puts SeeingIsBelieving::VERSION
    return SUCCESS_STATUS
  end

  if config.errors.any?
    stderr.puts *config.errors, *config.deprecations
    return NONDISPLAYABLE_ERROR_STATUS
  end

  if config.print_cleaned?
    stdout.print engine.cleaned_body
    return SUCCESS_STATUS
  end

  if engine.syntax_error?
    stderr.puts engine.syntax_error
    return NONDISPLAYABLE_ERROR_STATUS
  end

  engine.evaluate!

  if engine.timed_out?
    stderr.puts "Timeout Error after #{engine.timeout_seconds} seconds!"
    return NONDISPLAYABLE_ERROR_STATUS
  end

  if config.result_as_json?
    require 'json'
    stdout.puts JSON.dump(engine.result.as_json)
    return SUCCESS_STATUS
  elsif config.print_event_stream?
    # no op, the event stream handler has been printing it all along
  elsif config.debug?
    config.debugger.context("OUTPUT") { engine.annotated_body }
  else
    stdout.print engine.annotated_body
  end

  if config.inherit_exitstatus?
    engine.exitstatus
  elsif engine.exitstatus.zero?
    SUCCESS_STATUS
  else
    DISPLAYABLE_ERROR_STATUS
  end
end

.help_screen(markers) ⇒ Object

# File 'lib/seeing_is_believing/binary/config.rb', line 275

def Binary.help_screen(markers)
  value  = markers[:value][:prefix]
  stdout = markers[:stdout][:prefix]

  <<FLAGS
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.

Notes:

* If no filename or program (-e option) are provided, the program will read from standard input.
* The process's stdin will be passed to the program unless the program body is on stdin.
* The exit status will be:
  0 - No errors
  1 - Displayable error (e.g. code raises an exception while running)
  2 - Non-displayable error (e.g. a syntax error, a timeout)
  n - The program's exit status if the --inherit-exitstatus option is set

Options:
-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}"
-n,  --max-line-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-seconds s       # how long to evaluate the source file before timing out
                                 0 means it will never timeout (this is the default)
                                 accepts floating point values (e.g. 0.5 would timeout after half a second)
-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-body    # pass the program body 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
-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-exitstatus      # exit with the exit status of the program being evaluated
     --stream                  # a JSON stream of every event ias it is seen (such as recording a line)
     --ignore-unknown-flags    # don't error when flag is not in this list
                                 allows integrating code to support compatibility with future versions of SiB
-v,  --version                 # print the version (#{VERSION})
-h,  --help                    # help screen without examples
-h+, --help+                   # help screen with examples
FLAGS
end

.help_screen_extended(markers) ⇒ Object

# File 'lib/seeing_is_believing/binary/config.rb', line 326

def Binary.help_screen_extended(markers)
  value  = markers[:value][:prefix]
  stdout = markers[:stdout][:prefix]
  help_screen(markers) << <<EXAMPLES
Examples: A few examples, for a more comprehensive set of examples, check out features/flags.feature
NOTE: $'1\\n2' is the bash string literal for Ruby's "1\\n2"

Run the file myfile.rb
  $ echo __FILE__ > myfile.rb; seeing_is_believing myfile.rb
  __FILE__  #{value}"myfile.rb"

Run against standard input
  $ echo ':program' | seeing_is_believing
  :program  #{value}:program

Pass the program in an argument
  $ seeing_is_believing -e ':program'
  :program  #{value}:program

Remove previous output
  $ seeing_is_believing -e ":program" | seeing_is_believing --clean
  :program

Aligning comments
  $ seeing_is_believing -s line -e $'123\\n4\\n\\n567890'
  123  #{value}123
  4  #{value}4

  567890  #{value}567890


  $ seeing_is_believing -s chunk -e $'123\\n4\\n\\n567890'
  123  #{value}123
  4    #{value}4

  567890  #{value}567890


  $ seeing_is_believing -s file -e $'123\\n4\\n\\n567890'
  123     #{value}123
  4       #{value}4

  567890  #{value}567890

Run against a library you're working on by fixing the load path
  $ seeing_is_believing -I ./lib f.rb

Require a file before yours is run (can be used in tandem with -I)
  $ seeing_is_believing -r pp -e 'pp [[*1..5]]*5'
  pp [[*1..5]]*5  #{value}[[1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5]]

  #{stdout}[[1, 2, 3, 4, 5],
  #{stdout} [1, 2, 3, 4, 5],
  #{stdout} [1, 2, 3, 4, 5],
  #{stdout} [1, 2, 3, 4, 5],
  #{stdout} [1, 2, 3, 4, 5]]

Only update the lines you've marked
  $ seeing_is_believing -x -e $'1\\n2 # =>\\n3' |
  1
  2 #{value}2
  3

Display a complex structure across multiple lines
  $ seeing_is_believing -x -e $'{foo: 42, bar: {baz: 1, buz: 2, fuz: 3}, wibble: {magic_word: "xyzzy"}}\\n#{value}'
  {foo: 42, bar: {baz: 1, buz: 2, fuz: 3}, wibble: {magic_word: "xyzzy"}}
  #{value} {:foo=>42,
  #     :bar=>{:baz=>1, :buz=>2, :fuz=>3},
  #     :wibble=>{:magic_word=>"xyzzy"}}

Display a stream of events as they are seen
  $ seeing_is_believing -e $':a\\n:b\\n:c' --stream
  ["ruby_version",{"value":#{RUBY_VERSION.inspect}}]
  ["sib_version",{"value":#{SeeingIsBelieving::VERSION.inspect}}]
  ["filename",{"value":"/var/folders/7g/mbft22555w3_2nqs_h1kbglw0000gn/T/seeing_is_believing_temp_dir20150116-49548-kr0xop/program.rb"}]
  ["max_line_captures",{"value":-1,"is_infinity":true}]
  ["num_lines",{"value":3}]
  ["line_result",{"type":"inspect","line_number":1,"inspected":":a"}]
  ["line_result",{"type":"inspect","line_number":2,"inspected":":b"}]
  ["line_result",{"type":"inspect","line_number":3,"inspected":":c"}]
  ["event_stream_closed",{"side":"producer"}]
  ["stderr_closed",{"side":"producer"}]
  ["stdout_closed",{"side":"producer"}]
  ["exitstatus",{"value":0}]
  ["finished",{}]
EXAMPLES
end