explain 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rvmrc

@@ -0,0 +1 @@
+rvm use rbx-head@explain --create

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in explain.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Josep M. Bach
+
+MIT License
+
+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,69 @@
+# explain
+
+Explain explains your Ruby code in natural language. It is intended to be a
+tool for beginners who aren't yet very familiar with programming.
+
+It is a work in progress (a bit rough on the edges), so don't be mad. It will
+get better over time ;)
+
+(Explain runs only on Rubinius.)
+
+## Installation
+
+Install Rubinius if you don't have it yet:
+
+    $ rvm install rbx-head
+    $ rvm use rbx-head
+
+Install explain as a gem:
+
+    $ gem install explain
+
+## Usage
+
+Given some example Ruby code, for example this in `examples/person.rb`:
+
+```ruby
+class Person
+  def walk(distance)
+    @distance += distance
+    @hunger += 2
+  end
+
+  def eat(food)
+    @hunger -= food.nutritional_value
+  end
+end
+```
+
+We execute `explain` from the command line:
+
+    $ explain examples/person.rb
+
+And it will output:
+
+    Let's describe the general attributes and behavior of any Person.
+
+    A Person can **walk**, given a specific distance. This is described as
+    follows: its distance will be its distance plus what we previously defined as
+    `distance`. Finally we return its hunger will be its hunger plus the number
+    2.. 
+
+    A Person can **eat**, given a specific food. This is described as follows:
+    Finally we return its hunger will be its hunger minus the result of calling
+    **nutritional_value** on what we previously defined as `food`..
+    And with this we're done describing a Person.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Who's this
+
+This was made by [Josep M. Bach (Txus)](http://txustice.me) under the MIT
+license. I'm [@txustice](http://twitter.com/txustice) on twitter (where you
+should probably follow me!).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/bin/explain

@@ -0,0 +1,5 @@
+#!/usr/bin/env rbx
+
+$: << 'lib'
+require 'explain'
+puts Explain.explain File.read(ARGV.first)

data/examples/person.rb

@@ -0,0 +1,10 @@
+class Person
+  def walk(distance)
+    @distance += distance
+    @hunger += 2
+  end
+
+  def eat(food)
+    @hunger -= food.nutritional_value
+  end
+end

data/explain.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'explain/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "explain"
+  gem.version       = Explain::VERSION
+  gem.authors       = ["Josep M. Bach"]
+  gem.email         = ["josep.m.bach@gmail.com"]
+  gem.description   = %q{Explain explains your Ruby code in natural language.}
+  gem.summary       = %q{Explain explains your Ruby code in natural language.}
+  gem.homepage      = "https://github.com/txus/explain"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+end

data/lib/explain.rb

@@ -0,0 +1,10 @@
+require "explain/version"
+require "explain/visitor"
+
+module Explain
+  def self.explain(code)
+    visitor = Visitor.new
+    visitor.visit(code.to_ast)
+    visitor.output
+  end
+end

data/lib/explain/version.rb

@@ -0,0 +1,3 @@
+module Explain
+  VERSION = "0.0.1"
+end

data/lib/explain/visitor.rb

@@ -0,0 +1,337 @@
+module Explain
+  class Visitor
+    def initialize
+      @output = []
+    end
+
+    def visit(node, in_sentence=false)
+      __send__ node.node_name, node, in_sentence
+    end
+
+    def emit(str)
+      @output.push str
+    end
+
+    def output
+      @output.join
+    end
+
+    def class(node, in_sentence=false)
+      @in_class = node.name.name
+      emit "Let's describe the general attributes and behavior of any #{node.name.name}."
+      visit node.body
+      emit "\nAnd with this we're done describing a #{node.name.name}."
+      @in_class = nil
+    end
+
+    def module(node, in_sentence=false)
+      @in_class = node.name.name
+      emit "Let's describe a collection of behavior that we'll call #{node.name.name}."
+      visit node.body
+      emit "\nAnd with this we're done describing #{node.name.name}."
+      @in_class = nil
+    end
+
+    def empty_body(*)
+      # do nothing
+    end
+
+    def class_scope(node, in_sentence=false)
+      visit node.body
+    end
+    alias module_scope class_scope
+
+    def local_variable_assignment(node, in_sentence=false)
+      emit in_sentence ? "w" : "W"
+      emit "e define as `#{node.name}` "
+      visit(node.value)
+    end
+
+    def local_variable_access(node, in_sentence=false)
+      emit "what we previously defined as `#{node.name}`"
+    end
+
+    def instance_variable_assignment(node, in_sentence=false)
+      emit in_sentence ? "i" : "I"
+      emit "ts #{node.name[1..-1]} will be "
+      visit(node.value)
+    end
+
+    def instance_variable_access(node, in_sentence=false)
+      emit "its #{node.name[1..-1]}"
+    end
+
+    def fixnum_literal(node, in_sentence=false)
+      emit "the number #{node.value}"
+    end
+
+    def float_literal(node, in_sentence=false)
+      emit "the number #{node.value}"
+    end
+
+    def string_literal(node, in_sentence=false)
+      emit "the word \"#{node.string}\""
+    end
+
+    def symbol_literal(node, in_sentence=false)
+      emit "the name `#{node.value}`"
+    end
+
+    def true_literal(node, in_sentence=false)
+      emit "the truth"
+    end
+
+    def false_literal(node, in_sentence=false)
+      emit "the falsehood"
+    end
+
+    def nil_literal(node, in_sentence=false)
+      emit "the nothingness"
+    end
+
+    def empty_array(node, in_sentence=false)
+      emit "an empty list"
+    end
+
+    def array_literal(node, in_sentence=false)
+      body = node.body
+      emit "a list of "
+      body.each_with_index do |node, index|
+        visit node
+        if body.length == index + 2 # last element
+          emit " and "
+        elsif body.length != index + 1
+          emit ", "
+        end
+      end
+    end
+
+    def hash_literal(node, in_sentence=false)
+      return emit "an empty dictionary" if node.array.empty?
+
+      body = node.array.each_slice(2)
+
+      emit 'a dictionary where '
+      body.each_with_index do |slice, index|
+        key, value = slice
+
+        visit key
+        emit " relates to "
+        visit value
+
+        if body.to_a.length == index + 2 # last element
+          emit " and "
+        elsif body.to_a.length != index + 1
+          emit ", "
+        end
+      end
+    end
+
+    # def range(node, in_sentence=false)
+    # end
+
+    # def range_exclude(node, in_sentence=false)
+    # end
+
+    # def regex_literal(node, in_sentence=false)
+    # end
+
+    def send(node, in_sentence=false)
+      if node.receiver.is_a?(Rubinius::AST::Self)
+        emit in_sentence ? "the result of calling " : "We "
+        emit "**#{node.name}**"
+      else
+        emit in_sentence ? "the result of calling " : "We call "
+        emit "**#{node.name}** on "
+        visit node.receiver
+      end
+    end
+
+    def send_with_arguments(node, in_sentence=false)
+      return if process_binary_operator(node, in_sentence) # 1 * 2, a / 3, true && false
+
+      if node.receiver.is_a?(Rubinius::AST::Self)
+        emit in_sentence ? "the result of calling " : "We "
+        emit "**#{node.name}**"
+      else
+        emit in_sentence ? "the result of calling " : "We call "
+        emit "**#{node.name}** on "
+        visit node.receiver
+      end
+
+      unless node.arguments.array.empty?
+        emit " given "
+        visit(node.arguments)
+      end
+    end
+
+    def actual_arguments(node, in_sentence=false)
+      body = node.array
+      body.each_with_index do |node, index|
+        visit node
+        if body.length == index + 2 # last element
+          emit " and "
+        elsif body.length != index + 1
+          emit ", "
+        end
+      end
+    end
+
+    # def iter_arguments(node, in_sentence=false)
+    # end
+
+    # def iter(node, in_sentence=false)
+    # end
+
+    def block(node, in_sentence=false)
+      body = node.array
+      body.each_with_index do |node, index|
+        if body.length == index + 1 # last element
+          if @in_method
+          emit "Finally we return "
+          end
+          visit node, true
+          emit "."
+        else
+          visit node, in_sentence
+          emit '. '
+        end
+      end
+    end
+
+    # def not(node, in_sentence=false)
+    # end
+
+    # def and(node, in_sentence=false)
+    # end
+
+    # def or(node, in_sentence=false)
+    # end
+
+    # def op_assign_and(node, in_sentence=false)
+    # end
+
+    # def op_assign_or(node, in_sentence=false)
+    # end
+
+    # def toplevel_constant(node, in_sentence=false)
+    # end
+
+    # def constant_access(node, in_sentence=false)
+    # end
+
+    # def scoped_constant(node, in_sentence=false)
+    # end
+
+    def if(node, in_sentence=false)
+      body, else_body = node.body, node.else
+      keyword = 'if'
+
+      if node.body.is_a?(Rubinius::AST::NilLiteral) && !node.else.is_a?(Rubinius::AST::NilLiteral)
+
+        body, else_body = else_body, body
+        keyword = 'unless'
+      end
+
+      emit "#{keyword} "
+      visit node.condition, true
+      emit " is truthy, then "
+
+      visit body, true
+
+      if else_body.is_a?(Rubinius::AST::NilLiteral)
+        return
+      end
+
+      emit " -- else, "
+
+      visit else_body, true
+    end
+
+    def while(node, in_sentence=false)
+      emit in_sentence ? "w" : "W"
+      emit 'hile '
+      visit node.condition, true
+      emit ", "
+      visit node.body, true
+    end
+
+    def until(node, in_sentence=false)
+      emit in_sentence ? "u" : "U"
+      emit 'ntil '
+      visit node.condition, true
+      emit ", "
+      visit node.body, true
+    end
+
+    def return(node, in_sentence=false)
+      emit in_sentence ? "w" : "W"
+      emit "e return "
+      visit node.value
+    end
+
+    def define(node, in_sentence=false)
+      args = enumerate(node.arguments.names)
+
+      if @in_class
+        emit "\n\nA #{@in_class} can **#{node.name}**"
+      else
+        emit "\n\nLet's define a method: **#{node.name}**"
+      end
+      if node.arguments.names.empty?
+        emit "."
+      else
+        emit ", given a specific #{args}." 
+      end
+
+      unless node.body.array.first.is_a?(Rubinius::AST::NilLiteral) && node.body.array.length == 1
+        @in_method = true
+        emit " This is described as follows: "
+        visit node.body, true
+        @in_method = false
+      end
+    end
+
+    def method_missing(m, *args, &block)
+      emit "(eerr I don't know how to explain `#{m}`)"
+    end
+
+    private
+
+    def enumerate(ary)
+      comma_joinable = ary[0..-2]
+      if comma_joinable.empty?
+        "#{ary[-1]}"
+      else
+        [comma_joined.join(', '), ary[-1]].join(' and ')
+      end
+    end
+
+    def process_binary_operator(node, in_sentence)
+      operators = %w(+ - * / & | << < > >= <= == !=).map(&:to_sym)
+      return false unless operators.include?(node.name)
+      return false if node.arguments.array.length != 1
+
+      operand = node.arguments.array[0]
+
+      unless node.receiver.is_a?(Rubinius::AST::Self)
+        visit node.receiver
+      end
+
+      emit case node.name.to_s
+           when "+" then " plus "
+           when "-" then " minus "
+           when "*" then " times "
+           when "/" then " divided by "
+           when "<" then " is less than "
+           when ">" then " is greater than "
+           when ">=" then " is greater or equal than "
+           when "<=" then " is less or equal than "
+           when "==" then " is equal to "
+           when "!=" then " is different than "
+           end
+
+      visit operand, true
+    end
+  end
+end

data/test/explain/visitor_test.rb

@@ -0,0 +1,90 @@
+require 'test_helper'
+require 'explain/visitor'
+
+module Explain
+  describe Visitor do
+    let(:code) { "a = 123".to_ast }
+    let(:visitor) { Visitor.new }
+
+    def self.compiles(code, expected)
+      it "explains #{code}" do
+        visitor.visit(code.to_ast)
+        visitor.output.must_equal(expected)
+      end
+    end
+
+    # Basic types
+    compiles %q{123},
+      %q{the number 123}
+    compiles %q{12.3},
+      %q{the number 12.3}
+    compiles %q{:hey},
+      %q{the name `hey`}
+    compiles %q{"hey"},
+      %q{the word "hey"}
+
+    compiles %q{true},
+      %q{the truth}
+    compiles %q{false},
+      %q{the falsehood}
+    compiles %q{nil},
+      %q{the nothingness}
+
+    compiles %q{[]},
+      %q{an empty list}
+    compiles %q{["hey", 9.9, 123]},
+      %q{a list of the word "hey", the number 9.9 and the number 123}
+    compiles %q{{}},
+      %q{an empty dictionary}
+    compiles %q{{:foo => "bar", :baz => 123}},
+      %q{a dictionary where the name `foo` relates to the word "bar" and the name `baz` relates to the number 123}
+
+    # Assignments
+    compiles %q{a = 123},
+      %q{We define as `a` the number 123}
+    compiles %q{name = "John"},
+      %q{We define as `name` the word "John"}
+
+    compiles %q{def ret_name; name = "John"; name; end},
+      %Q{\n\nLet's define a method: **ret_name**. This is described as follows: we define as `name` the word "John". Finally we return what we previously defined as `name`.}
+    compiles %q{@name},
+      %q{its name}
+    compiles %q{@name = "John"},
+      %q{Its name will be the word "John"}
+
+    # Classes and modules
+    compiles %q{class Person; end},
+      %Q{Let's describe the general attributes and behavior of any Person.\nAnd with this we're done describing a Person.}
+
+    compiles %q{class Person
+                  def walk(distance)
+                    @position += distance
+                    update_hunger 1
+                  end
+                end},
+      %Q{Let's describe the general attributes and behavior of any Person.\n\nA Person can **walk**, given a specific distance. This is described as follows: its position will be its position plus what we previously defined as `distance`. Finally we return the result of calling **update_hunger** given the number 1..\nAnd with this we're done describing a Person.}
+
+    # Control flow
+    compiles %q{if true
+                  false
+                else
+                  :foo
+                end},
+      %Q{if the truth is truthy, then the falsehood -- else, the name `foo`}
+
+    compiles %q{number = 0
+                while number < 3
+                  number += 1
+                end},
+      %Q{We define as `number` the number 0. while what we previously defined as `number` is less than the number 3, we define as `number` what we previously defined as `number` plus the number 1.}
+
+    compiles %q{number = 0
+                until number == 3
+                  number += 1
+                end},
+      %Q{We define as `number` the number 0. until what we previously defined as `number` is equal to the number 3, we define as `number` what we previously defined as `number` plus the number 1.}
+
+    compiles %q{return 3},
+      %Q{We return the number 3}
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,2 @@
+require 'minitest/spec'
+require 'minitest/autorun'

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: explain
+version: !ruby/object:Gem::Version
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors:
+- Josep M. Bach
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-07 00:00:00.000000000 Z
+dependencies: []
+description: Explain explains your Ruby code in natural language.
+email:
+- josep.m.bach@gmail.com
+executables:
+- explain
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rvmrc
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/explain
+- examples/person.rb
+- explain.gemspec
+- lib/explain.rb
+- lib/explain/version.rb
+- lib/explain/visitor.rb
+- test/explain/visitor_test.rb
+- test/test_helper.rb
+homepage: https://github.com/txus/explain
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Explain explains your Ruby code in natural language.
+test_files:
+- test/explain/visitor_test.rb
+- test/test_helper.rb