dokaz 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    M2I3NzJkY2RlNjVjNjVmYzI1YmRiNmU0MmU0MjZiZmJlZDI3YzdkYw==
+  data.tar.gz: !binary |-
+    ODljNjkzMjE2MjI1NTlkZmQ2Yzk5ZGJmMzJmYzE3NDU1MTBkMDljYw==
+SHA512:
+  metadata.gz: !binary |-
+    NzFkMWI0NDMxZDlhYjYwYzg4MjZmOWFmYjEzNTNiNGI0OTQyMzM4ZTYxMzg2
+    ZmQzZTFiZGU2YTZjNzhmYjIzOTQyYjllNjQyNDYxYTdhYmMyNzAzMWNiODUw
+    N2Q3NmNhZDgxZGM3YjQ3MDkzMTM0MTNjY2VkZmQ4YmMzNmQzODM=
+  data.tar.gz: !binary |-
+    ZTU4ZjRmMzAyNjA2MTlkNzI3NTYyMGY5MWJkYTdjMjMwZWMzYjJhNDk5OTRk
+    ZWY3MDI0NTQxYmY3NzZjMTA2N2MyNjFlODU4MTAyMDhmYjQwZmQxZjhkMjJj
+    YmQ2OTYyNmJhY2VmYmEyYjVlMzY3OTRkMGVkMzVhMGE5NWUwYjk=

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014-15 Victor 'Zverok' Shepelev
+
+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,82 @@
+# Dokaz
+
+Dokaz (До́каз) means "proof" in Ukrainian.
+
+**Dokaz** gem allows you to check all code inside your documentation, and
+see what it outputs.
+
+It just finds all pieces of <pre>```ruby</pre>-marked code in your .md
+files, tries to run it and shows you the consequences.
+
+## Install
+
+Just as usual -- by adding `gem 'dokaz'` to your Gemfile then running
+`bundle install`.
+
+Or `[sudo] gem install dokaz`
+
+## Usage
+
+```
+dokaz --help
+
+Usage: dokaz [patterns] [options]
+
+Patterns:
+  File.md             one file
+  File.md:15          only block around line 15
+  folder/*.md         all files in folder
+
+Options:
+  -r, --require      Additional files to require, comma-separated
+  -f, --format       Output format ("spec" or "show[case]")
+      --help         Shows this message
+```
+
+Dokaz respects `.dokaz` file in local folder, which should be just its
+options, each on newline.
+
+## Output formats
+
+* "spec" -- simple "does it work?" check:
+
+<img src="https://raw.github.com/zverok/dokaz/master/screenshots/spec.png" alt="--format spec"/>
+
+* "showcase" or just "show" -- pretty copy-pasteable output of what
+  sample code returns and prints:
+
+<img src="https://raw.github.com/zverok/dokaz/master/screenshots/showcase.png" alt="--format showcase"/>
+
+You can just insert it back into your docs.
+
+## Using it for your project's README
+
+* Add to project's Gemfile (preferably to `:dev` group) `gem 'dokaz'`
+* Create file for example `spec/dokaz_helpers.rb`, containing all
+  initialization code to include your project files
+* Create file `.dokaz`, containing:
+```
+README.md
+--require ./spec/dokaz_helpers.rb
+```
+* Run `bundle exec dokaz`
+
+## Using it for your project's GitHub wiki
+
+* Do the same as above
+* Clone your project's wiki to some directory (outside your project's directory!):
+  `git clone git:github.com/myusername/myproject.wiki.git`
+* At your project's directory, run `bundle exec dokaz /path/to/cloned/wiki/*.md`
+
+## Known issues
+
+* ridiculously simple, naïve and not tested; though, works for me;
+* all code from all blocks is evaluated in same context (so, if block
+  from one documentation file defines some class or variable, it is
+  visible to all other blocks). Typically, it is reasonable behaviour,
+  yet can produce unwanted effects when your docs demonstrate some
+  metaprogramming or do some serious side-effects.
+
+## License
+
+MIT

data/bin/dokaz

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+require 'slop'
+
+$:.unshift 'lib'
+require 'dokaz'
+
+if File.exists?('.dokaz')
+  ARGV.push(*File.read('.dokaz').split("\n"))
+end
+
+patterns = []
+patterns << ARGV.shift until ARGV.empty? || ARGV.first =~ /^-/
+
+HELP = %Q{
+Usage: dokaz [patterns] [options]
+
+Patterns:
+  File.md             one file
+  File.md:15          only block around line 15
+  folder/*.md         all files in folder
+
+Options:
+  -r, --require      Additional files to require, comma-separated
+  -f, --format       Output format ("spec" or "show[case]")
+      --help         Shows this message
+}
+
+options = Slop.parse do
+  on :r, :require=, "Additional files to require, comma-separated"
+  on :f, :format=, "Output format (spec or show[case])"
+  on :help
+end
+
+if patterns.empty? || options.help?
+  puts HELP
+  exit
+end
+
+Dokaz.new(patterns, options.to_hash).run

data/dokaz.gemspec

@@ -0,0 +1,30 @@
+Gem::Specification.new do |s|
+  s.name     = 'dokaz'
+  s.version  = '0.0.1'
+  s.authors  = ['Victor Shepelev']
+  s.email    = 'zverok.offline@gmail.com'
+  s.homepage = 'https://github.com/zverok/dokaz'
+
+  s.summary = 'Use your documentation as a specification'
+  s.licenses = ['MIT']
+
+  s.files = `git ls-files`.split($RS).reject do |file|
+    file =~ /^(?:
+    spec\/.*
+    |Gemfile
+    |Rakefile
+    |\.rspec
+    |\.gitignore
+    |\.rubocop.yml
+    |\.travis.yml
+    )$/x
+  end
+  s.require_paths = ["lib"]
+  s.executables << 'dokaz'
+
+  s.add_dependency 'ansi'
+  s.add_dependency 'slop', '~> 3'
+
+  s.add_development_dependency 'rspec', '~> 3'
+  s.add_development_dependency 'rspec-its', '~> 1'
+end

data/examples/README.md

@@ -0,0 +1,63 @@
+This file shows you how DocSpec work.
+
+Try this
+* `docspec examples/example.md`
+* `docspec examples/example.md --format showcase`
+
+## Example 1
+
+So, lets begin with simple ruby code:
+
+```ruby
+1 + 18
+```
+
+In default (check) mode, this first gives just green dot (it works!).
+In showcase mode you'll see what this code outputs; which allows you to
+paste it into your docs.
+
+## Example 2
+
+This is more complex code, try it:
+
+```ruby
+class A
+  def initialize(i)
+    @i = i
+  end
+
+  def sum(other)
+    @i + other
+  end
+end
+
+a = A.new(5)
+a.sum(3)
+```
+
+The code is evaluated in continuous manner, so, the `A` class and `a`
+variable are already defined:
+
+```ruby
+a.sum(8)
+```
+
+This code not only returns values, but also outputs something to STDOUT:
+
+```ruby
+puts a.sum(10)
+```
+
+This code throws an error:
+
+```ruby
+100 / 0
+```
+
+This code requires additional require:
+
+```ruby
+BigDecimal.new("0")
+```
+
+Try to run it with option `--require cgi`.

data/lib/dokaz.rb

@@ -0,0 +1,70 @@
+# encoding: utf-8
+require 'irb'
+
+require_relative 'dokaz/parser'
+require_relative 'dokaz/io_helpers'
+require_relative 'dokaz/formatters'
+
+class Dokaz
+  FORMATTERS = {
+    'spec' => SpecFormatter,
+    'show' => ShowcaseFormatter,
+    'showcase' => ShowcaseFormatter
+  }
+  
+  def initialize(patterns, options = {})
+    @blocks = select_blocks(patterns)
+
+    if options[:require]
+      options[:require].split(',').each{|f| require f}
+    end
+
+    @formatter = FORMATTERS[options[:format] || 'spec'].new
+  end
+
+  def run
+    puts "Running #{@blocks.count} blocks from #{@blocks.map(&:file).uniq.count} files\n\n"
+    
+    @blocks.each do |b|
+      @formatter.start_block(b)
+      process_block(b)
+      @formatter.finish_block(b)
+    end
+    @formatter.finalize
+  end
+
+  private
+
+    def process_block(block)
+      lex = RubyLex.new
+      lex.set_input(SpecIO.new(block.code))
+      lex.each_top_level_statement do |line, line_no|
+        begin
+          res = nil
+          out = capture_output{
+            res = eval(line, TOPLEVEL_BINDING, block.file, block.line + line_no)
+          }
+          @formatter.output(line, res, out)
+        rescue => e
+          @formatter.output_err(line, e)
+          break
+        end
+      end
+    end
+
+    def capture_output(&block)
+      Out.new.capture(&block)
+    end
+
+    def select_blocks(patterns)
+      patterns.map{|pat|
+        path, ln = pat.split(':', 2)
+        files = Dir[path]
+        blocks = files.map{|f|
+          Parser.new(f).parse
+        }.flatten.select{|b|
+          ln ? b.inside?(ln.to_i) : true
+        }
+      }.flatten
+    end
+end

data/lib/dokaz/formatters.rb

@@ -0,0 +1,102 @@
+# encoding: utf-8
+require 'ansi/code'
+
+class Dokaz
+  class Formatter
+    def start_block(block)
+    end
+
+    def finish_block(block)
+    end
+
+    def finalize
+    end
+
+    def output(code, res, out)
+    end
+    
+    def output_err(code, e)
+    end
+
+    protected
+      def filter_backtrace(trace)
+        trace.take_while{|ln| ln !~ /lib\/dokaz/}
+      end
+  end
+  
+  class SpecFormatter < Formatter
+    def initialize
+      @ok = 0
+      @errors = []
+    end
+    
+    def start_block(block)
+      @err = false
+    end
+
+    def finish_block(block)
+      unless @err
+        @ok += 1 
+        print ANSI.green{'.'}
+      end
+    end
+
+    def finalize
+      puts
+      puts
+
+      @errors.each do |code, e|
+        puts code
+        puts( ANSI.red{"#{e.message} (#{e.class})\n  " + filter_backtrace(e.backtrace).join("\n  ") + "\n"})
+      end
+
+      puts
+      @errors.each do |code, e|
+        ln = e.backtrace.first.sub(/:in .*$/, '')
+        puts ANSI.red{"dokaz #{ln}"} + ANSI.cyan{" # #{e.message} (#{e.class})"}
+      end
+
+      puts
+      puts [
+        "#{@ok + @errors.count} total",
+        !@ok.zero? && ANSI.green{"#{@ok} ok"},
+        !@errors.empty? && ANSI.red{"#{@errors.count} errors"}
+      ].select{|l| l}.join(', ')
+      
+    end
+    
+    def output_err(code, e)
+      @errors << [code, e]
+      print ANSI.red{'F'}
+      @err = true
+    end
+  end
+
+  class ShowcaseFormatter < Formatter
+    def start_block(block)
+      puts "#{block.caption}\n#{'=' * block.caption.size}\n\n"
+    end
+    
+    def output(code, res, out)
+      puts code
+      unless out.empty?
+        puts comment("# Prints: \n#  " + out.split("\n").join("\n#    "))
+      end
+      puts comment("# => " + res.inspect.split("\n").join("\n#    "))
+    end
+
+    def output_err(code, e)
+      puts code
+      puts comment("# Throws: #{e.message} (#{e.class})")
+    end
+
+    def finish_block(block)
+      puts "\n\n"
+    end
+
+    private
+      def comment(str)
+        ANSI.dark{str}
+      end
+  end
+end

data/lib/dokaz/io_helpers.rb

@@ -0,0 +1,19 @@
+# encoding: utf-8
+class Dokaz
+  class SpecIO < StringIO
+    def encoding
+      string.encoding
+    end
+  end
+
+  class Out < StringIO
+    def capture(&block)
+      orig = $stdout
+      $stdout = self
+      yield
+      string.to_s
+    ensure
+      $stdout = orig
+    end
+  end
+end

data/lib/dokaz/parser.rb

@@ -0,0 +1,50 @@
+# encoding: utf-8
+require 'strscan'
+
+class Dokaz
+  class Block
+    attr_reader :code, :line, :file
+    def initialize(code, line, file)
+      @code, @line, @file = code, line, file
+    end
+
+    def end_line
+      line + code.count("\n")
+    end
+    
+    def caption
+      "#{file}:#{line}"
+    end
+
+    def inside?(ln)
+      (line..end_line).cover?(ln)
+    end
+  end
+  
+  class Parser
+    def initialize(path)
+      @path = path
+    end
+
+    def parse
+      res = []
+      ln = 0
+      scanner = StringScanner.new(File.read(@path))
+      loop do
+        text = scanner.scan_until(/\n```ruby\n/)
+        break unless text
+        
+        ln += text.count("\n")
+        code = scanner.scan_until(/\n```\n/)
+        if !code
+          res << Block.new(scanner.rest, ln, @path)
+          break
+        end
+        res << Block.new(code.sub(/```\Z/, ''), ln, @path)
+        ln += code.count("\n")
+      end
+
+      res
+    end
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: dokaz
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Victor Shepelev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-06-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ansi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: slop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1'
+description: 
+email: zverok.offline@gmail.com
+executables:
+- dokaz
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- bin/dokaz
+- dokaz.gemspec
+- examples/README.md
+- lib/dokaz.rb
+- lib/dokaz/formatters.rb
+- lib/dokaz/io_helpers.rb
+- lib/dokaz/parser.rb
+- screenshots/showcase.png
+- screenshots/spec.png
+homepage: https://github.com/zverok/dokaz
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+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: Use your documentation as a specification
+test_files: []
+has_rdoc: