irb_hacks 0.2.2 → 0.2.3

data/README.md

@@ -24,7 +24,7 @@ If you see "(snippet)", you're ready to go.
 The Hacks
 ---------
 
-### Code snippets -- `a` and `ae` ###
+### Code Snippets -- `a` and `ae` ###
 
 There's often a need to invoke our work-in-progress code a number of times using the same arguments, wrapping block, etc. For that, "code snippets" feature is quite handy.
 
@@ -97,7 +97,7 @@ Snippets maintain **their own** Readline history. When you press [Up] and [Down]
 You can configure some aspects of the snippets. Read "Configuration" chapter below.
 
 
-### Browse program data with GNU `less` ###
+### Browse Program Data With GNU `less` ###
 
 Sometimes the data your code works with is too long to fit in a console window. The clearest example of this are variables filled with text content, e.g. [Hpricot](http://github.com/whymirror/hpricot) documents/elements.
 
@@ -127,7 +127,7 @@ Now with `STDERR` capture:
 You can configure which pager program to use and with which options. Read "Configuration" chapter below.
 
 
-### Break execution and return instant value ###
+### Break Execution and Return Instant Value ###
 
 By using `IrbHacks.break(value)` you break snippet (`a`) execution and make it return `value`. This is a simple yet powerful debugging technique.
 
@@ -173,9 +173,15 @@ Via `IrbHacks.conf` object you can configure various features of `irb_hacks`. Ad
 * `snippet_prompt` -- Snippet input prompt.
 
 
+Copyright
+---------
+
+Copyright © 2010-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/irb_hacks).
-
-Licensed under the MIT License.

data/Rakefile

@@ -27,10 +27,10 @@ task :rebuild => [:gemspec, :build]
 
 desc "Push (publish) gem to RubyGems.org"
 task :push do
-  # Yet found no way to ask Jeweler forge a complete version string for us.
+  # NOTE: Yet found no way to ask Jeweler forge a complete version string for us.
   vh = YAML.load(File.read("VERSION.yml"))
-  version = [vh[:major], vh[:minor], vh[:patch], (if (v = vh[:build]); v; end)].compact.join(".")
-  pkgfile = File.join("pkg", [GEM_NAME, "-", version, ".gem"].join)
+  version = [vh[:major], vh[:minor], vh[:patch], vh[:build]].compact.join(".")
+  pkgfile = File.join("pkg", "#{GEM_NAME}-#{version}.gem")
   Kernel.system("gem", "push", pkgfile)
 end
 
@@ -42,22 +42,3 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
   #rdoc.options << "--inline-source"
   rdoc.rdoc_files.include("lib/**/*.rb")
 end
-
-#Rake::GemPackageTask.new(spec) do |p|
-#  p.need_tar = true if RUBY_PLATFORM !~ /mswin/
-#end
-
-desc "Compile README preview"
-task :readme do
-  require "kramdown"
-
-  doc = Kramdown::Document.new(File.read "README.md")
-
-  fn = "README.html"
-  puts "Writing '#{fn}'..."
-  File.open(fn, "w") do |f|
-    f.write(File.read "dev/head.html")
-    f.write(doc.to_html)
-  end
-  puts ": ok"
-end

data/VERSION.yml

@@ -1,5 +1,5 @@
 --- 
 :major: 0
 :minor: 2
-:patch: 2
-#:build: pre2
+:patch: 3
+#:build: pre1

data/irb_hacks.gemspec

@@ -5,20 +5,18 @@
 
 Gem::Specification.new do |s|
   s.name = %q{irb_hacks}
-  s.version = "0.2.2"
+  s.version = "0.2.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Alex Fortuna"]
-  s.date = %q{2011-07-12}
+  s.date = %q{2012-02-10}
   s.description = %q{Yet another set of IRB hacks}
   s.email = %q{alex.r@askit.org}
   s.extra_rdoc_files = [
-    "README.html",
     "README.md"
   ]
   s.files = [
     "MIT-LICENSE",
-    "README.html",
     "README.md",
     "Rakefile",
     "VERSION.yml",

data/lib/irb_hacks/snippet.rb

@@ -86,7 +86,8 @@ module IrbHacks
 
       if (code = @history.last)
         begin
-          eval(code, &block)
+          # NOTE: Passing `binding` is important to provide a better backtrace when exception occurs.
+          eval(code, binding, &block)
         rescue IrbHacks::BreakException => e
           # If invoked as documented, `e.message` is always an array.
           e.message[0]

data/lib/irb_hacks.rb

@@ -5,17 +5,17 @@ Dir[File.join(File.dirname(__FILE__), "irb_hacks/**/*.rb")].each {|fn| require f
 # Summary of features brought to IRB:
 #
 # * <tt>a</tt> and <tt>ae</tt> methods to invoke or edit code snippets.
-# * <tt>less</tt> method to interactively dump data with OS pages like <tt>less</tt>.
+# * <tt>less</tt> method to interactively dump data with OS pager program (e.g. <tt>less</tt>).
 # * IrbHacks::break to instantly return value from code into IRB.
 module IrbHacks   #:doc:
-  # Break execution, instantly return value if caller is invoked from a snippet.
+  # Break execution, instantly return a value if caller is invoked from a snippet.
   #
   #   def myfunc
   #     puts "Reading name..."
   #     name = File.read(...)
-  #     IrbHacks.break name     #DEBUG: See what's been read.
+  #     IrbHacks.break name     # Pass what's been read back to console.
   #
-  #     # Other code...
+  #     ...
   #   end
   #
   #   irb> ae
@@ -35,17 +35,3 @@ module IrbHacks   #:doc:
     @conf ||= Config.new
   end
 end
-
-#--------------------------------------- Junk
-
-if false
-  def self.less_cmd   #:nodoc:
-    @less_cmd
-  end
-
-  def self.less_cmd=(cmd)   #:nodoc:
-    @less_cmd = cmd
-  end
-
-  self.less_cmd = "less -R"
-end

metadata

@@ -2,7 +2,7 @@
 name: irb_hacks
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors: 
 - Alex Fortuna
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-12 00:00:00 +04:00
+date: 2012-02-10 00:00:00 +04:00
 default_executable: 
 dependencies: []
 
@@ -21,11 +21,9 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README.html
 - README.md
 files: 
 - MIT-LICENSE
-- README.html
 - README.md
 - Rakefile
 - VERSION.yml

data/README.html

@@ -1,192 +0,0 @@
-<head>
-  <meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
-  <link href="dev/github.css" rel="stylesheet" type="text/css" />
-</head>
-<h1 id="yet-another-set-of-irb-hacks">Yet Another Set of IRB Hacks</h1>
-
-<h2 id="setup">Setup</h2>
-
-<pre><code>$ gem sources --add http://rubygems.org
-$ gem install irb_hacks
-</code></pre>
-
-<p>Add to your <code>~/.irbrc</code>:</p>
-
-<pre><code>require "rubygems"
-require "irb_hacks"
-</code></pre>
-
-<p>Now fire up IRB for a quick test:</p>
-
-<pre><code>$ irb
-irb&gt; ae
-(snippet)&gt;&gt;
-</code></pre>
-
-<p>If you see “(snippet)”, you’re ready to go.</p>
-
-<h2 id="the-hacks">The Hacks</h2>
-
-<h3 id="code-snippets----a-and-ae">Code snippets – <code>a</code> and <code>ae</code></h3>
-
-<p>There’s often a need to invoke our work-in-progress code a number of times using the same arguments, wrapping block, etc. For that, “code snippets” feature is quite handy.</p>
-
-<p><code>irb_hacks</code> provides the two methods with short, meaningless (and thus conflict-free) names – <code>a</code> and <code>ae</code>. <code>a</code> means nothing, it’s just the first letter of the alphabet. <code>a</code> <strong>invokes</strong> the last-edited snippet. <code>ae</code> <strong>lets you edit</strong> the actual snippet (it roughly stands for “a” + “edit”).</p>
-
-<p>A very basic example:</p>
-
-<pre><code>irb&gt; ae
-(snippet)&gt;&gt; puts "Hello, world!"
-irb&gt; a
-Hello, world!
-</code></pre>
-
-<p>Snippet arguments are supported. It’s an array called <code>args</code> in snippet context.</p>
-
-<pre><code>irb&gt; ae
-(snippet)&gt;&gt; p "args", args
-irb&gt; a 10, 1.0, "a string"
-"args"
-[10, 1.0, "a string"]
-</code></pre>
-
-<p>Snippets work just like normal Ruby methods – they return the value of the last statement executed.</p>
-
-<pre><code>irb&gt; ae
-(snippet)&gt;&gt; ["alfa", "zulu", "bravo"] + args
-irb&gt; puts a("charlie").sort
-alfa
-bravo
-charlie
-zulu
-</code></pre>
-
-<p>Snippets support code blocks. It’s a <code>Proc</code> object called <code>block</code> in snippet context. Usage example follows. Suppose you’re building a simplistic <code>/etc/passwd</code> parser. You put the actual reading in the snippet, but do line data manipulation in a block:</p>
-
-<pre><code>irb&gt; ae
-(snippet)&gt;&gt; File.readlines("/etc/passwd").map(&amp;block).each {|s| p s}; nil
-irb&gt; a {|s| ar = s.split(":"); {:name =&gt; ar[0], :uid =&gt; ar[2]}}
-{:uid=&gt;"0", :name=&gt;"root"}
-{:uid=&gt;"1", :name=&gt;"bin"}
-{:uid=&gt;"2", :name=&gt;"daemon"}
-{:uid=&gt;"3", :name=&gt;"adm"}
-...
-</code></pre>
-
-<p>Snippets are <strong>persistent</strong> thoughout IRB invocations. That’s quite handy, since not all stuff can be dynamically reloaded and sometimes we have to restart IRB to ensure a clean reload.</p>
-
-<pre><code>irb&gt; ae
-(snippet)&gt;&gt; puts "Snippets are persistent!"
-irb&gt; exit
-$ irb
-irb&gt; a
-Snippets are persistent!
-</code></pre>
-
-<p>Just in case, snippet history file is called <code>~/.irb_snippet_history</code> by default.</p>
-
-<p>Snippets maintain <strong>their own</strong> Readline history. When you press [Up] and [Down] keys in <code>ae</code>, you browse the previously used snippets, not just your previous IRB input. So don’t retype the snippet you used yesterday – press [Up] a few times and you’ll see it.</p>
-
-<pre><code>irb&gt; ae
-(snippet)&gt;&gt; puts "snippet one"
-irb&gt; hala
-irb&gt; bala
-irb&gt; ae
-(snippet)&gt;&gt; puts "snippet two"
-irb&gt; foo
-irb&gt; moo
-irb&gt; ae
-(snippet)&gt;&gt;
-# Pressing [Up] will give you...
-(snippet)&gt;&gt; puts "snippet two"
-# Pressing [Up] again will give you...
-(snippet)&gt;&gt; puts "snippet one"
-</code></pre>
-
-<p>You can configure some aspects of the snippets. Read “Configuration” chapter below.</p>
-
-<h3 id="browse-program-data-with-gnu-less">Browse program data with GNU <code>less</code></h3>
-
-<p>Sometimes the data your code works with is too long to fit in a console window. The clearest example of this are variables filled with text content, e.g. <a href="http://github.com/whymirror/hpricot">Hpricot</a> documents/elements.</p>
-
-<p>To solve that, the greatest paging program of all times, GNU <code>less</code>, comes to the rescue.</p>
-
-<pre><code>$ irb
-irb&gt; files = Dir["/etc/*"].sort
-# Some bulky array...
-irb&gt; less files
-# ...which you browse interactively!
-</code></pre>
-
-<p>In block form, <code>less</code> hack intercepts everything output to <code>STDOUT</code> (and, optionally, to <code>STDERR</code>), and feeds it to the pager.</p>
-
-<pre><code>$ irb
-irb&gt; less do
-puts "Hello, world"
-end
-</code></pre>
-
-<p>Now with <code>STDERR</code> capture:</p>
-
-<pre><code>$ irb
-irb&gt; less(:stderr) do
-puts "to stdout"
-STDERR.puts "to stderr"
-end
-</code></pre>
-
-<p>You can configure which pager program to use and with which options. Read “Configuration” chapter below.</p>
-
-<h3 id="break-execution-and-return-instant-value">Break execution and return instant value</h3>
-
-<p>By using <code>IrbHacks.break(value)</code> you break snippet (<code>a</code>) execution and make it return <code>value</code>. This is a simple yet powerful debugging technique.</p>
-
-<p>Suppose you’re debugging the code which contains something like:</p>
-
-<pre><code>csv.each_with_index do |fc_row, i|
-  row = OpenHash[*fc_row.map {|k, v| [(k.to_sym rescue k), (v.to_s.strip rescue v)]}.flatten(1)]
-  ...
-</code></pre>
-
-<p>There’s something wrong with the code and you want to see if <code>row</code> is given the correct value. To do it, use <code>IrbHacks.break</code>:</p>
-
-<pre><code>csv.each_with_index do |fc_row, i|
-  row = OpenHash[*fc_row.map {|k, v| [(k.to_sym rescue k), (v.to_s.strip rescue v)]}.flatten(1)]
-  IrbHacks.break(row)
-</code></pre>
-
-<p>Now all you have to do is write an <code>ae</code> snippet and call it. <code>row</code> value will be available in IRB for inspection:</p>
-
-<pre><code>irb&gt; ae
-(snippet)&gt;&gt; Klass.new.method(args)
-irb&gt; row = a
-# Back in IRB. Do whatever you want with `row` value now.
-irb&gt;
-</code></pre>
-
-<p>Each <code>IrbHacks.break</code> call raises an <code>IrbHacks::BreakException</code>. If you see them popping out runtime, find the appropriate <code>IrbHacks.break</code> calls and defuse them.</p>
-
-<h2 id="configuration">Configuration</h2>
-
-<p>Via <code>IrbHacks.conf</code> object you can configure various features of <code>irb_hacks</code>. Add <code>IrbHacks.conf</code> manipulation code to your <code>.irbrc</code>:</p>
-
-<pre><code>require "rubygems"
-require "irb_hacks"
-
-IrbHacks.conf.snippet_prompt = "&gt;&gt;&gt; "
-</code></pre>
-
-<h3 id="configuration-variables-irbhacksconf">Configuration Variables (<code>IrbHacks.conf.*</code>)</h3>
-
-<ul>
-  <li><code>less_cmd</code> – System command to invoke pager for <code>less</code>.</li>
-  <li><code>snippet_history_file</code> – Snippet (<code>a</code>, <code>ae</code>) history file.</li>
-  <li><code>snippet_history_size</code> – Snippet history size.</li>
-  <li><code>snippet_prompt</code> – Snippet input prompt.</li>
-</ul>
-
-<h2 id="feedback">Feedback</h2>
-
-<p>Send bug reports, suggestions and criticisms through <a href="http://github.com/dadooda/irb_hacks">project’s page on GitHub</a>.</p>
-
-<p>Licensed under the MIT License.</p>