devver-germinate 1.0.0

data/.gitignore

@@ -0,0 +1,2 @@
+pkg
+doc

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 / 2009-07-06
+
+* 1 major enhancement
+  * Birthday!

data/README.rdoc

@@ -0,0 +1,132 @@
+= germinate
+
+by Avdi Grimm
+    
+http://github.com/devver/germinate/
+
+== SYNOPSIS
+
+  germ generate > my_article.rb
+  germ format my_article.rb > my_article.txt
+
+== DESCRIPTION
+
+Germinate is a tool for writing about code.  With Germinate, the source code IS
+the article.
+
+For example, given the following source code:
+
+  # #!/usr/bin/env ruby
+  # :BRACKET_CODE: <pre>, </pre>
+  # :PROCESS: ruby, "ruby %f"
+
+  # :SAMPLE: hello
+  def hello(who)
+    puts "Hello, #{who}"
+  end
+
+  hello("World")
+
+  # :TEXT:
+  # Check out my amazing program!  Here's the hello method:
+  # :INSERT: @hello:/def/../end/
+
+  # And here's the output:
+  # :INSERT: @hello|ruby
+
+When we run the <tt>germ format</tt> command the following output is generated:
+
+  Check out my amazing program!  Here's the hello method:
+  <pre>
+  def hello(who)
+    puts "Hello, #{who}"
+  end
+  </pre>
+  And here's the output:
+  <pre>
+  Hello, World
+  </pre>
+
+To get a better idea of how this works, please take a look at
+link:examples/basic.rb, or run:
+
+  germ generate > basic.rb
+
+To generate an example article to play with.
+
+Germinate is particularly useful for writing articles, such as blog posts, which
+contain code excerpts.  Instead of forcing you to keep a source code file and an
+article document in sync throughout the editing process, the Germinate motto is
+"The source code IS the article".  Specially marked comment sections in your
+code file become the article text.  Wherever you need to reference the source
+code in the article, use insertion directives to tell Germinate what parts of
+the code to excerpt.  An advanced selector syntax enables you to be very
+specific about which lines of code you want to insert.
+
+If you also want to show the output of your code, Germinate has you covered.
+Special "process" directives enable you to define arbitrary commands which can
+be run on your code.  The output of the command then becomes the excerpt text.
+You can define an arbitrary number of processes and have different excerpts
+showing the same code as processed by different commands.  You can even string
+processes together into pipelines.
+
+Development of Germinate is graciously sponsored by Devver, purveyor of fine
+cloud-based services to busy Ruby developers.  If you like this tool please
+check them out at http://devver.net.
+
+== FEATURES
+
+* Language and markup agnostic
+* Advanced selector syntax for excerpting code
+* Define arbitrary command pipelines to preprocess excerpts
+* Article text is reformatted to be more compatible with popular blogging 
+  engines, e.g. WordPress.
+* Introspection commands make it easy to experiment
+* Fully tested
+
+== KNOWN ISSUES
+
+* Directive syntax conflicts with RDoc.  Doh!
+
+== FUTURE
+
+* Integration with blogging platforms, e.g. WordPress
+* Integration with Github's Gist
+
+== REQUIREMENTS
+
+* main
+* fattr
+* ick
+* orderedhash
+* arrayfields
+* alter-ego
+
+== INSTALL:
+
+  gem install --source http://gems.rubyforge.org devver-germinate
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008
+
+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/Rakefile

@@ -0,0 +1,43 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+require 'germinate'
+
+task :default => 'spec:run'
+
+PROJ.name = 'germinate'
+PROJ.authors = 'Avdi Grimm'
+PROJ.email = 'avdi@avdi.org'
+PROJ.url = 'http://github.com/devver/germinate/'
+PROJ.version = Germinate::VERSION
+PROJ.rubyforge.name = 'germinate'
+
+PROJ.spec.opts << '--color'
+
+PROJ.ruby_opts = []
+
+PROJ.readme_file = "README.rdoc"
+PROJ.rdoc.main = "README.rdoc"
+PROJ.rdoc.exclude << "features"
+
+depend_on "ick",         "~> 0.3.0"
+depend_on "fattr",       "~> 1.0.3"
+depend_on "arrayfields", "~> 4.7.3"
+depend_on "orderedhash", "~> 0.0.6"
+depend_on "alter-ego",   "~> 1.0.0"
+depend_on "main",        "~> 2.8.3"
+
+# EOF

data/bin/germ

@@ -0,0 +1,133 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), %w[.. lib germinate]))
+
+require 'main'
+
+Main do
+  description <<-END
+    Germinate - A tool for writing about code.
+
+    With Germinate, your source code is also your article text.  Special
+    directives tell Germinate which parts to format as article text and
+    where to insert source code excerpts and program output.
+
+    To get started, execute:
+
+      germ generate > my_article.rb
+
+    to have Germinate generate a basic example article.
+
+    For more information, see the project homepage at 
+    http://github.com/devver/germinate/
+
+    Development of Germinate is graciously sponsored by Devver, purveyor 
+    of fine cloud-based services to busy Ruby developers.  If you like 
+    this tool please check them out at http://devver.net.
+  END
+
+  author "Avdi Grimm <avdi@avdi.org>"
+
+  version Germinate::VERSION
+
+  def self.source_argument
+    argument :source do
+      arity 1
+      validate{|source| Pathname(source).readable?}
+      description "Source file"
+    end
+  end
+
+  mode :format do
+    description "Format an article for publishing"
+    source_argument
+    def run
+      Germinate.logger = self
+      with_source_file do |source|
+        application = Germinate::Application.new
+        application.format(source, $stdout, $stderr)
+      end
+    end
+  end
+
+  mode :list do
+    description "List various article components"
+    source_argument
+    COLLECTIONS = [:sections, :samples, :processes] 
+    COLLECTIONS.each do |collection| 
+      option collection do
+        description "List all #{collection}"
+        cast :bool
+      end
+    end
+
+    def run
+      things_to_list = []
+      COLLECTIONS.each do |collection|
+        things_to_list << collection if params[collection].value
+      end
+      with_source_file do |source|
+        application = Germinate::Application.new
+        application.list(source, things_to_list, $stdout)
+      end
+    end
+  end
+
+  mode :show do
+    description "Show details about various article components"
+    source_argument
+    TYPES = [:section, :sample, :process] 
+    TYPES.each do |type| 
+      option type do
+        description "Show details about a #{type}"
+        argument_required
+      end
+    end
+
+    def run
+      selection = TYPES.inject({}) {|sel, type|
+        sel[type] = params[type].values
+        sel
+      }
+      with_source_file do |source|
+        application = Germinate::Application.new
+        application.show(source, selection, $stdout)
+      end
+    end
+  end
+
+  mode :select do
+    description "Test out a selector"
+    source_argument
+    option(:selector, :s) do
+      arity 1
+      required
+      argument_required
+      description "The selector to search for"
+    end
+
+    def run
+      with_source_file do |source|
+        application = Germinate::Application.new
+        application.select(source, params[:selector].value, $stdout)
+      end
+    end
+  end
+
+  mode :generate do
+    description "Generate a sample article"
+
+    def run
+      example = File.expand_path("../doc/examples/basic.rb", 
+                                 File.dirname(__FILE__))
+      stdout.write(File.read(example))
+    end
+  end
+
+  def with_source_file(&block)
+    File.open(params['source'].value, &block)
+  end
+end
+
+# EOF

data/cucumber.yml

@@ -0,0 +1,2 @@
+autotest: --no-color --format pretty
+autotest-all: --no-color --format pretty

data/examples/basic.rb

@@ -0,0 +1,118 @@
+# A basic example of a Germinate article.
+#
+# This text is "front matter" and will not be included in the final article.
+# The article doesn't begin until the first text directive.
+#
+# Let's set up code bracketing so that code excerpts will be surrounded by HTML
+# <pre>...</pre> tags.
+#
+# :BRACKET_CODE: <pre>, </pre>
+#
+# :TEXT:
+# This is the first line of the article text.  For the formatted article,
+# Germinate will remove the comment prefixes ("# ") and join paragraphs into
+# single lines.
+#
+# We're coming up on our first code section.  If some code immediately follows a
+# text section it will automatically be inserted into the formatted article
+# text.
+def my_func
+  # ...
+end
+# :END:
+# 
+# The END directive above ends that particular code sample.  This text will not
+# be included in the final article.
+#
+# We don't want to have to write our source code in the order it appears in
+# the article.  Let's define a named code sample.
+#
+# :SAMPLE: hello
+def hello
+  puts "Hello, #{ARGV[0]}"
+end
+hello
+
+# :TEXT:
+# We're back in the article text now.  Let's insert our named sample now.
+# :INSERT: @hello
+#
+# Now lets define some processes and experiment with running the sample through
+# them.
+#
+# :PROCESS: fred, "ruby %f Fred"
+# :PROCESS: jane, "ruby %f Jane"
+# :PROCESS: quote, "ruby -n -e 'puts \"> #{$_}\"'"
+#
+# Note that the "quote" process has no %f placeholder for the filename.
+# If it doesn't find a %f, Germinate will pipe the source sample into the
+# command on its STDIN.
+#
+# Here's the result of \:INSERT: @hello|fred
+# :INSERT: @hello|fred
+#
+# Here's the result of :INSERT: @hello|jane
+# :INSERT: @hello|jane
+#
+# We can even chain processes together. Here's the result of 
+# \:INSERT: @hello|jane|quote
+# :INSERT: @hello|jane|quote
+#
+# It's not necessary to quote whole code samples.  We can select specific lines
+# to excerpt using more advanced selectors.
+#
+# Select a single line
+# \:INSERT: @foo:2
+# :INSERT: @foo:2
+#
+# Select an inclusive range
+# \:INSERT: @foo:2..4
+# :INSERT: @foo:2..4
+#
+# Select an exclusive range
+# \:INSERT: @foo:1...3
+# :INSERT: @foo:1...3
+#
+# Select by starting line and length
+# \:INSERT: @foo:4,4
+# :INSERT: @foo:4,4
+#
+# Select by starting and ending regular expressions
+# \:INSERT: @foo:/do_stuff/../end/
+# :INSERT: @foo:/do_stuff/../end/
+#
+# Select by regex and length
+# \:INSERT: @foo:/attr_reader/,3
+# :INSERT: @foo:/attr_reader/,3
+#
+# :SAMPLE: foo
+class Foo
+  attr_reader :bar
+  attr_reader :baz
+  attr_reader :buz
+
+  def do_stuff
+    # ...
+  end
+end
+# :END:
+
+# :TEXT:
+# Finally, we can include all of the code samples in a single chunk with
+# \:INSERT: $CODE
+# :INSERT: $CODE
+#
+# There are some other special section names, such as $SOURCE and $TEXT.  See
+# the Germinate documentation for more.
+#
+# :CUT:
+#
+# You can format this article for publishing by running:
+#
+#   germ format <filename>
+#
+# If you want to experiment with the selector syntax, try:
+#
+#   germ select -s <selector>
+#
+# Enjoy!

data/examples/short.rb

@@ -0,0 +1,17 @@
+# #!/usr/bin/env ruby
+# :BRACKET_CODE: <pre>, </pre>
+# :PROCESS: ruby, "ruby %f"
+
+# :SAMPLE: hello
+def hello(who)
+  puts "Hello, #{who}"
+end
+
+hello("World")
+
+# :TEXT:
+# Check out my amazing program!  Here's the hello method:
+# :INSERT: @hello:/def/../end/
+
+# And here's the output:
+# :INSERT: @hello|ruby