germinate 1.2.0

data/.gitignore

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

data/History.txt

@@ -0,0 +1,26 @@
+== 1.2.0 / 2009-07-21
+
+* 4 major enhancements
+  * Added "publish" command and pluggable publishers
+  * Added builtin publisher "shell" for publishing via shell command
+  * Added variables, settable with the :SET: directive
+  * Added the ability for commands to write changes back to the source file
+    (with backups)
+* 2 minor enhancements
+  * Refactored standard text transforms to be just another process
+  * Made the list/show/select command arguments easier to use
+
+== 1.1.0 / 2009-07-12
+
+* 1 major enhancement
+  * Added post-pipeline excerpting, e.g. $SOURCE|ruby:/def foo/../end/
+    Post-pipeline excerpting executes the process against the entire sample and 
+    then excerpts the output.
+* 1 minor enhancement
+  * Processes applied to $SOURCE will be given the actual source path instead of
+    a temp file
+
+== 1.0.0 / 2009-07-06
+
+* 1 major enhancement
+  * Birthday!

data/README.rdoc

@@ -0,0 +1,152 @@
+= 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.
+
+== WHAT GERMINATE IS NOT
+
+Germinate is not a markup language like HTML, Textile, or Markdown.  It is
+completely markup-agnostic, although it can be configured to automatically
+pre-process your articles with markup tools before publishing.  Germinate
+concerns itslf strictly with bringing together your words and your code, and
+with automating the process of publishing the finished product.
+
+Germinate is not a code documentation tool.  While it facilitates the process of
+writing *about* code, it has no understanding of the code itself.  Germinate is
+orthogonal to tools such as RDoc or Doxygen.
+
+Germinate is not a blogging engine.  It is designed to integrate with your
+favorite blogging engine through publisher plugins.
+
+Germinate is none of these things, but it is designed to complement all of
+them.
+
+== 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.
+* Extensable with plugins for publishing to Gist, WordPress, etc.
+* Introspection commands make it easy to experiment
+
+== KNOWN ISSUES
+
+* Directive syntax conflicts with RDoc.  Doh!
+* Focus is currently on features.  Documentation is lacking.  Have a look at the
+  features/ directory to get a better idea of various Germinate features.
+
+== FUTURE
+
+* Integration with blogging platforms, e.g. WordPress
+
+== REQUIREMENTS
+
+* Ruby 1.8
+* main
+* fattr
+* ick
+* orderedhash
+* arrayfields
+* alter-ego
+
+== INSTALL:
+
+  gem install --source http://gems.rubyforge.org devver-germinate
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009
+
+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/TODO

@@ -0,0 +1,140 @@
+# -*- mode: org -*-
+#+SEQ_TODO:  TODO | DONE INVALID
+
+* INVALID Fix bug in `germ select`                          :bug:
+  CLOSED: [2009-07-12 Sun 18:25]
+:   germ select -s "$SOURCE|ruby" ruby_subprocesses_part_2.rb 
+:   F, [2009-07-12T17:41:17.331337 #19506] FATAL -- : No code sample named 'SECTION0'.  Known samples: helpers, SECTION3, open_with_pipe, open_with_pipe_dash, popen, popen_with_dash, SECTION8 (IndexError)
+
+<2009-07-12 Sun> My mistake... the shell was interpreting the $SOURCE directive.
+    
+* DONE Make $SOURCE use the actual source file path in processes
+  CLOSED: [2009-07-12 Sun 19:46]
+
+* DONE Improve error message for non-matching regexen in selectors :usability:
+  CLOSED: [2009-07-13 Mon 02:17]
+* DONE Make text transforms just another process for pipelines :techdebt:
+  CLOSED: [2009-07-19 Sun 16:33]
+  This should help make [[*Make%20it%20possible%20for%20publishers%20to%20use%20formatted%20text%20as%20input][this item]] possible.
+* DONE Add standard "select" option to publishers
+  CLOSED: [2009-07-19 Sun 16:33]
+  The select option would define a selector to be used to get the input for the
+  publisher. Another step towards [[*Make%20it%20possible%20for%20publishers%20to%20use%20formatted%20text%20as%20input][this]].
+
+  This MAY make the current "pipeline" option redundant.
+* DONE Make it possible for publishers to use formatted text as input :feature:
+  CLOSED: [2009-07-19 Sun 16:33]
+  Pretty useless without this...
+
+* TODO Refactor format command into a null publisher        :techdebt:
+  This just needs one last step of pre-loading a "stdout publisher" and then we
+  can do e.g.:
+  
+  : germ publish stdout my_article.c
+* TODO Output line numbers for Reader errors                :usability:
+
+* DONE Gist uploads                                         :feature:
+  CLOSED: [2009-07-21 Tue 10:54]
+
+* DONE Publishing to WordPress blogs (Atompub)              :feature:
+  CLOSED: [2009-07-21 Tue 10:54]
+
+* TODO Alternate directive syntax                           :usability:
+  one that doesn't conflict with RDoc
+
+* TODO Anonymous processes                                  :feature:
+  A process that doesn't match a predefined process name should be interpreted
+  as a shell command.
+
+* TODO Code indent                                          :feature:
+  Define an indent (either N spaces or a string) to be applied to code sections.
+
+  Should first de-indent code.
+
+* TODO Shorthand for matching whitespace in selectors       :feature:
+  e.g. "@mysample:/def foo/..._"
+
+* TODO Format Pipelines                                     :feature:
+  Define a pipeline to be run on the entire article after formatting
+
+  Or maybe just demote "format" to be a built-in publisher.
+* TODO ERB Substitution                                     :feature:
+  Should be run on TEXT sections.
+
+* TODO Line# Helper                                         :feature:
+  A helper for ERB subtitution which inserts the line# of a given selector.
+
+* TODO Plugin API                                           :feature:
+* TODO User-global preference file                          :feature:
+
+* TODO Multiple file support                                :feature:
+
+* TODO Output line numbers for errors at any point          :usability:
+  This will require giving Hunks the knowledge of their source offset.
+  
+* TODO Nested samples                                       :feature:
+  Might want to wait this on the implementation of nested states in AlterEgo.
+
+* TODO Optionally capture STDERR from processes             :feature:
+
+  Workaround: Authors can just include 2>&1 in their process definitions.
+
+* DONE Syntax for post-process excerpting                   :feature:
+  CLOSED: [2009-07-12 Sun 20:50]
+  E.g. "$SOURCE|ruby:/---/../---/"
+
+  This would cause the process to be run on $SOURCE and then a subset of the
+  output to be excerpted.
+
+* TODO Named Styles                                         :feature:
+  A way to group together a bunch of style attributes in a reusable way.
+* DONE A way to set arbitrary variables for later substitution :feature:
+  CLOSED: [2009-07-16 Thu 11:51]
+* DONE Standard "pipeline" option for publishers            :feature:
+  CLOSED: [2009-07-15 Wed 01:32]
+  Defines a pipeline which will be run on $SOURCE before publishing.
+* TODO Plugin discovery                                     :feature:
+  Should use gems to discover plugins.
+
+* TODO Line continuations for directives                    :usability:
+  After some thought I think what I really want is a second syntax for long-form
+  directives, wherein the YAML arguments go in between directive opening and
+  closing lines.  E.g.
+
+  : # :PUBLISHER: ---
+  : # - source
+  : # - shell
+  : # - 
+  : #   command: cat
+  : #   pipeline: markdown
+  : # :END:
+* DONE Variables
+  CLOSED: [2009-07-16 Thu 19:47]
+  Syntax:
+  : :SET: foo, 123
+*** Reader records what line they were set on
+*** SourceFile class which can set and re-set variables
+    - Backs the file up first
+    - Verifies the backup
+    - Locks the file and the backup
+    - Removes the old line
+    - Replaces it with a new :SET: line
+    - Or adds a new :SET: line to the end
+    - Re-reads and verifies value
+    - Restores the backup if there is a problem
+    
+*** Variables are available to processes as environment vars
+* TODO Add processing/style options to TEXT sections        :feature:
+* TODO Add console modes                                    :feature:
+*** TODO Shell console
+    In this version we just exec $SHELL with some custom environment.  A
+    GERMINATE_SOURCE variable should point to the source file, and all germ
+    commands should use it if no explicit source is specified.
+
+    In addition, aliases for all the common germ modes should be installed -
+    publish, format, list, etc.
+*** TODO Debug console
+    An IRB session with Germinate preloaded.
+
+* TODO Clean up output during tests                         :techdebt:
+* TODO Add a dry-run mode                                   :feature:

data/bin/germ

@@ -0,0 +1,260 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), %w[.. lib germinate]))
+
+require 'English'
+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
+
+  option(:debug, :d) do 
+    cast :bool
+  end
+
+  def run
+    help!
+  end
+
+  mode :format do
+    description "Format an article for publishing"
+    source_argument
+    def run
+      with_source_file do |source, path|
+        @application.format(source, path)
+      end
+    end
+  end
+
+  mode :list do
+    description "List info about the source file"
+    argument :collection do
+      arity 1
+      required
+      argument_required
+      description "One of: sections, samples, processes, publishers, variables"
+    end
+    source_argument
+
+    def run
+      with_source_file do |source, path|
+        @application.list(source, path, params[:collection].value)
+      end
+    end
+  end
+
+  mode :show do
+    description "Show details about various article components"
+    argument :type do
+      arity 1
+      required
+      argument_required
+      description "One of: section, sample, process, publisher, variable"
+    end
+    argument :item do
+      arity 1
+      required
+      argument_required
+      description "The specific item to show details about"
+    end
+    source_argument
+
+    def run
+      with_source_file do |source, path|
+        @application.show(source, path, params['type'].value, params['item'].value)
+      end
+    end
+  end
+
+  mode :select do
+    description "Test out a selector"
+    argument :selector do
+      arity 1
+      required
+      argument_required
+      description "The selector to retrieve"
+    end
+    source_argument
+
+    Germinate::TextTransforms.singleton_methods.each do |transform|
+      option(transform) do
+        description "Enable/disable the '#{transform}' text transform"
+        cast :bool
+      end
+    end
+
+    def run
+      options = Germinate::TextTransforms.singleton_methods.inject({}) do 
+        |opts, transform|
+        if params[transform].given?
+          opts[transform] = params[transform].value
+          logger.info "Text transform '#{transform}' " + 
+            (params[transform].value ? "enabled" : "disabled")
+        end
+        opts
+      end
+      with_source_file do |source, path|
+        @application.select(source, path, params[:selector].value, options)
+      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
+
+  mode :publish do
+    description "Publish the article using the named publisher"
+    argument :publisher
+    source_argument
+    option 'publish-options' do
+      arity 1
+    end
+
+    def run
+      with_source_file do |source, path|
+        options = YAML.load(params['publish-options'].value || "{}")
+        @application.publish(source, path, params[:publisher].value, options)
+      end
+    end
+  end
+
+  mode :set do
+    description "Set a named value in the article"
+    argument :name do
+      description "Variable name"
+      cast :string
+    end
+    argument :value do
+      description "Variable value"
+      cast :string
+    end
+    source_argument
+
+    def run
+      with_source_file do |source, path|
+        @application.set(
+          source, 
+          path, 
+          params[:name].value, 
+          params[:value].value)
+      end
+    end
+  end
+
+  def initialize
+    @command = "#{$PROGRAM_NAME} #{ARGV.join(' ')}"
+    Germinate.logger = logger
+    logger.progname = "germinate"
+    logger.formatter = lambda { |severity, time, progname, message| 
+      lines = case message
+              when ::String then message.split("\n")
+              when ::Exception then 
+                Array(message.message) + Array(message.backtrace)
+              else
+                message.inspect
+              end
+      lines.map{|l| "#{severity} -- #{progname}: #{l}"}.join("\n") + "\n"
+    }
+    @application = Germinate::Application.new(stdout, stderr)
+    @application.load_plugins!
+  end
+
+  def pre_parse_parameters
+  end
+
+  def pre_run
+    logger.level = params['debug'].value ? Logger::DEBUG : Logger::INFO
+  end
+
+  def with_source_file
+    rescue_errors do
+      path = params['source'].value
+      File.open(path) do |file|
+        yield file, path
+      end
+    end
+  end
+
+  def rescue_errors
+    yield
+  rescue RuntimeError => error
+    raise if params['debug'].value
+    log_user_error(error)
+  rescue Exception => error
+    raise if params['debug'].value
+    log_program_error(error)
+  end
+
+  def log_user_error(error)
+    log_fatal_error <<-END
+Germinate could not complete your command.
+Please check your command and article for proper syntax.
+#{command_report}
+#{error_report(error)}
+For more information, re-run the command with the --debug flag.
+END
+  end
+
+  def log_program_error(error)
+    log_fatal_error <<-END 
+Germinate encountered an error while executing your command.
+#{command_report}
+#{error_report(error)}
+Please re-run the command with the --debug flag, and file a problem report at 
+http://github.com/devver/germinate/
+END
+  end
+
+  def command_report
+    "The command was: '#{@command}'"
+  end
+
+  def error_report(error)
+    "The error was: '#{error.message}'"
+  end
+
+  def log_fatal_error(error)
+    logger.fatal(error)
+  end
+end
+
+# EOF