hack_tree 0.1.0 → 0.1.1

data/.gitignore

@@ -1,10 +1,12 @@
 # General Ruby.
+/.bundle
 .ref-*
 .old*
 *-old*
+/.rvmrc
 
 # Project-specific.
 /*.rb
 /doc/
 /pkg/
-/.rvmrc
+/.yardoc

data/Gemfile.lock

@@ -0,0 +1,26 @@
+PATH
+  remote: .
+  specs:
+    hack_tree (0.1.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+    yard (0.7.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  hack_tree!
+  rspec
+  yard

data/README.md

@@ -2,13 +2,17 @@
 Organize and share your console hacks
 =====================================
 
-WARNING! THIS IS WORK IN PROGRESS, NOTHING IS GUARANDEED TO WORK AT ALL
------------------------------------------------------------------------
-
 Introduction
 ------------
 
-HackTree lets you organize and share your console hacks in an effective and uniform way. Blah-blah-blah.
+HackTree lets you organize and share your console hacks in a simple and efficient way.
+
+Console hacks (or tricks) are handy methods you use in IRB console to do repetitive tasks. HackTree gives you the following opportunities:
+
+* Create hacks using a **simple and uniform DSL**.
+* **Describe** your hacks, much like you describe tasks in Rakefiles.
+* **List available** hacks with descriptions right in your console.
+* **Share** hacks with your teammates, **reuse** them in different projects.
 
 
 Setup (Rails 3)
@@ -17,9 +21,8 @@ Setup (Rails 3)
 Add to your `Gemfile`:
 
 ~~~
-group :development do
-  gem "hack_tree"
-end
+gem "hack_tree"
+#gem "hack_tree", :git => "git://github.com/dadooda/hack_tree.git"    # Edge version.
 ~~~
 
 Install the gem:
@@ -28,6 +31,12 @@ Install the gem:
 $ bundle install
 ~~~
 
+Generate essentials:
+
+~~~
+$ rails generate hack_tree
+~~~
+
 
 Usage
 -----
@@ -50,14 +59,275 @@ Request help on a hack:
 >> c.hello?
 ~~~
 
-Use the hack:
+Use a hack:
 
 ~~~
 >> c.hello
+Hello, world!
+
+>> c.hello "Ruby"
+Hello, Ruby!
+~~~
+
+Create a hack (create and edit `lib/hacks/ping.rb`):
+
+~~~
+HackTree.define do
+  desc "Play ping-pong"
+  hack :ping do
+    puts "Pong!"
+  end
+end
+~~~
+
+Reload hacks:
+
+~~~
+>> c.hack_tree.reload
+~~~
+
+Use your hack:
+
+~~~
+>> c.ping
+Pong!
+~~~
+
+That's it for the basics, read further for more detailed information.
+
+
+Definition language
+-------------------
+
+### Overview ###
+
+The definition language has just 3 statements: `desc`, `group` and `hack`.
+
+To enter the definition language use the wrapper block:
+
+~~~
+HackTree.define do
+  ...
+end
+~~~
+
+> NOTE: Inside the wrapper `self` is the object of type `HackTree::Instance`.
+
+### Defining hacks ###
+
+To define a hack, use `hack`. To describe it, use `desc`.
+
+~~~
+HackTree.define do
+  desc "Say hello to the world"
+  hack :hello do
+    puts "Hello, world!"
+  end
+end
+~~~
+
+### Handling hack arguments ###
+
+Hack arguments are block arguments in regular Ruby syntax.
+
+~~~
+HackTree.define do
+  desc "Say hello to the world or to a specific person"
+  hack :hello do |*args|
+    puts "Hello, %s!" % (args[0] || "world")
+  end
+~~~
+
+In Ruby 1.9 this form will also work:
+
+~~~
+HackTree.define do
+  desc "Say hello to the world or to a specific person"
+  hack :hello do |who = "world"|
+    puts "Hello, #{who}!"
+  end
+end
+~~~
+
+### Using full descriptions ###
+
+Once your hack begins to take arguments it is recommended that you extend `desc` to a full block of text. Keep the heading line, **add a few examples** and possibly some other descriptive information.
+
+~~~
+HackTree.define do
+  desc <<-EOT
+    Say hello to the world or to a specific person
+
+    Examples:
+
+      >> c.hello
+      Hello, world!
+
+      >> c.hello "Ruby"
+      Hello, Ruby!
+  EOT
+  hack :hello do |*args|
+    puts "Hello, %s!" % (args[0] || "world")
+  end
+end
+~~~
+
+See it in console:
+
+~~~
+>> c
+hello            # Say hello to the world or to a specific person
+
+>> c.hello?
+Say hello to the world or to a specific person
+
+Examples:
+
+  >> c.hello
+  Hello, world!
+
+  >> c.hello "Ruby"
+  Hello, Ruby!
+~~~
+
+### Defining groups ###
+
+Groups act as namespaces and are used to encapsulate hacks and other groups. You can nest groups to any level.
+
+~~~
+HackTree.define do
+  desc "DB management"
+  group :db do
+    desc "List tables in native format"
+    hack :tables do
+      ...
+    end
+
+    desc "Get `ActiveRecord::Base.connection`"
+    hack :conn do
+      ...
+    end
+  end
+end
+~~~
+
+See it in console:
+
+~~~
+>> c
+db/              # DB management
+...
+
+>> c.db
+conn             # Get `ActiveRecord::Base.connection`
+tables           # List tables in native format
+~~~
+
+### Exiting from hacks, returning values ###
+
+If the hack runs uninterrupted, it returns the result of its last statement.
+
+~~~
+>> HackTree.define do
+  hack :five do
+    5
+  end
+end
+
+>> c.five
+=> 5
+~~~
+
+To exit from a hack, use `next`. Unfortunately, **you cannot** use `break` or `return`, please keep that in mind.
+
+~~~
+HackTree.define do
+  hack :hello do |*args|
+    who = args[0] || "world"
+
+    if who == "Java"
+      puts "Goodbye, Java!"
+      next false
+    end
+
+    puts "Hello, #{who}!"
+
+    true
+  end
+end
+~~~
+
+In the above example, the hack should return `false` if the argument is "Java".
+
+See it in console:
+
+~~~
 >> c.hello "Ruby"
+Hello, Ruby!
+=> true
+
+>> c.hello "Java"
+Goodbye, Java!
+=> false
+~~~
+
+### Handling external dependencies ###
+
+In real life it's possible that your hack depends on particular gems, environment settings, etc.
+
+Please follow these recommendations when dealing with dependencies:
+
+* Make sure your hack can be loaded regardless of dependencies. In other words, use dependencies **inside** the hack, not outside of it.
+* Use `begin ... rescue` to catch possible unmet dependencies. Upon an unmet dependency report about it and return a noticeable result, e.g. `false`.
+
+Example:
+
+~~~
+HackTree.define do
+  group :db do
+    desc "Get `ActiveRecord::Base.connection`"
+    hack :conn do
+      begin
+        ActiveRecord::Base.connection
+      rescue
+        puts "Error: ActiveRecord not found"
+        false
+      end
+    end
+  end
+end
 ~~~
 
-Place your application's hacks in `lib/hacks/`.
+### Defining classes and methods to be used in hacks ###
+
+If your hack needs to use a custom method or class, it is recommended that you use a hierarchy of Ruby module namespaces matching your hack's name.
+
+Example (`lib/hacks/db/tables.rb`):
+
+~~~
+HackTree.define do
+  group :db do
+    desc "List tables in native format"
+    hack :tables do
+      tables = Hacks::DB::Tables.get_tables
+      tables.each do |table|
+        puts table
+      end
+    end
+  end
+end
+
+module Hacks
+  module DB
+    module Tables
+      def self.get_tables
+        # Some logic here.
+        ["authors", "books"]
+      end
+    end
+  end
+end
+~~~
 
 
 Copyright

data/hack_tree.gemspec

@@ -1,22 +1,23 @@
-$: << File.join(File.dirname(__FILE__), "lib")
-require "hack_tree"
+require File.expand_path("../lib/hack_tree/version", __FILE__)
 
 Gem::Specification.new do |s|
-  s.name        = "hack_tree"
-  s.version     = HackTree::VERSION
-  s.authors     = ["Alex Fortuna"]
-  s.email       = ["alex.r@askit.org"]
-  s.homepage    = "http://github.com/dadooda/hack_tree"
+  s.name = "hack_tree"
+  s.version = HackTree::VERSION
+  s.authors = ["Alex Fortuna"]
+  s.email = ["alex.r@askit.org"]
+  s.homepage = "http://github.com/dadooda/hack_tree"
 
   # Copy these from class's description, adjust markup.
-  s.summary     = %q{Organize and share your console hacks}
+  s.summary = %q{Organize and share your console hacks}
+  # TODO: Proper text.
   s.description = %q{HackTree lets you organize and share your console hacks in an effective and uniform way. Blah-blah-blah.}
   # end of s.description=
 
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables = `git ls-files -- bin/*`.split("\n").map {|f| File.basename(f)}
   s.require_paths = ["lib"]
 
   s.add_development_dependency "rspec"
+  s.add_development_dependency "yard"
 end

data/lib/generators/hack_tree/hack_tree_generator.rb

@@ -1,5 +1,5 @@
 class HackTreeGenerator < Rails::Generators::Base   #:nodoc:
-  source_root File.join(File.dirname(__FILE__), "templates")
+  source_root File.expand_path("../templates", __FILE__)
 
   def go
     copy_file (bn = "hack_tree.rb"), "config/initializers/#{bn}"

data/lib/hack_tree/action_context.rb

@@ -42,7 +42,10 @@ module HackTree
     end
 
     def inspect
-      # NOTE: Exceptions raised here result in `(Object doesn't support #inspect)`. No other details are available, be careful.
+      # NOTES:
+      #
+      # * Exceptions raised here result in `(Object doesn't support #inspect)`. No other details are available, be careful.
+      # * We don't return value from here, we **print** it directly.
 
       nodes = @instance.nodes.select {|node| node.parent == @parent}
 
@@ -103,7 +106,13 @@ module HackTree
             (["", node.full_desc] if node.full_desc),
           ].flatten(1).compact
 
+          # `out` are lines of text, eventually.
           ::Kernel.puts out.empty?? "No description, please provide one" : out
+
+          # For groups list contents after description.
+          #if node.is_a? Node::Group
+          #  ::Kernel.puts ["", self.class.new(@instance, node).inspect]
+          #end
         else
           # Group/hack request.
           case node

data/lib/hack_tree/instance.rb

@@ -12,21 +12,17 @@ module HackTree
       attrs.each {|k, v| send("#{k}=", v)}
     end
 
-    # Get action object.
+    # Create action object.
     #
     #   >> r.action
     #   hello       # Say hello
+    #
     #   >> r.action.hello
     #   Hello, world!
     def action
       ActionContext.new(self)
     end
 
-    # Create action object. See HackTree::action for examples.
-    def action
-      ActionContext.new(self)
-    end
-
     # List direct children of <tt>node</tt>. Return Array, possibly an empty one.
     #
     #   children_of(nil)    # => [...], children of root.

data/lib/hack_tree/node/group.rb

@@ -1,4 +1,4 @@
-require File.join(File.dirname(__FILE__), "base")
+require File.expand_path("../base", __FILE__)
 
 module HackTree
   module Node

data/lib/hack_tree/node/hack.rb

@@ -1,4 +1,4 @@
-require File.join(File.dirname(__FILE__), "base")
+require File.expand_path("../base", __FILE__)
 
 module HackTree
   module Node

data/lib/hack_tree/parser/desc.rb

@@ -1,4 +1,4 @@
-require File.join(File.dirname(__FILE__), "base")
+require File.expand_path("../base", __FILE__)
 
 module HackTree
   module Parser

data/lib/hack_tree/version.rb

@@ -0,0 +1,4 @@
+module HackTree
+  # Gem version.
+  VERSION = "0.1.1"
+end

data/lib/hack_tree.rb

@@ -1,14 +1,14 @@
+
+# Load all stuff.
 [
   "hack_tree/**/*.rb",
 ].each do |fmask|
-  Dir[File.join(File.dirname(__FILE__), fmask)].each do |fn|
+  Dir[File.expand_path("../#{fmask}", __FILE__)].each do |fn|
     require fn
   end
 end
 
 module HackTree
-  VERSION = "0.1.0"
-
   # Standard hacks bundled with the gem, their global names.
   STD_HACKS = [
     "hack_tree.reload",
@@ -57,22 +57,20 @@ module HackTree
   # Enable HackTree globally.
   #
   #   >> HackTree.enable
-  #   Greetings.
+  #   Console hacks are available. Use `c`, `c.hack?`, `c.hack [args]`
+  #
   #   >> c
   #   hello         # Say hello
+  #
   #   >> c.hello
   #   Hello, world!
   #
   # Options:
   #
-  #   :completion => T|F      # Enable completion enhancement. Default is true.
+  #   :completion => T|F      # Enable completion enhancement. Default is `true`.
   #   :with_std => [...]      # Load only these standard hacks.
   #   :without_std => [...]   # Load all but these standard hacks.
-  #   :quiet => T|F           # Be quiet. Default is false.
-  #
-  # Examples:
-  #
-  # TODO.
+  #   :quiet => T|F           # Be quiet. Default is `false`.
   def self.enable(method_name = :c, options = {})
     options = options.dup
     o = {}
@@ -142,8 +140,8 @@ module HackTree
 
     global_names.each do |global_name|
       bn = global_name.gsub(".", "/") + ".rb"
-      fn = File.join(File.dirname(__FILE__), "../hacks", bn)
-      load fn
+      fn = File.expand_path("../hacks/#{bn}", __FILE__)
+      require fn
     end
 
     nil
@@ -157,77 +155,3 @@ module HackTree
     @instance ||= Instance.new
   end
 end
-
-#--------------------------------------- Junk
-
-if false
-      # * Using array is a reliable way to ensure a newline after the banner.
-      ::Kernel.puts [
-        #"",
-        "Console hacks are available. Use `%s`, `%s.hack?`, `%s.hack [args]`" % ([@enabled_as]*3),
-        #"",
-      ]
-end
-
-if false
-  # Node (group/hack) regexp without delimiters.
-  NAME_REGEXP = /[a-zA-Z_]\w*/
-
-  # Node names which can't be used due to serious reasons.
-  FORBIDDEN_NAMES = [
-    :inspect,
-    :method_missing,
-    :to_s,
-  ]
-end
-
-if false
-  # Create the action object.
-  #
-  #   module Kernel
-  #     # Access our hacks via <tt>c</tt>.
-  #     def c
-  #       ::HackTree.action
-  #     end
-  #   end
-  #
-  #   >> c
-  #   hello       # Say hello
-  #   >> c.hello
-  #   Hello, world!
-  #
-  # See also ::enable.
-  def self.action
-    ActionContext.new(@nodes)
-  end
-
-  # Clear self.
-  def self.clear
-    # Request re-initialization upon first use of any kind.
-    @is_initialized = false
-  end
-
-  # Access nodes (groups/hacks) created via the DSL.
-  def self.nodes
-    @nodes
-  end
-
-  # See #nodes.
-  def self.nodes=(ar)
-    @nodes = ar
-  end
-
-  # NOTE: We need this wrapper to create private singletons.
-  class << self
-    private
-
-    # On-the-fly initializer.
-    def _otf_init
-      return if @is_initialized
-
-      @is_initialized = true
-      @nodes = []
-      @dsl_root = DslContext.new(@nodes)
-    end
-  end # class << self
-end

data/{hacks → lib/hacks}/hack_tree/reload.rb

@@ -1,5 +1,4 @@
 HackTree.define do
-  desc "HackTree management hacks"
   group :hack_tree do
     desc <<-EOT
       Reload application hacks

data/lib/hacks/hack_tree.rb

@@ -0,0 +1,5 @@
+HackTree.define do
+  desc "HackTree management"
+  group :hack_tree do
+  end
+end

data/{hacks → lib/hacks}/ls.rb

@@ -41,8 +41,9 @@ HackTree.define do
           r.global_name =~ re,
           r.brief_desc && r.brief_desc =~ re,
 
-          # TODO: Include full as an option, later.
-          #r.full_desc && r.full_desc =~ re,    # Better without full_desc, or examples may match.
+          # Might some time include search in `full_desc` as an option.
+          # Must not be enabled by default since it returns too many results.
+          #r.full_desc && r.full_desc =~ re,
         ].any?
       end
     end
@@ -50,7 +51,7 @@ HackTree.define do
     nodes = nodes.sort_by do |node|
       [
         node.is_a?(::HackTree::Node::Group) ? 0 : 1,    # Groups first.
-        node.name.to_s,
+        node.global_name,
       ]
     end
 

data/spec/{lib/hack_tree/parser → parser}/desc_spec.rb

@@ -1,4 +1,4 @@
-require File.join(File.dirname(__FILE__), "spec_helper")
+require File.expand_path("../spec_helper", __FILE__)
 
 describe HackTree::Parser::Desc do
   before :each do

data/spec/parser/spec_helper.rb

@@ -0,0 +1,3 @@
+require File.expand_path("../../spec_helper", __FILE__)
+
+# Custom stuff for this group.

data/spec/spec_helper.rb

@@ -1,16 +1,33 @@
-require "pathname"
+# NOTE: I usually support `STANDALONE` mode in specs for Rails projects' components
+#       to be able to test them without loading the environment. This project does not
+#       depend on Rails *BUT* I still want a consistent RSpec file structure.
+#       If this is confusing, feel free to propose something better. :)
 
-# Load stuff.
-[
-  "lib/**/*.rb",
-].each do |fmask|
-  Dir["./#{fmask}"].each do |fn|
-    ##puts "-- req '#{fn}'"
-    require fn
+# No Rails, we're always standalone... and free! :)
+STANDALONE = 1
+
+if STANDALONE
+  # Provide root path object.
+  module Standalone
+    eval <<-EOT
+      def self.root
+        # This is an absolute path, it's perfectly safe to do a `+` and then `require`.
+        Pathname("#{File.expand_path('../..', __FILE__)}")
+      end
+    EOT
+  end
+
+  # Load stuff.
+  [
+    "lib/hack_tree/**/*.rb",
+  ].each do |fmask|
+    Dir[Standalone.root + fmask].each do |fn|
+      require fn
+    end
   end
 end
 
-# TODO: When this becomes a gem, use gem instead of direct copy.
+# When this becomes a gem, use gem instead of direct copy.
 module RSpec
   module PrintOnFailure
     module Helpers

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hack_tree
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-04 00:00:00.000000000Z
+date: 2012-03-09 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &71051990 !ruby/object:Gem::Requirement
+  requirement: &75379870 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,18 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *71051990
+  version_requirements: *75379870
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &75361840 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *75361840
 description: HackTree lets you organize and share your console hacks in an effective
   and uniform way. Blah-blah-blah.
 email:
@@ -33,12 +44,11 @@ files:
 - .gitignore
 - .rspec
 - Gemfile
+- Gemfile.lock
 - MIT-LICENSE
 - README.md
 - Rakefile
 - hack_tree.gemspec
-- hacks/hack_tree/reload.rb
-- hacks/ls.rb
 - lib/generators/hack_tree/USAGE
 - lib/generators/hack_tree/hack_tree_generator.rb
 - lib/generators/hack_tree/templates/INSTALL
@@ -56,16 +66,18 @@ files:
 - lib/hack_tree/parser/base.rb
 - lib/hack_tree/parser/desc.rb
 - lib/hack_tree/tools.rb
-- spec/lib/hack_tree/parser/desc_spec.rb
-- spec/lib/hack_tree/parser/desc_spec/000,brief.txt
-- spec/lib/hack_tree/parser/desc_spec/000,full.txt
-- spec/lib/hack_tree/parser/desc_spec/000.txt
-- spec/lib/hack_tree/parser/desc_spec/010,brief.txt
-- spec/lib/hack_tree/parser/desc_spec/010,full.txt
-- spec/lib/hack_tree/parser/desc_spec/010.txt
-- spec/lib/hack_tree/parser/spec_helper.rb
-- spec/lib/hack_tree/spec_helper.rb
-- spec/lib/spec_helper.rb
+- lib/hack_tree/version.rb
+- lib/hacks/hack_tree.rb
+- lib/hacks/hack_tree/reload.rb
+- lib/hacks/ls.rb
+- spec/parser/desc_spec.rb
+- spec/parser/desc_spec/000,brief.txt
+- spec/parser/desc_spec/000,full.txt
+- spec/parser/desc_spec/000.txt
+- spec/parser/desc_spec/010,brief.txt
+- spec/parser/desc_spec/010,full.txt
+- spec/parser/desc_spec/010.txt
+- spec/parser/spec_helper.rb
 - spec/spec_helper.rb
 homepage: http://github.com/dadooda/hack_tree
 licenses: []
@@ -92,3 +104,4 @@ signing_key:
 specification_version: 3
 summary: Organize and share your console hacks
 test_files: []
+has_rdoc: 

data/spec/lib/hack_tree/parser/spec_helper.rb

@@ -1,3 +0,0 @@
-require File.join(File.dirname(__FILE__), "../spec_helper")
-
-# Custom stuff for this group.

data/spec/lib/hack_tree/spec_helper.rb

@@ -1,3 +0,0 @@
-require File.join(File.dirname(__FILE__), "../spec_helper")
-
-# Custom stuff for this group.

data/spec/lib/spec_helper.rb

@@ -1,3 +0,0 @@
-require File.join(File.dirname(__FILE__), "../spec_helper")
-
-# Custom stuff for this group.