hack_tree 0.1.0

data/.gitignore

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

data/.rspec

@@ -0,0 +1,2 @@
+--color
+-fn         # Tree-like progress.

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem dependencies in `PROJECT.gemspec`.
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011-2012 Alex Fortuna
+
+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,74 @@
+
+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.
+
+
+Setup (Rails 3)
+---------------
+
+Add to your `Gemfile`:
+
+~~~
+group :development do
+  gem "hack_tree"
+end
+~~~
+
+Install the gem:
+
+~~~
+$ bundle install
+~~~
+
+
+Usage
+-----
+
+Start console:
+
+~~~
+$ rails console
+~~~
+
+List available hacks:
+
+~~~
+>> c
+~~~
+
+Request help on a hack:
+
+~~~
+>> c.hello?
+~~~
+
+Use the hack:
+
+~~~
+>> c.hello
+>> c.hello "Ruby"
+~~~
+
+Place your application's hacks in `lib/hacks/`.
+
+
+Copyright
+---------
+
+Copyright © 2012 Alex Fortuna.
+
+Licensed under the MIT License.
+
+
+Feedback
+--------
+
+Send bug reports, suggestions and criticisms through [project's page on GitHub](http://github.com/dadooda/hack_tree).

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/hack_tree.gemspec

@@ -0,0 +1,22 @@
+$: << File.join(File.dirname(__FILE__), "lib")
+require "hack_tree"
+
+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"
+
+  # Copy these from class's description, adjust markup.
+  s.summary     = %q{Organize and share your console hacks}
+  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.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec"
+end

data/hacks/hack_tree/reload.rb

@@ -0,0 +1,18 @@
+HackTree.define do
+  desc "HackTree management hacks"
+  group :hack_tree do
+    desc <<-EOT
+      Reload application hacks
+
+      Load every file under `lib/hacks/`.
+    EOT
+    hack :reload do
+      Dir["lib/hacks/**/*.rb"].each do |fn|
+        load fn
+      end
+
+      # Signal something more positive than nil.
+      true
+    end
+  end
+end

data/hacks/ls.rb

@@ -0,0 +1,74 @@
+HackTree.define do
+  desc <<-EOT
+    List groups/hacks globally
+    
+    Examples:
+
+      >> c.ls /^ls$/
+      ls               # List groups/hacks globally
+
+      >> c.ls /he/
+      hello            # Say hello to the world or to a specific person
+
+      >> c.ls /person/
+      hello            # Say hello to the world or to a specific person
+
+      >> c.ls "dsl"
+      dsl/             # Get domain-specific language contexts
+      dsl.gemfile      # Get Bundler `Gemfile` context
+      dsl.rspec        # Get RSpec specfile context
+
+      >> c.ls "dsl.r"
+      dsl.rspec        # Get RSpec specfile context
+  EOT
+  hack :ls do |filter = nil|
+    nodes = @nodes
+
+    # Apply filter.
+    if filter
+      re = case filter
+      when Regexp
+        filter
+      when String
+        Regexp.compile(Regexp.escape(filter))
+      else
+        raise ArgumentError, "Unsupported filter #{filter.inspect}"
+      end
+
+      nodes = nodes.select do |r|
+        [
+          # Logical order.
+          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.
+        ].any?
+      end
+    end
+
+    nodes = nodes.sort_by do |node|
+      [
+        node.is_a?(::HackTree::Node::Group) ? 0 : 1,    # Groups first.
+        node.name.to_s,
+      ]
+    end
+
+    # Compute name alignment width.
+    names = nodes.map {|node| ::HackTree::Tools.format_node_name(node)}
+    name_align = ::HackTree::Tools.compute_name_align(names, @conf.global_name_align)
+
+    nodes.each do |node|
+      brief_desc = node.brief_desc || ::HackTree.conf.brief_desc_stub
+
+      fmt = "%-#{name_align}s%s"
+
+      ::Kernel.puts(fmt % [
+        ::HackTree::Tools.format_node_name(node, node.global_name),
+        brief_desc ? " # #{brief_desc}" : "",
+      ])
+    end # nodes.each
+
+    nil
+  end
+end

data/lib/generators/hack_tree/USAGE

@@ -0,0 +1,7 @@
+Description:
+  Generate HackTree files.
+
+Example:
+  `rails generate hack_tree`
+
+  This will create essential files for HackTree initialization in your project.

data/lib/generators/hack_tree/hack_tree_generator.rb

@@ -0,0 +1,9 @@
+class HackTreeGenerator < Rails::Generators::Base   #:nodoc:
+  source_root File.join(File.dirname(__FILE__), "templates")
+
+  def go
+    copy_file (bn = "hack_tree.rb"), "config/initializers/#{bn}"
+    copy_file (bn = "hello.rb"), "lib/hacks/#{bn}"
+    readme "INSTALL"
+  end
+end

data/lib/generators/hack_tree/templates/INSTALL

@@ -0,0 +1,20 @@
+
+Start console:
+
+    $ rails console
+
+List available hacks:
+
+    >> c
+
+Request help on a hack:
+
+    >> c.hello?
+
+Use the hack:
+
+    >> c.hello
+    >> c.hello "Ruby"
+
+Place your application's hacks in `lib/hacks/`.
+

data/lib/generators/hack_tree/templates/hack_tree.rb

@@ -0,0 +1,4 @@
+if defined? IRB
+  HackTree.enable
+  c.hack_tree.reload
+end

data/lib/generators/hack_tree/templates/hello.rb

@@ -0,0 +1,16 @@
+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

data/lib/hack_tree/action_context.rb

@@ -0,0 +1,125 @@
+module HackTree
+  # Context to execute the actions.
+  class ActionContext
+    # NOTE: No useless methods here, please.
+
+    def initialize(instance, parent = nil)
+      @instance, @parent = instance, parent
+
+      # Suppress warnings.
+      vrb, $VERBOSE = $VERBOSE, nil
+
+      # Insert lookup routine for existing methods.
+      (methods.map(&:to_s) - Node::FORBIDDEN_NAMES.map(&:to_s)).each do |method_name|
+        next if not method_name =~ /\A(#{Node::NAME_REGEXP})\?{,1}\z/
+        node_name = $1.to_sym
+        instance_eval <<-EOT
+          def #{method_name}(*args)
+            if @instance.find_local_node(:#{node_name}, @parent)
+              _dispatch(:#{method_name}, *args)
+            else
+              super
+            end
+          end
+        EOT
+      end
+
+      # Restore warnings.
+      $VERBOSE = vrb
+
+      # Create direct methods. In case your console's completion is sane by itself, it will help.
+      # IRB's default completion isn't sane yet (2012-02-25).
+      @instance.nodes.select do |node|
+        node.parent == @parent
+      end.each do |node|
+        # NOTE: This is slightly different from "existing method lookup routine" used above. Let's keep them separate.
+        instance_eval <<-EOT
+          def #{node.name}(*args)
+            _dispatch(:#{node.name}, *args)
+          end
+        EOT
+      end
+    end
+
+    def inspect
+      # NOTE: Exceptions raised here result in `(Object doesn't support #inspect)`. No other details are available, be careful.
+
+      nodes = @instance.nodes.select {|node| node.parent == @parent}
+
+      # Empty group?
+      if nodes.empty?
+        ::Kernel.puts "No groups/hacks here"
+        return nil
+      end
+
+      # Not empty group, list contents.
+
+      nodes = nodes.sort_by do |node|
+        [
+          node.is_a?(Node::Group) ? 0 : 1,    # Groups first.
+          node.name.to_s,
+        ]
+      end
+
+      # Compute name alignment width.
+      names = nodes.map {|node| Tools.format_node_name(node)}
+      name_align = Tools.compute_name_align(names, @instance.conf.local_name_align)
+
+      nodes.each do |node|
+        brief_desc = node.brief_desc || @instance.conf.brief_desc_stub
+
+        fmt = "%-#{name_align}s%s"
+
+        ::Kernel.puts(fmt % [
+          Tools.format_node_name(node),
+          brief_desc ? " # #{brief_desc}" : "",
+        ])
+      end # nodes.each
+
+      nil
+    end
+
+    def method_missing(method_name, *args)
+      _dispatch(method_name.to_sym, *args)
+    end
+
+    private
+
+    #   _dispatch(:hello)     # Group/hack request.
+    #   _dispatch(:hello?)    # Help request.
+    def _dispatch(request, *args)
+      raise ArgumentError, "Invalid request #{request.inspect}" if not request.to_s =~ /\A(#{Node::NAME_REGEXP})(\?{,1})\z/
+      node_name = $1.to_sym
+      is_question = ($2 != "")
+
+      node = @instance.find_local_node(node_name, @parent)
+
+      # NOTE: Method return result.
+      if node
+        if is_question
+          # Help request.
+          out = [
+            node.brief_desc || @instance.conf.brief_desc_stub,
+            (["", node.full_desc] if node.full_desc),
+          ].flatten(1).compact
+
+          ::Kernel.puts out.empty?? "No description, please provide one" : out
+        else
+          # Group/hack request.
+          case node
+          when Node::Group
+            # Create and return a new nested access context.
+            self.class.new(@instance, node)
+          when Node::Hack
+            # Invoke hack in the context of `HackTree` instance.
+            @instance.instance_exec(*args, &node.block)
+          else
+            raise "Unknown node class #{node.class}, SE"
+          end
+        end # if is_question
+      else
+        ::Kernel.puts "Node not found: '#{node_name}'"
+      end
+    end
+  end # ActionContext
+end

data/lib/hack_tree/config.rb

@@ -0,0 +1,27 @@
+module HackTree
+  # Configuration object.
+  class Config
+    # If set, substitute missing brief descriptions with this text.
+    attr_accessor :brief_desc_stub
+
+    # Aligned width of full names, Range.
+    #
+    #   global_name_align = 16..32
+    attr_accessor :global_name_align
+
+    # Mask to format group names (Kernel::sprintf).
+    attr_accessor :group_format
+
+    # Mask to format hack names (Kernel::sprintf).
+    attr_accessor :hack_format
+
+    # Aligned width of (namespaced) names, Range.
+    #
+    #   local_name_align = 16..32
+    attr_accessor :local_name_align
+
+    def initialize(attrs = {})
+      attrs.each {|k, v| send("#{k}=", v)}
+    end
+  end
+end

data/lib/hack_tree/dsl_context.rb

@@ -0,0 +1,95 @@
+module HackTree
+  # Definition DSL context.
+  class DslContext
+    # NOTE: Please keep methods to an absolute minimum. This is the DSL, I want as little confusion as possible.
+
+    # Initialize self.
+    def initialize(instance, parent = nil)
+      @instance, @parent = instance, parent
+      @desc_parser = Parser::Desc.new
+    end
+
+    def desc(text)
+      @brief_desc, @full_desc = @desc_parser[text]
+    end
+
+    def group(name, &block)
+      raise "Code block expected" if not block
+
+      name = name.to_sym
+
+      # TODO: Check forbidden names.
+
+      # It is allowed to reopen the groups. Find the named group.
+      group = @instance.nodes.find {|r| r.name == name}
+
+      if group
+        if not group.is_a? Node::Group
+          raise "Node '#{name}' already exists and it's not a group"
+        end
+
+        # It is allowed to redefine group description with another description.
+        # If there is no description, the original one is retained on reopen.
+        if @brief_desc
+          group.brief_desc = @brief_desc
+          group.full_desc = @full_desc
+        end
+      else
+        # Create.
+        group = Node::Group.new({
+          :brief_desc => @brief_desc,
+          :full_desc => @full_desc,
+          :name => name,
+          :parent => @parent,
+        })
+
+        @instance.nodes << group
+      end
+
+      # Clear last used descriptions.
+      @brief_desc = @full_desc = nil
+
+      # Create sub-context and dive into it.
+      context = self.class.new(@instance, group)
+      context.instance_eval(&block)
+    end
+
+    def hack(name, &block)
+      raise "Code block expected" if not block
+
+      name = name.to_sym
+
+      # TODO: Check forbidden names.
+
+      # It is allowed to redefine the hacks. Find the named hack.
+      hack = @instance.nodes.find {|r| r.name == name}
+
+      if hack
+        if not hack.is_a? Node::Hack
+          raise "Node '#{name}' already exists and it's not a hack"
+        end
+
+        # Modify hack.
+        hack.brief_desc = @brief_desc
+        hack.full_desc = @full_desc
+        hack.block = block
+      else
+        # Create.
+        hack = Node::Hack.new({
+          :block => block,
+          :brief_desc => @brief_desc,
+          :full_desc => @full_desc,
+          :name => name,
+          :parent => @parent,
+        })
+
+        @instance.nodes << hack
+      end
+
+      # Clear last used descriptions.
+      @brief_desc = @full_desc = nil
+
+      nil
+    end
+  end # DslContext
+end

data/lib/hack_tree/instance.rb

@@ -0,0 +1,153 @@
+module HackTree
+  # Instance of the system.
+  class Instance
+    # Configuration object.
+    attr_accessor :conf
+
+    # Array of Node::Base successors.
+    attr_accessor :nodes
+
+    def initialize(attrs = {})
+      clear
+      attrs.each {|k, v| send("#{k}=", v)}
+    end
+
+    # Get 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.
+    #   children_of(node)   # => [...], children of `node`.
+    def children_of(parent)
+      @nodes.select {|node| node.parent == parent}
+    end
+
+    def clear
+      clear_conf
+      clear_nodes
+    end
+
+    def clear_conf
+      @conf = Config.new({
+        :brief_desc_stub => "(no description)",
+        :global_name_align => 16..32,
+        :group_format => "%s/",
+        :hack_format => "%s",
+        :local_name_align => 16..32,
+      })
+      nil
+    end
+
+    def clear_nodes
+      @nodes = []
+      nil
+    end
+
+    # Perform logic needed to do IRB completion. Returns Array if completion is handled successfully, <tt>nil</tt>
+    # if input is not related to HackTree.
+    #
+    #   completion_logic("c.he", :enabled_as => :c)    # => ["c.hello"]
+    def completion_logic(input, options = {})
+      o = {}
+      options = options.dup
+
+      o[k = :enabled_as] = options.delete(k)
+
+      raise ArgumentError, "Unknown option(s): #{options.inspect}" if not options.empty?
+      raise ArgumentError, "options[:enabled_as] must be given" if not o[:enabled_as]
+
+      # Check if this input is related to us.
+      if not mat = input.match(/\A#{o[:enabled_as]}\.((?:[^.].*)|)\z/)
+        return nil
+      end
+
+      lookup = mat[1]
+
+      # Parse lookup string into node name and prefix.
+      global_name, prefix = if mat = lookup.match(/\A(?:([^.]*)|(.+)\.(.*?))\z/)
+        if mat[1]
+          # "something".
+          ["", mat[1]]
+        else
+          # "something.other", "something.other.other.".
+          [mat[2], mat[3]]
+        end
+      else
+        # Handle no match just in case.
+        ["", ""]
+      end
+
+      base = if global_name == ""
+        # Base is root.
+        nil
+      else
+        # Find a named base node. If not found, return no candidates right away.
+        find_node(global_name) or return []
+      end
+      
+      # Select sub-nodes.
+      candidates = children_of(base).select do |node|
+        # Select those matching `prefix`.
+        node.name.to_s.index(prefix) == 0
+      end.map do |node|
+        # Provide 1+ candidates per item.
+        case node
+        when Node::Group
+          # A neat trick to prevent IRB from appending a " " after group name.
+          [node.name, "#{node.name}."]
+        else
+          [node.name]
+        end.map(&:to_s)
+      end.flatten(1).map do |s|
+        # Convert to final names.
+        [
+          "#{o[:enabled_as]}.",
+          ("#{global_name}." if global_name != ""),
+          s,
+        ].compact.join
+      end
+
+      candidates
+    end
+
+    # Define groups/hacks via the DSL. See HackTree::define for examples.
+    def define(&block)
+      raise "Code block expected" if not block
+      DslContext.new(self).instance_eval(&block)
+      nil
+    end
+
+    # Search for the node by its global name, return <tt>Node::*</tt> or <tt>nil</tt>.
+    #
+    #   find_node("hello")            # => Node::* or nil
+    #   find_node("do.some.stuff")    # => Node::* or nil
+    #
+    # See also: #find_local_node.
+    def find_node(global_name)
+      @nodes.find {|node| node.global_name == global_name}
+    end
+
+    # Search for a local node, return <tt>Node::*</tt> or <tt>nil</tt>.
+    #
+    #   find_node(:hello)                   # Search at root.
+    #   find_node(:hello, :parent => grp)   # Search in `grp` group.
+    #
+    # See also: #find_node.
+    def find_local_node(name, parent)
+      @nodes.find {|r| r.name == name.to_sym and r.parent == parent}
+    end
+  end
+end