Rstfilter

This tool prints a Ruby script with execution results.

$ cat sample.rb
a = 1
b = 2
c = a + b
puts "Hello" * c

$ rstfilter sample.rb -o
a = 1                                              #=> 1
b = 2                                              #=> 2
c = a + b                                          #=> 3
puts "Hello" * c                                   #=> nil
#out: HelloHelloHello

Installation

Add this line to your application's Gemfile:

gem 'rstfilter'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install rstfilter

Usage

Usage: rstfilter [options] SCRIPT
    -c, --comment                    Show result only on comment
    -o, --output                     Show output results
    -d, --decl                       Show results on declaration
        --no-exception               Do not show exception
        --pp                         Use pp to represent objects
    -n, --nextline                   Put comments on next line
        --comment-indent=NUM         Specify comment indent size (default: 50)
        --comment-pattern=PAT        Specify comment pattern of -c (default: '#=>')
        --coment-label=LABEL         Specify comment label (default: "")
    -e, --executable=COMMAND         Execute Ruby script with given command
        --no-filename                Execute -e command without filename
    -j, --json                       Print records in JSON format
        --ignore-pragma              Ignore pragma specifiers
        --rc RCFILE                  Load RCFILE
        --verbose                    Verbose mode

`-e` option

You can specify multiple -e options like that:

$ rstfilter -o sample.rb -eruby27:/home/ko1/.rbenv/versions/2.7.6/bin/ruby -e ruby30:/home/ko1/.rbenv/versions/3.0.4/bin/ruby
a = 1
#=> ruby27: 1
#=> ruby30: 1
b = 2
#=> ruby27: 2
#=> ruby30: 2
c = a + b
#=> ruby27: 3
#=> ruby30: 3
puts "Hello" * c
#=> ruby27: nil
#=> ruby30: nil
#ruby27:out: HelloHelloHello
#ruby30:out: HelloHelloHello

On this case, you can check results on multiple Ruby interpreters.

Comment style options

You can write above options in the script with #rstfilter ARGS... comment.

#rstfilter -c
a = 1
b = 2
c = a + b #=>

$ rstfilter sample.rb
#rstfilter -c
a = 1
b = 2
c = a + b #=> 3

RC file

You can specify rcfile in YAML file.

# rstfilter.yaml
default: -c
dir:
  '*/spec/*': -e rspec

rcfile accept two keys:

default: set default option
dir: pairs of a pattern and a option.

In this case, deafult option is -c and match files with the/spec/pattern applied with the given-e rspec` option.

Advanced demo

rstdemo.mp4

This video shows advanced usage to show the results with modified script immediately.

kv is another pager.
kv -w SCRIPT monitors SCRIPT file modification and reload it immediately.
kv --filter-process=cmd SCRIPT shows the result of cmd FILE as a filter.
Combination: kv -w --filter-command='rstfilter -a' SCRIPT shows modified script with execution results.

Implementation

With parser gem, rstfilter translates the given script and run it.

For example, the first example is translated to:

a = ::RSTFILTER__.record(1,4,1,5){1}
b = ::RSTFILTER__.record(2,4,2,5){2}
c = ::RSTFILTER__.record(3,4,3,9){::RSTFILTER__.record(3,4,3,5){a} + ::RSTFILTER__.record(3,8,3,9){b}}
::RSTFILTER__.record(4,0,4,16){puts ::RSTFILTER__.record(4,5,4,16){::RSTFILTER__.record(4,5,4,12){"Hello"} * ::RSTFILTER__.record(4,15,4,16){c}}}

and ::RSTFILTER__.record method records the results. After that, rstfilter prints the script with the results. --verbose option shows the translated script and collected results.

Contribution

Bug reports and pull requests are welcome on GitHub at https://github.com/ko1/rstfilter.

License

The gem is available as open source under the terms of the MIT License.

Aside

My motivation of this tool is to make it easy to annotate the script with execution results. For example, Ruby developer's meeting generates many code like: https://github.com/ruby/dev-meeting-log/blob/master/DevMeeting-2022-05-19.md
The name "Rst" stands for "Result". This tool is inspired from xmpfilter and original author Gotoken-san told me that "xmp" is stand for "Example" (he had wanted to make a support tool for lectures). Respect to the "xmp" mysterious word, I choosed "Rst".

rstfilter

Runtime