devver-germinate 1.1.0 → 1.2.0

data/History.txt

@@ -1,3 +1,15 @@
+== 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

data/README.rdoc

@@ -74,6 +74,24 @@ 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
@@ -81,20 +99,22 @@ check them out at http://devver.net.
 * 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
-* Fully tested
 
 == 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
-* Integration with Github's Gist
+* See the TODO file
 
 == REQUIREMENTS
 
+* Ruby 1.8
 * main
 * fattr
 * ick
@@ -105,12 +125,14 @@ check them out at http://devver.net.
 == INSTALL:
 
   gem install --source http://gems.rubyforge.org devver-germinate
+  gem install --source http://gems.rubyforge.org devver-germinate-gist
+  gem install --source http://gems.rubyforge.org devver-germinate-atompub
 
 == LICENSE:
 
 (The MIT License)
 
-Copyright (c) 2008
+Copyright (c) 2009
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/TODO

@@ -11,13 +11,33 @@
 * DONE Make $SOURCE use the actual source file path in processes
   CLOSED: [2009-07-12 Sun 19:46]
 
-* TODO Improve error message for non-matching regexen in selectors :usability:
-
+* 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:
 
-* TODO Gist uploads                                         :feature:
+* DONE Gist uploads                                         :feature:
+  CLOSED: [2009-07-21 Tue 10:54]
 
-* TODO Publishing to WordPress blogs (Atompub)              :feature:
+* 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
@@ -37,6 +57,7 @@
 * 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.
 
@@ -44,8 +65,6 @@
   A helper for ERB subtitution which inserts the line# of a given selector.
 
 * TODO Plugin API                                           :feature:
-  Should use gems to discover plugins.
-
 * TODO User-global preference file                          :feature:
 
 * TODO Multiple file support                                :feature:
@@ -60,12 +79,65 @@
 
   Workaround: Authors can just include 2>&1 in their process definitions.
 
-* DONE Syntax for post-process excerpting
+* 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
+* 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:
+* TODO Add a TITLE variable
+  Should be used by publishers.
+* TODO Make publishers more configurable

data/bin/germ

@@ -3,6 +3,7 @@
 require File.expand_path(
     File.join(File.dirname(__FILE__), %w[.. lib germinate]))
 
+require 'English'
 require 'main'
 
 Main do
@@ -39,78 +40,93 @@ Main do
     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
-      Germinate.logger = self
       with_source_file do |source, path|
-        application = Germinate::Application.new
-        application.format(source, path, $stdout, $stderr)
+        @application.format(source, path)
       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
+    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
-      things_to_list = []
-      COLLECTIONS.each do |collection|
-        things_to_list << collection if params[collection].value
-      end
       with_source_file do |source, path|
-        application = Germinate::Application.new
-        application.list(source, path, things_to_list, $stdout)
+        @application.list(source, path, params[:collection].value)
       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
+    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
-      selection = TYPES.inject({}) {|sel, type|
-        sel[type] = params[type].values
-        sel
-      }
       with_source_file do |source, path|
-        application = Germinate::Application.new
-        application.show(source, path, selection, $stdout)
+        @application.show(source, path, params['type'].value, params['item'].value)
       end
     end
   end
 
   mode :select do
     description "Test out a selector"
-    source_argument
-    option(:selector, :s) do
+    argument :selector do
       arity 1
       required
       argument_required
-      description "The selector to search for"
+      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 = Germinate::Application.new
-        application.select(source, path, params[:selector].value, $stdout)
+        @application.select(source, path, params[:selector].value, options)
       end
     end
   end
@@ -125,12 +141,120 @@ Main do
     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
-    path = params['source'].value
-    File.open(path) do |file|
-      yield file, path
+    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