rubysync 0.1.1 → 0.2.1

data/bin/rubysync.rb

@@ -1,77 +1,77 @@
 #!/usr/bin/env ruby
 
 
-  # == Synopsis
-  # 
-  #   Command line tool for running *rubysync* <em>A Free MetaDirectory.</em>
-  # 
-  # == Usage
-  #   
-  #     rubysync command name [options]
-  #   
-  #  Valid commands are::
-  #   * create {name}::            Create a rubysync configuration directory
-  # 
-  #   * connector {name} -t {type} [--vault {name}] [--client {name}]
-  #                           ; Create a connector of the given name in
-  #                           ; the current rubysync configuration directory
-  #                         
-  #   * fields {name}           ; list the fields detected by the named connector
-  # 
-  #   * pipeline {name}         ; Create a rubysync pipeline of the given name
-  #                           ; in the current rubysync configuration directory
-  #                         
-  #   * once {name}::             
-  #       Execute the named pipeline within the current configuration directory once and then exit
-  #                         
-  #   * example::          Show an example of how this command might be used
-  # 
-  # == Example
-  # 
-  #   This sets up the skeleton of a configuration for importing comma delimeted
-  #   text files into an xml file.
-  #     <tt>
-  #     $ rubysync create xml_demo
-  #     $ cd xml_demo
-  #     $ rubysync connector my_csv -t csv_file
-  #     $ rubysync connector my_xml -t xml
-  #     </tt>
-  #   
-  #   You would then edit the files::
-  # 
-  #     * +connectors/my_csv_connector.rb+:: where to get the CSV files, field names, etc
-  #     * +connectors/my_xml_connector.rb+::  how to connect to your XML file.
-  # 
-  #   And enter::
-  #     <tt>
-  #     $ rubysync pipeline my_pipeline -C my_csv -V my_xml
-  #     </tt>
-  # 
-  #   You would then edit the file +pipelines/my_pipeline.rb+ to configure the
-  #   policy for synchronizing between the two connectors.
-  #                                         
-  #   You may then execute the pipeline in one-shot mode (daemon mode is coming)::
-  # 
-  #     <tt>
-  #     $ rubysync once my_pipeline
-  #     </tt>
-  # 
-  # == Author
-  #   Ritchie Young, 9 to 5 Magic (http://9to5magic.com.au)
-  #  
-  # == Copyright
-  #   Copyright (c) 2007 Ritchie Young. All rights reserved.
-  # 
-  # This file is part of RubySync.
-  # 
-  # RubySync is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License
-  # as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
-  # 
-  # RubySync is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
-  # warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
-  # 
-  # You should have received a copy of the GNU General Public License along with RubySync; if not, write to the
-  # Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
+# == Synopsis
+# 
+#   Command line tool for running *rubysync* <em>A Free MetaDirectory.</em>
+# 
+# == Usage
+#   
+#     rubysync command name [options]
+#   
+#  Valid commands are::
+#   * create {name}::            Create a rubysync configuration directory
+# 
+#   * connector {name} -t {type} [--vault {name}] [--client {name}]
+#                           ; Create a connector of the given name in
+#                           ; the current rubysync configuration directory
+#                         
+#   * fields {name}           ; list the fields detected by the named connector
+# 
+#   * pipeline {name}         ; Create a rubysync pipeline of the given name
+#                           ; in the current rubysync configuration directory
+#                         
+#   * once {name}::             
+#       Execute the named pipeline within the current configuration directory once and then exit
+#                         
+#   * example::          Show an example of how this command might be used
+# 
+# == Example
+# 
+#   This sets up the skeleton of a configuration for importing comma delimeted
+#   text files into an xml file.
+#     <tt>
+#     $ rubysync create xml_demo
+#     $ cd xml_demo
+#     $ rubysync connector my_csv -t csv_file
+#     $ rubysync connector my_xml -t xml
+#     </tt>
+#   
+#   You would then edit the files::
+# 
+#     * +connectors/my_csv_connector.rb+:: where to get the CSV files, field names, etc
+#     * +connectors/my_xml_connector.rb+::  how to connect to your XML file.
+# 
+#   And enter::
+#     <tt>
+#     $ rubysync pipeline my_pipeline -C my_csv -V my_xml
+#     </tt>
+# 
+#   You would then edit the file +pipelines/my_pipeline.rb+ to configure the
+#   policy for synchronizing between the two connectors.
+#                                         
+#   You may then execute the pipeline in one-shot mode (daemon mode is coming)::
+# 
+#     <tt>
+#     $ rubysync once my_pipeline
+#     </tt>
+# 
+# == Author
+#   Ritchie Young, 9 to 5 Magic (http://9to5magic.com.au)
+#  
+# == Copyright
+#   Copyright (c) 2007 Ritchie Young. All rights reserved.
+# 
+# This file is part of RubySync.
+# 
+# RubySync is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
+# 
+# RubySync is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+# warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along with RubySync; if not, write to the
+# Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
 
 
 lib_path = File.dirname(__FILE__) + '/../lib'
@@ -87,12 +87,15 @@ class Controller < SimpleConsole::Controller
 
   before_filter :configure_logging
   
-  params :string => {:p => :pipe,
-                     :t => :type,
-                     :V => :vault,
-                     :C => :client},
-         :int =>{:v => :verbose,
-	 	:d => :delay}
+  params(
+    :int =>{:v => :verbose, :d => :delay},
+    :string => {:p => :pipe,
+      :t => :type,
+      :V => :vault,
+      :C => :client}, 
+    :bool =>{:n => :no_edit}
+  )
+  
 
   def default
     #RDoc::usage 'Usage'
@@ -124,36 +127,41 @@ class Controller < SimpleConsole::Controller
     end
   end
 
-
-
   # Create a Rubysync project directory
   def create
     config_path = params[:id]
     ensure_dir_exists([
-      config_path,
-      "#{config_path}/pipelines",
-      "#{config_path}/connectors",
-      "#{config_path}/shared",
-      "#{config_path}/shared/pipelines",
-      "#{config_path}/shared/connectors",
-      "#{config_path}/shared/lib",
-      "#{config_path}/log",
-      "#{config_path}/db"
-    ])
+	config_path,
+	"#{config_path}/pipelines",
+	"#{config_path}/connectors",
+	"#{config_path}/shared",
+	"#{config_path}/shared/pipelines",
+	"#{config_path}/shared/connectors",
+	"#{config_path}/shared/lib",
+	"#{config_path}/log",
+	"#{config_path}/db"
+      ])
   end
   
   # Create a connector configuration file
   def connector
     name = params[:id]
     type = params[:type]
-    unless name and type
-      puts "Usage: rubysync connector connector_name -t connector_type"
+    unless name
+      puts "Usage: rubysync connector connector_name [-t connector_type]"
       return
     end
-    if base_path
-      File.open("#{base_path}/connectors/#{name}_connector.rb", "w") do |file|
-        file.puts connector_template(name, type)
+    if base_path 
+      filename = "#{base_path}/connectors/#{name}_connector.rb"
+      unless File.exists?(filename)
+	puts "Require -t connector_type when creating a connector" unless type
+	if template = connector_template(name, type)
+	  File.open(filename, "w") do |file|
+	    file.puts template
+	  end
+	end
       end
+      edit filename
     else
       puts 'Change into a config dir and try again or create a config dir with "rubysync create"'
     end
@@ -167,6 +175,31 @@ class Controller < SimpleConsole::Controller
     @field_names = connector && connector.fields || []
   end
   
+  def show
+    params[:id] =~ /(.+?)\[(.+?)\]/o
+    connector_name = $1
+    path = $2
+    unless connector_name and path
+      puts "Usage: rubysync show connector[path]"
+    else
+      connector = connector_called(connector_name)
+      if connector 
+	unless connector.respond_to?(:'[]')
+	  puts "Connector '#{connector_name}' doesnt support random access."
+	else
+	  connector.started
+	  value = connector[path]
+	  connector.stopped
+	  unless value
+	    puts "Path '#{path}' not found in connector '#{connector_name}'"
+	  else
+	    puts value.to_yaml
+	  end
+	end
+      end
+    end
+  end
+
   def pipeline
     name = params[:id]
     vault_name = params[:vault]
@@ -176,9 +209,15 @@ class Controller < SimpleConsole::Controller
       return
     end
     if base_path
-      File.open("#{base_path}/pipelines/#{name}_pipeline.rb", "w") do |file|
-        file.puts pipeline_template(name, vault_name, client_name)
+      filename = "#{base_path}/pipelines/#{name}_pipeline.rb"
+      unless File.exists?(filename)
+	if template = pipeline_template(name, vault_name, client_name)
+	  File.open(filename, "w") do |file|
+	    file.puts template
+	  end
+        end
       end
+      edit filename
     else
       puts 'Change into a config dir and try again or create a config dir with "rubysync create"'
     end
@@ -187,7 +226,17 @@ class Controller < SimpleConsole::Controller
   
   
   private
-  
+
+  def edit filename
+    unless params[:no_edit]
+      if ENV['EDITOR']
+	exec "#{ENV['EDITOR']} #{filename}"
+      else
+	log.warn "Set the EDITOR environment variable to enable automatic editing of config files."
+      end
+    end
+  end
+
   def configure_logging
     log_levels = [::Logger::WARN, ::Logger::INFO, ::Logger::DEBUG]
     verbosity = [(params[:verbose]||0), log_levels.size-1].min
@@ -200,8 +249,8 @@ end
 class View < SimpleConsole::View
 
 
-def default
-puts <<"END"
+  def default
+    puts <<"END"
 Usage:
   
     rubysync command name [options]
@@ -222,16 +271,20 @@ Usage:
                           ; Execute the named pipeline within the current
                           ; configuration directory once and then exit
                           
+  * show {name}[{path}]	  ; Display the entry at path for connector specified
+                          ; name
+
   * start {name}          ; Execute the named pipeline
                         
   * example               ; Show an example of how this command might be used
 
+
 END
-end
+  end
 
 
-def example
-puts <<"END"
+  def example
+    puts <<"END"
   This sets up the skeleton of a configuration for importing comma delimeted
   text files into an XML file.
 
@@ -259,101 +312,138 @@ puts <<"END"
   
     $ rubysync start my
 END
-end
+  end
 
-def fields
-  puts @field_names.join("\n")
-end
+  def fields
+    puts @field_names.join("\n")
+  end
 
 end
 
 
-  def connector_template name, type
-    type_class_name = "RubySync::Connectors::#{type.to_s.camelize}Connector"
-    type_class = eval(type_class_name)
-    sample_config = (type_class && type_class.respond_to?("sample_config")) ?
-      type_class.sample_config : ""
-    return <<-"end;"
-class #{name.to_s.camelize}Connector < #{type_class_name}
+def connector_template name, type
+  return unless type_class = class_for_name("RubySync::Connectors::#{class_name_for type, 'connector'}")
+  sample_config = (type_class && type_class.respond_to?("sample_config")) ?
+    type_class.sample_config : ""
+  return <<-"end;"
+class #{class_name_for(name, 'connector')} < #{type_class.name}
   #{sample_config}
 end
-    end;
-  end
+  end;
+end
 
   
-  def pipeline_template name, vault_name, client_name
-    vault = (vault_name)? ::RubySync::Connectors::BaseConnector.class_for(vault_name) : nil
-    vault_fields = vault && vault.fields || []
+def pipeline_template name, vault_name, client_name
+  vault = (vault_name)? class_for_name("RubySync::Connectors::#{class_name_for vault_name, 'connector'}") : nil
+  vault_fields = vault && vault.fields || []
 
-    client = (client_name)? ::RubySync::Connectors::BaseConnector.class_for(client_name) : nil
-    client_fields = client && client.fields || []
+  client = (client_name)? class_for_name("RubySync::Connectors::#{class_name_for client_name, 'connector'}") : nil
+  client_fields = client && client.fields || []
 
-    vault_specifier = (vault_name)? "vault :#{vault_name}" : "#vault :vault_connector_name"
-    client_specifier = (client_name)? "client :#{client_name}" : "#client :client_connector_name"
-    return <<-"end;"
+  return nil if vault_name && !vault or client_name && !client
+
+  vault_specifier = (vault_name)? "vault :#{vault_name}" : "#vault :vault_connector_name"
+  client_specifier = (client_name)? "client :#{client_name}" : "#client :client_connector_name"
+  return <<-"end;"
 class #{name.to_s.camelize}Pipeline < RubySync::Pipelines::BasePipeline
 
   #{client_specifier}
 
   #{vault_specifier}
 
-  # Remove any fields that you don't want to set in the client from the vault
-  allow_out #{allow_through(vault_fields)}
-
-  # Remove any fields that you don't want to set in the vault from the client
+ # Remove any client fields that have no bearing on the final entry in the vault.
   allow_in #{allow_through(client_fields)}
 
+  # "in" means going from client to vault
   # If the client and vault have different names for the same field, define the
-  # the mapping here. For example, if the vault has a field called "first name" and
-  # the client has a field called givenName you may put:
+  # the mapping here. For example, if the vault has a field called "first name" 
+  # and the client has a field called 'givenName' you may write:
+  #
   #    map 'first name', 'givenName'
   #
-  # You can also calculate the values for fields. For more info, see
+  # You can also calculate the values for fields. If the vault has a 'fullname'
+  # and the client has 'givenName' and 'surname' attributes. You might write:
+  #
+  #    map(:fullname) {value_of(:givenName) + " " + value_of(:surname) }
+  #
+  # For more info, see
   # http://rubysync.org/docs/rubysync-transformations/
-  
-  # "in" means going from client to vault
-  in_transform do
+  in_event_transform do
     #{transform_fields(vault_fields, 'vault', 'client')}
   end
 
-  # "out" means going from vault to client
-  out_transform do
-    #{transform_fields(client_fields, 'client', 'vault')}
-  end
-
+  # if the record has been successfully synchronized already, RubySync will
+  # already know about the association and will skip ahead to
+  # in_command_transform.
+  # 
   # if the vault doesn't already hold an association for this record
   # from the client, perform a search here to see if a match can be found
+  # and if so, return its path.
+  # Default behaviour is to attempt to use the value returned by in_place.
   # in_match do
   # end
 
+  # If there was exactly one match, RubySync records the association and skips
+  # ahead to in_command_transform. Otherwise it considers creating the entry in
+  # the vault.
+
+  # If in_create evaluates to false, it will veto the creation of a record on
+  # the vault. This is good for checking you've got the required fields or only
+  # creating a subset of the possible records.
+  # in_create do
+  #   #eg only create entries with a (somewhat) valid email address
+  #   value_of(:email) =~ /%w+@%w+\.%w+/   
+  # end
+
+  # Should evaluate to the path for placing a new record in the vault
+  # in_place do
+  #   value_of(:vault_path_field)
+  # end
+
+  # in_command_transform is the same as in_event_transform but occurs after
+  # any in_match, in_create or in_place invocations.
+  # in_command_transform  do
+  #  drop_changes_to :any, :fields, :you, :dont, :want, :in, :the, :vault
+  # end
+
+
+  # End of client to vault processing
+  # -----------------------------------
+  # Start of vault to client processing
+
+ # Remove any client fields that have no bearing on the final entry in the client.
+  allow_out #{allow_through(vault_fields)}
+
+ 
+  # "out" means going from vault to client
+  # See comment for in_event_transform above
+  out_event_transform do
+    #{transform_fields(client_fields, 'client', 'vault')}
+  end
+
   # if the vault doesn't have an association linking this record to one on
   # the client, perform a search here to see if an existing client record
   # matches this record
   # out_match do
   # end
 
-  # If this evaluates to false, it will veto the creation of a record on
-  # the vault. Good for checking you've got the required fields etc
-  # in_create_if do
-  # end
-
-  # if this evaluates to false for an outgoing event then it will
+   # if this evaluates to false for an outgoing event then it will
   # veto the creation of a new record on the client
-  # out_create_if do
-  # end
-
-  # Should evaluate to the path for placing a new record on the vault
-  # in_place do
+  # out_create do
   # end
 
-  # Should evaluate to the path for placing a new record on the client
+ # Should evaluate to the path for placing a new record on the client
   # out_place do
   # end
 
+  # See comment for in_command_transform above
+  out_command_transform do
+  #  drop_changes_to :any, :fields, :you, :dont, :want, :in, :the, :client
+  end
 
 end
-    end;
-  end
+  end;
+end
 
 def allow_through fields
   (fields.empty? ? %w{allow these fields through} : fields).to_ruby