+ Customizing the Hobix Command Line

[why the lucky stiff]

=== Yer Daily Tip: Customizing the Hobix Command Line ===

The Hobix command line tool is a very simple bit of code.  Since 
configuration settings are stored in your ~/.hobixrc, the command line 
doesn't take any configuration options, just command phrases.  Each 
command phrase corresponds to a set of methods in Hobix::CommandLine 
which wrap Hobix API calls.

The commandline has three basic types of phrases:

  * app: Application-wide (such as 'upgrade')
  * weblog: Weblog management (such as 'create' or 'add')
  * action: Weblog activities (such as 'post' or 'regen')

New phrases are added by introducing new methods into the 
Hobix::CommandLine class.  Each phrases requires three methods to be 
added: an explanation method, an argument list method, and the method 
which will actually enact the command

For example, here's the code for the 'upgen' command:

  class Hobix::CommandLine
    # Update the site
    def upgen_action_explain; "Update site with only the latest 
changes."; end
    def upgen_action_args; ['weblog-name']; end
    def upgen_action( weblog )
        weblog.regenerate( :update )
    end
  end

The 'explain' and 'args' command types are used to generate the argument 
list and explanatory text when the user runs 'hobix help'.  Note that 
every `action' command type must accept a Hobix::Weblog object as its 
first parameter.

=== Adding Your Own CommandLine Actions ===

First, decide what type of command you will require.  Generally, you 
should stay away from adding new 'app' commands, these are reserved for 
maintenance of the software.

William's script for importing Blosxom blogs would probably be 
categorized as a 'weblog' command.   One might envision William's 
command looking like this in 'hobix help':

  blosxom weblog-name /path/to/blosxom/entries     Imports blog entries 
from blosxom.  (Creates weblog if non-existant.)

And here's the methods we'd add to get this working:

  class Hobix::CommandLine
     def blosxom_weblog_explain
        "Imports blog entries from blosxom.  (Creates weblog if 
non-existant.)"
     end
     def blosxom_weblog_args
        ['weblog-name', '/path/to/blosxom/entries']
     end
     def blosxom_weblog( weblog_name, blosxom_path )]
        # check existence of weblog
        if @config['weblog'].has_key? weblog_name
           print "Create weblog `#{ weblog_name }'? [Y/n]"
           # create weblog code here
        end
        # perhaps ask for location of entries_index, then
        # import posts.
     end
  end

You are encouraged to make your command full-featured and interactive.  
If there are subtleties in the configuration, throw Yes/No prompts at 
the user to give them the choice to decide.  The Hobix commandline is 
designed to be interactive, not automatic.  The API should be scripted 
for automation.

For now, changes will need to be patch right into hobix/commandline.rb.  
In the next few days, I'll add a `requires' list to the `~/.hobixrc' 
structure which will allow loading of commandline plugins.