germinate 1.2.0

data/features/example_output/escaping.out

@@ -0,0 +1,5 @@
+Here are some Germinate directives :TEXT: :SAMPLE: :INSERT: You get the idea.
+
+It works in code too:
+
+# :PROCESS: foo, bar

data/features/example_output/excerpt_output.out

@@ -0,0 +1,6 @@
+===
+line 2
+=====
+---
+line 1
+-----

data/features/example_output/hello.txt

@@ -0,0 +1 @@
+Hello, world!

data/features/example_output/pipelines.out

@@ -0,0 +1,28 @@
+Sorting the sample:
+aaron
+george
+joe
+sally
+susan
+zack
+
+Quoting the sample:
+> joe
+> sally
+> aaron
+> george
+> zack
+> susan
+
+We can combine pipelines with excerpting:
+> sally
+> aaron
+> george
+
+And we can chain processes to form a true pipeline:
+> aaron
+> george
+> joe
+> sally
+> susan
+> zack

data/features/example_output/regexen.txt

@@ -0,0 +1,22 @@
+We can select code by regexp
+def foo
+  # ...
+end
+
+Or with a regex and a length
+def bar
+  # ...
+end
+
+class Frob
+  # ...
+end
+
+Ending offset can be exclusive
+def foo
+  # ...
+end
+
+def bar
+  # ...
+end

data/features/example_output/sample_offsets.txt

@@ -0,0 +1,15 @@
+We can specify a starting offset:
+a_line_2 = 2
+
+And an ending offset
+a_line_2 = 2
+a_line_3 = 3
+
+Ending offset can be exclusive
+a_line_1 = 1
+a_line_2 = 2
+
+We can specify offset and count instead
+a_line_2 = 2
+a_line_3 = 3
+a_line_4 = 4

data/features/example_output/specials.txt

@@ -0,0 +1,40 @@
+We can paste in all the code:
+a_line_1 = 1
+a_line_2 = 2
+a_line_3 = 3
+a_line_4 = 4
+
+b_line_1 = 1
+b_line_2 = 2
+
+
+Or all the text:
+# We can paste in all the code:
+Insertion[$CODE(<Unknown>)]
+# 
+# Or all the text:
+Insertion[$TEXT(<Unknown>)]
+#
+# Or the entire source file
+Insertion[$SOURCE(<Unknown>)]
+
+Or the entire source file
+# :SAMPLE: A
+a_line_1 = 1
+a_line_2 = 2
+a_line_3 = 3
+a_line_4 = 4
+
+# :SAMPLE: B
+b_line_1 = 1
+b_line_2 = 2
+
+# :TEXT:
+# We can paste in all the code:
+# :INSERT: $CODE, { disable_transforms: true }
+# 
+# Or all the text:
+# :INSERT: $TEXT, { disable_transforms: true }
+#
+# Or the entire source file
+# :INSERT: $SOURCE, { disable_transforms: true }

data/features/example_output/stderr.out

@@ -0,0 +1,3 @@
+Hello, STDOUT
+Hello, STDERR
+Hello again, STDOUT

data/features/example_output/wrapping.txt

@@ -0,0 +1,3 @@
+'Twas brillig and the slithy toves Did gyre and gimbal in the wabe
+
+All mimsy were the borogroves And the momeraths outgrabe

data/features/step_definitions/germinate.rb

@@ -0,0 +1,42 @@
+require 'tempfile'
+
+Given /^the article "([^\"]*)"$/ do |article_file|
+  @filename = (EXAMPLE_ARTICLES + article_file)
+end
+
+When /^I run the format command on the article$/ do
+  run_germinate("format #{@filename}")
+end
+
+When /^I run the command "([^\"]*)" on the article$/ do |command|
+  run_germinate(command.sub(/^germ /,"") + " #{@filename}")
+end
+
+Then /^the output should look like "([^\"]*)"$/ do |output_file|
+  example_path   = (EXAMPLE_OUTPUT + output_file)
+  example_output = example_path.read
+  @output.should == example_output
+end
+
+Given /^an article with the contents:$/ do |contents|
+  file = Tempfile.open("germinate_example_article")
+  file.write(contents)
+  file.close
+  at_exit do
+    file.delete
+  end
+  @filename   = Pathname(file.path)
+end
+
+Then /^the output should be as follows:$/ do |example_output|
+  @output.strip.should == example_output.strip
+end
+
+Then /^the article contents should be:$/ do |contents|
+  @filename.read.strip.should == contents.strip
+end
+
+Then /^the article backup contents should be:$/ do |contents|
+  Pathname(@filename.to_s + ".germ.bak").read.should == contents
+end
+

data/features/support/env.rb

@@ -0,0 +1,20 @@
+require 'English'
+require 'pathname'
+require 'spec/expectations'
+require File.expand_path('../../lib/germinate', File.dirname(__FILE__))
+
+EXAMPLE_ARTICLES = (Pathname(__FILE__).dirname + '../example_articles')
+EXAMPLE_OUTPUT = (Pathname(__FILE__).dirname + '../example_output')
+EXAMPLE_BIN = (Pathname(__FILE__).dirname + '../bin')
+
+ENV['PATH'] += ":" + EXAMPLE_BIN.to_s
+
+def run_germinate(arguments, permit_failure=false)
+  exec_path = (Pathname(__FILE__).dirname + '..' + '..' + 'bin/germ').expand_path
+  command   = "#{exec_path} #{arguments}"
+  @output   = `#{command}`
+  @result   = $CHILD_STATUS
+  raise "Command `#{command}` failed" unless @result.success? or permit_failure
+end
+
+

data/germinate.gemspec

@@ -0,0 +1,55 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{germinate}
+  s.version = "1.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Avdi Grimm"]
+  s.date = %q{2009-07-21}
+  s.default_executable = %q{germ}
+  s.description = %q{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.}
+  s.email = %q{avdi@avdi.org}
+  s.executables = ["germ"]
+  s.extra_rdoc_files = ["History.txt", "README.rdoc", "bin/germ"]
+  s.files = [".gitignore", "History.txt", "README.rdoc", "Rakefile", "TODO", "bin/germ", "cucumber.yml", "examples/basic.rb", "examples/short.rb", "features/author-formats-article.feature", "features/author-lists-info.pending_feature", "features/author-publishes-article-source.feature", "features/author-publishes-article.feature", "features/author-republishes-article.feature", "features/author-selects-hunks.feature", "features/author-sets-variables.feature", "features/author-updates-article-source.feature", "features/author-views-stuff.pending_feature", "features/bin/quoter", "features/bin/sorter", "features/example_articles/bracketing.rb", "features/example_articles/escaping.txt", "features/example_articles/excerpt_output.rb", "features/example_articles/hello.rb", "features/example_articles/pipelines.txt", "features/example_articles/regexen.rb", "features/example_articles/sample_offsets.rb", "features/example_articles/specials.rb", "features/example_articles/stderr.rb", "features/example_articles/wrapping.rb", "features/example_output/bracketing.out", "features/example_output/code_samples.txt", "features/example_output/escaping.out", "features/example_output/excerpt_output.out", "features/example_output/hello.txt", "features/example_output/pipelines.out", "features/example_output/regexen.txt", "features/example_output/sample_offsets.txt", "features/example_output/specials.txt", "features/example_output/stderr.out", "features/example_output/wrapping.txt", "features/step_definitions/germinate.rb", "features/support/env.rb", "germinate.gemspec", "lib/germinate.rb", "lib/germinate/application.rb", "lib/germinate/article_editor.rb", "lib/germinate/formatter.rb", "lib/germinate/hunk.rb", "lib/germinate/implicit_insertion.rb", "lib/germinate/insertion.rb", "lib/germinate/librarian.rb", "lib/germinate/origin.rb", "lib/germinate/pipeline.rb", "lib/germinate/publisher.rb", "lib/germinate/reader.rb", "lib/germinate/selector.rb", "lib/germinate/shared_style_attributes.rb", "lib/germinate/shell_process.rb", "lib/germinate/shell_publisher.rb", "lib/germinate/simple_publisher.rb", "lib/germinate/source_file.rb", "lib/germinate/text_transforms.rb", "lib/germinate/transform_process.rb", "lib/germinate/variable.rb", "sample.rb", "spec/germinate/application_spec.rb", "spec/germinate/article_editor_spec.rb", "spec/germinate/code_hunk_spec.rb", "spec/germinate/file_hunk_spec.rb", "spec/germinate/formatter_spec.rb", "spec/germinate/hunk_spec.rb", "spec/germinate/implicit_insertion_spec.rb", "spec/germinate/insertion_spec.rb", "spec/germinate/librarian_spec.rb", "spec/germinate/pipeline_spec.rb", "spec/germinate/process_spec.rb", "spec/germinate/publisher_spec.rb", "spec/germinate/reader_spec.rb", "spec/germinate/selector_spec.rb", "spec/germinate/shell_publisher_spec.rb", "spec/germinate/source_file_spec.rb", "spec/germinate/text_hunk_spec.rb", "spec/germinate/text_transforms_spec.rb", "spec/germinate/transform_process_spec.rb", "spec/germinate/variable_spec.rb", "spec/germinate_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "tasks/ann.rake", "tasks/bones.rake", "tasks/cucumber.rake", "tasks/gem.rake", "tasks/git.rake", "tasks/notes.rake", "tasks/post_load.rake", "tasks/rdoc.rake", "tasks/rubyforge.rake", "tasks/setup.rb", "tasks/spec.rake", "tasks/svn.rake", "tasks/test.rake", "tasks/zentest.rake", "test/test_germinate.rb"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/devver/germinate/}
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{germinate}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{Germinate is a tool for writing about code}
+  s.test_files = ["test/test_germinate.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<ick>, ["~> 0.3.0"])
+      s.add_runtime_dependency(%q<fattr>, ["~> 1.0.3"])
+      s.add_runtime_dependency(%q<arrayfields>, ["~> 4.7.3"])
+      s.add_runtime_dependency(%q<orderedhash>, ["~> 0.0.6"])
+      s.add_runtime_dependency(%q<alter-ego>, ["~> 1.0.0"])
+      s.add_runtime_dependency(%q<main>, ["~> 2.8.3"])
+      s.add_development_dependency(%q<bones>, [">= 2.5.1"])
+    else
+      s.add_dependency(%q<ick>, ["~> 0.3.0"])
+      s.add_dependency(%q<fattr>, ["~> 1.0.3"])
+      s.add_dependency(%q<arrayfields>, ["~> 4.7.3"])
+      s.add_dependency(%q<orderedhash>, ["~> 0.0.6"])
+      s.add_dependency(%q<alter-ego>, ["~> 1.0.0"])
+      s.add_dependency(%q<main>, ["~> 2.8.3"])
+      s.add_dependency(%q<bones>, [">= 2.5.1"])
+    end
+  else
+    s.add_dependency(%q<ick>, ["~> 0.3.0"])
+    s.add_dependency(%q<fattr>, ["~> 1.0.3"])
+    s.add_dependency(%q<arrayfields>, ["~> 4.7.3"])
+    s.add_dependency(%q<orderedhash>, ["~> 0.0.6"])
+    s.add_dependency(%q<alter-ego>, ["~> 1.0.0"])
+    s.add_dependency(%q<main>, ["~> 2.8.3"])
+    s.add_dependency(%q<bones>, [">= 2.5.1"])
+  end
+end

data/lib/germinate.rb

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'fattr'
+require 'logger'
+
+module Germinate
+
+  # :stopdoc:
+  VERSION = '1.2.0'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to require all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+  Fattr(:logger) { Logger.new($stderr) }
+
+end  # module Germinate
+
+Germinate.require_all_libs_relative_to(__FILE__)
+
+# EOF

data/lib/germinate/application.rb

@@ -0,0 +1,113 @@
+require 'English'
+
+# The Application ties all the other componts together.  It has public methods
+# roughly corresponding commands that the 'germ' command-line tool supports.
+class Germinate::Application
+  attr_writer :formatter
+
+  def initialize(output, errors)
+    @output       = output
+    @error_output = errors
+    @log          = Germinate.logger
+    @plugins      = []
+  end
+
+  # Search Rubygems for Germinate plugins and load them
+  def load_plugins!
+    $LOAD_PATH.each do |dir|
+      plugin_init = Pathname(dir) + 'germinate_plugin_v0_init.rb'
+      if plugin_init.readable?
+        load_plugin!(plugin_init.to_s)
+      end
+    end
+    Gem.find_files('germinate_plugin_v0_init').each do |file|
+      load_plugin!(file)
+    end
+  end
+
+  def format(source, path)
+    librarian = load_librarian(source, path)
+    publisher = Germinate::SimplePublisher.new("simple", librarian)
+    publisher.publish!(@output)
+  end
+
+  def list(source, path, collection)
+    librarian = load_librarian(source, path)
+    case collection
+    when "sections"
+      @output.puts(librarian.section_names.join("\n"))
+    when "samples"
+      @output.puts(librarian.sample_names.join("\n"))
+    when "processes"
+      @output.puts(librarian.process_names.join("\n"))
+    when "publishers"
+      @output.puts(*librarian.publisher_names)
+    when "all_publishers"
+      Germinate::Publisher.registered_publishers.keys do |p|
+        @output.puts(p)
+      end
+    when "variables"
+      librarian.variables.each_pair do |name, value|
+        @output.puts("%-20s %s" % [name, value.to_s])
+      end
+    when "plugins"
+      @plugins.each do |plugin|
+        puts(plugin)
+      end
+    else
+      raise "I don't know how to list '#{collection}'"
+    end
+  end
+
+  def show(source, path, item_type, item)
+    librarian = load_librarian(source, path)
+    case item_type
+    when "section"
+      @output.puts(librarian.section(item))
+    when "sample"
+      @output.puts(librarian.sample(item))
+    when "process"
+      @output.puts(librarian.process(item).command)
+    when "publisher"
+      @output.puts(librarian.publisher(item))
+    else
+      raise "I don't know how to show '#{item_type}'"
+    end
+  end
+
+  def select(source, path, selector, options, origin="command line")
+    librarian = load_librarian(source, path)
+    @output.puts(*librarian[selector, origin, options])
+  end
+
+  def publish(source, path, publisher, options={})
+    librarian = load_librarian(source, path)
+    librarian.publisher(publisher).publish!(@output, options)
+    librarian.store_changes!
+  end
+
+  def set(source, path, name, value)
+    librarian = load_librarian(source, path)
+    librarian.variables[name] = value
+    librarian.store_changes!
+  end
+
+  private
+
+  def load_librarian(source, path)
+    librarian = Germinate::Librarian.new
+    reader    = Germinate::Reader.new(librarian, path)
+    source.each_line do |line|
+      reader << line
+    end
+    librarian
+  end
+
+  def load_plugin!(file)
+    unless @plugins.include?(file)
+      @log.debug "Loading plugin: #{file}"
+      Kernel.load(file)
+      @plugins << File.dirname(file)
+    end
+  end
+end

data/lib/germinate/article_editor.rb

@@ -0,0 +1,20 @@
+# An Editor is responsible for selecting hunks of text from a Librarian and
+# assembling them into a list for formatting.
+class Germinate::ArticleEditor
+  def initialize(librarian)
+    @librarian = librarian
+  end
+
+  def each_hunk(&block)
+    librarian.section_names.each do |section_name|
+      yield librarian.section(section_name).resolve_insertions
+      if librarian.has_sample?(section_name)
+        yield librarian.sample(section_name).resolve_insertions 
+      end
+    end
+  end
+
+  private
+
+  attr_reader :librarian
+end