athena 0.2.1 → 0.2.2

data/README

@@ -2,12 +2,22 @@
 
 == VERSION
 
-This documentation refers to athena version 0.2.1
+This documentation refers to athena version 0.2.2
 
 
 == DESCRIPTION
 
-TODO: well, the description... ;-)
+Athena is a library to convert "database" files between various formats.
+It's accompanied by a corresponding executable that gives access to its
+converting features from the command-line. See Athena::Formats for the
+supported database formats and how you can add your own.
+
+=== Plugins
+
+Athena has a plugin system that allows you to implement additional database
+formats and have them available easily. Just create a file +athena_plugin.rb+
+(Athena::PLUGIN_FILENAME) in your Gem's +lib+ directory or any directory that's
+placed in <tt>$LOAD_PATH</tt>. See Athena::Formats on how to define custom formats.
 
 
 == LINKS

data/Rakefile

@@ -14,7 +14,7 @@ begin
       :summary      => %q{Convert database files to various formats.},
       :author       => %q{Jens Wille},
       :email        => %q{jens.wille@uni-koeln.de},
-      :dependencies => %w[builder xmlstreamin] << ['ruby-nuggets', '>= 0.7.4']
+      :dependencies => %w[builder xmlstreamin] << ['ruby-nuggets', '>= 0.8.1']
     }
   }}
 rescue LoadError => err

data/bin/athena

@@ -1,4 +1,4 @@
-#! /usr/bin/ruby
+#! /usr/bin/env ruby
 
 #--
 ###############################################################################

data/example/athena_plugin.rb

@@ -0,0 +1,13 @@
+class Bla < Athena::Formats::Base
+
+  def parse
+    # ...
+  end
+
+  def convert
+    # ...
+  end
+
+  register_format :blub
+
+end

data/lib/athena.rb

@@ -26,55 +26,83 @@
 ###############################################################################
 #++
 
-# Athena is a library to convert (mainly) prometheus database files to various
-# output formats. It's accompanied by a corresponding script that gives access
-# to all its converting features.
-#
-# In order to support additional input and/or output formats, Athena::Formats::Base
-# needs to be sub-classed and, respectively, an instance method _parse_ or an
-# instance method _convert_ supplied. This way, a specific format can even function
-# as both input and output format.
-
 require 'athena/version'
 
+# See README.
+
 module Athena
 
-  autoload :Parser,  'athena/parser'
   autoload :Record,  'athena/record'
   autoload :Formats, 'athena/formats'
 
   extend self
 
-  def parser(config, format)
-    Parser.new(config, format)
-  end
+  DEFAULT_SEPARATOR = ', '
+  DEFAULT_EMPTY     = '<<EMPTY>>'
 
-  def input_formats
-    Formats::Base.formats[:in].sort
+  def run(config, spec, format, input, output)
+    Formats[:out, format, output].run(
+      Formats[:in, spec, build_config(config)],
+      input
+    )
   end
 
-  def valid_input_format?(format)
-    Formats::Base.valid_format?(:in, format)
+  def input_formats
+    Formats.formats[:in].sort
   end
 
   def output_formats
-    Formats::Base.formats[:out].sort
+    Formats.formats[:out].sort
   end
 
-  def valid_output_format?(format)
-    Formats::Base.valid_format?(:out, format)
+  def valid_format?(direction, format)
+    Formats.valid_format?(direction, format)
   end
 
-  def deferred_output?(format)
-    Formats[:out, format].deferred?
+  def valid_input_format?(format)
+    valid_format?(:in, format)
   end
 
-  def raw_output?(format)
-    Formats[:out, format].raw?
+  def valid_output_format?(format)
+    valid_format?(:out, format)
   end
 
-  def with_format(format, *args, &block)
-    Formats[:out, format].wrap(*args, &block)
+  private
+
+  def build_config(config)
+    hash = {}
+
+    config.each { |field, value|
+      if field.to_s =~ /\A__/
+        hash[field] = value
+      else
+        case value
+          when String, Array
+            elements, value = [*value], {}
+          when Hash
+            elements = value[:elements] || value[:element].to_a
+
+            raise ArgumentError, "no elements specified for field #{field}" unless elements.is_a?(Array)
+          else
+            raise ArgumentError, "illegal value for field #{field}"
+        end
+
+        separator = value[:separator] || DEFAULT_SEPARATOR
+
+        elements.each { |element|
+          (hash[element] ||= {})[field] = {
+            :string   => value[:string] || ['%s'] * elements.size * separator,
+            :empty    => value[:empty]  || DEFAULT_EMPTY,
+            :elements => elements
+          }
+        }
+      end
+    }
+
+    hash
   end
 
 end
+
+require 'nuggets/util/pluggable'
+Util::Pluggable.load_plugins_for(Athena)

data/lib/athena/cli.rb

@@ -63,42 +63,18 @@ module Athena
         }.reverse.find { |t| config[target = t.to_sym] }
       end or abort "Config not found for target: #{target}."
 
-      parser = Athena.parser(target_config, spec)
-
       input = options[:input]
       input = arguments.shift unless input != defaults[:input] || arguments.empty?
-      options[:input] = File.directory?(input) ? Dir.open(input) : open_file_or_std(input)
+      input = File.directory?(input) ? Dir.open(input) : open_file_or_std(input)
 
       quit unless arguments.empty?
 
-      options[:output] = open_file_or_std(options[:output], true)
-
-      if Athena.deferred_output?(format)
-        res = parser.parse(options[:input])
-
-        res.map { |record|
-          record.to(format)
-        }.flatten.sort.uniq.each { |line|
-          options[:output].puts line
-        }
-      elsif Athena.raw_output?(format)
-        res = Athena.with_format(format, options[:output]) { |_format|
-          parser.parse(options[:input]) { |record|
-            record.to(_format)
-          }
-        }
-      else
-        res = Athena.with_format(format) { |_format|
-          parser.parse(options[:input]) { |record|
-            options[:output].puts record.to(_format)
-          }
-        }
-      end
+      Athena.run(target_config, spec, format, input, open_file_or_std(options[:output], true))
     end
 
     private
 
-    def merge_config(args = [default])
+    def merge_config(args = [defaults])
       super
     end
 
@@ -124,13 +100,7 @@ module Athena
       }
 
       opts.on('-L', '--list-specs', "List available input formats (specs) and exit") {
-        puts 'Available input formats (specs):'
-
-        Athena.input_formats.each { |format, name|
-          puts "  - #{format}#{" (= #{name})" if format != name.to_s}"
-        }
-
-        exit
+        print_formats(:in)
       }
 
       opts.separator ''
@@ -145,13 +115,7 @@ module Athena
       }
 
       opts.on('-l', '--list-formats', "List available output formats and exit") {
-        puts 'Available output formats:'
-
-        Athena.output_formats.each { |format, name|
-          puts "  - #{format}#{" (= #{name})" if format != name.to_s}"
-        }
-
-        exit
+        print_formats(:out)
       }
 
       opts.separator ''
@@ -161,6 +125,19 @@ module Athena
       }
     end
 
+    def print_formats(direction)
+      puts "Available #{direction}put formats:"
+
+      Athena.send("#{direction}put_formats").each { |name, klass|
+        line, format = "  - #{name}", klass.format
+        line << " (= #{format})" if name != format && Athena.valid_format?(direction, format)
+
+        puts line
+      }
+
+      exit
+    end
+
   end
 
 end

data/lib/athena/formats.rb

@@ -30,108 +30,416 @@ require 'athena'
 
 module Athena
 
+  # In order to support additional input and/or output formats,
+  # Athena::Formats::Base needs to be sub-classed and an instance
+  # method _parse_ or an instance method _convert_ supplied,
+  # respectively. This way, a specific format can even function
+  # as both input and output format.
+  #
+  # == Defining custom formats
+  #
+  # Define one or more classes that inherit from Athena::Formats::Base
+  # and either call Athena::Formats.register with your format class as
+  # parameter or call Athena::Formats.register_all with your surrounding
+  # namespace (which will then recursively add any format definitions below
+  # it). Alternatively, you can call Athena::Formats::Base.register_format
+  # <b>at the end</b> of your class definition to register just this class.
+  #
+  # The directions supported by your custom format are determined
+  # automatically; see below for further details.
+  #
+  # === Defining an _input_ format
+  #
+  # An input format must provide a *public* instance method _parse_ that
+  # accepts an input object (usually an IO object) and a block it passes
+  # each record (Athena::Record) to. See Athena::Formats::Base#parse.
+  #
+  # === Defining an _output_ format
+  #
+  # An output format must provide a *public* instance method _convert_ that
+  # accepts a record (Athena::Record) and either returns a suitable value for
+  # output or writes the output itself. See Athena::Formats::Base#convert.
+  #
+  # == Aliases
+  #
+  # In order to provide an alias name for a format, simply assign
+  # the format class to a new constant. Then you need to call
+  # <tt>Athena::Formats.register(your_new_const)</tt> to register
+  # your alias.
+
   module Formats
 
-    CRLF    = %Q{\015\012}
+    # CR+LF line ending.
+    CRLF = %Q{\015\012}
+
+    # Regular expression to match (multiple) CR+LF line endings.
     CRLF_RE = %r{(?:\r?\n)+}
 
-    def self.[](direction, format)
-      if direction == :out
-        if format.class < Base
-          if format.class.direction != direction
-            raise DirectionMismatchError,
-              "expected #{direction}, got #{format.class.direction}"
+    # Mapping of format direction to method required for implementation.
+    METHODS = { :in => 'parse', :out => 'convert' }
+
+    @formats = { :in => {}, :out => {} }
+
+    class << self
+
+      # Container for registered formats per direction. Use ::find or ::[]
+      # to access them.
+      attr_reader :formats
+
+      # call-seq:
+      #   Athena::Formats[direction, format, *args] -> aFormat
+      #
+      # Retrieves the format for +direction+ by its name +format+ (see
+      # ::find) and initializes it with +args+ (see Base#init). Returns
+      # +format+ unaltered if it already is a format instance, while
+      # making sure that it supports +direction+.
+      def [](direction, format, *args)
+        res = find(direction, format, true)
+        res.is_a?(Base) ? res : res.init(direction, *args)
+      end
+
+      # call-seq:
+      #   Athena::Formats.find(direction, format) -> aFormatClass
+      #
+      # Retrieves the format for +direction+ by its name +format+. Returns
+      # +format+'s class if it already is a format instance, while making
+      # sure that it supports +direction+.
+      def find(direction, format, instance = false)
+        directions = formats.keys
+
+        unless directions.include?(direction)
+          raise ArgumentError, "invalid direction: #{direction.inspect}" <<
+            " (must be one of: #{directions.map { |d| d.inspect }.join(', ')})"
+        end
+
+        case format
+          when Symbol
+            find(direction, format.to_s)
+          when String
+            formats[direction][format] or
+              raise FormatNotFoundError.new(direction, format)
           else
-            format
-          end
+            klass = format.class
+
+            if klass < Base && !(directions = klass.directions).empty?
+              if klass.has_direction?(direction)
+                return instance ? format : klass
+              else
+                raise DirectionMismatchError.new(direction, directions)
+              end
+            else
+              raise ArgumentError, "invalid format of type #{klass}" <<
+                " (expected one of: Symbol, String, or sub-class of #{Base})"
+            end
+        end
+      end
+
+      # call-seq:
+      #   Athena::Formats.valid_format?(direction, format) -> true | false
+      #
+      # Indicates whether the +direction+/+format+ combination is supported,
+      # i.e. a format by name +format+ has been registered and supports
+      # +direction+.
+      def valid_format?(direction, format)
+        if format.class < Base
+          format.class.has_direction?(direction)
         else
-          Base.formats[direction][format].new
+          formats[direction].has_key?(format.to_s)
+        end
+      end
+
+      # call-seq:
+      #   Athena::Formats.register(klass, name = nil, relax = false) -> anArray | nil
+      #
+      # Registers +klass+ as format under +name+ (defaults to Base.format).
+      # Only warns instead of raising any errors when +relax+ is +true+.
+      # Returns an array of the actual name +klass+ has been registered
+      # under and the directions supported; returns +nil+ if nothing has
+      # been registered.
+      def register(klass, name = nil, relax = false)
+        unless klass < Base
+          return if relax
+          raise ArgumentError, "must be a sub-class of #{Base}"
         end
-      else
-        Base.formats[direction][format]
+
+        name = name ? name.to_s : klass.format
+        methods = klass.public_instance_methods(false).map { |m| m.to_s }
+        directions = klass.directions
+
+        METHODS.each { |direction, method|
+          next unless methods.include?(method)
+
+          if formats[direction].has_key?(name)
+            err = DuplicateFormatDefinitionError.new(direction, name)
+            raise err unless relax
+
+            warn err
+            next
+          else
+            directions << direction unless klass.has_direction?(direction)
+            formats[direction][name] = klass
+          end
+        }
+
+        [name, directions] unless directions.empty?
+      end
+
+      # call-seq:
+      #   Athena::Formats.register_all(klass = self) -> anArray
+      #
+      # Recursively registers all formats *below* +klass+ (see ::register).
+      # Returns an array of all registered format names with their supported
+      # directions.
+      def register_all(klass = self, registered = [])
+        names  = klass.constants
+        names -= klass.superclass.constants if klass.is_a?(Class)
+
+        names.each { |name|
+          const = klass.const_get(name)
+          next unless const.is_a?(Module)
+
+          registered << register(const, format_name("#{klass}::#{name}"), true)
+          register_all(const, registered)
+        }
+
+        registered.compact
+      end
+
+      protected
+
+      # call-seq:
+      #   Athena::Formats.format_name(name) -> aString
+      #
+      # Formats +name+ as suitable format name.
+      def format_name(fn)
+        fn.sub(/\A#{self}::/, '').
+          gsub(/([a-z\d])(?=[A-Z])/, '\1_').
+          gsub(/::/, '/').downcase
       end
+
     end
 
-    class Base
+    # Base class for all format classes. See Athena::Formats
+    # for more information.
 
-      @formats = { :in => {}, :out => {} }
+    class Base
 
       class << self
 
-        def formats
-          Base.instance_variable_get(:@formats)
+        # call-seq:
+        #   Athena::Formats::Base.format -> aString
+        #
+        # Returns this class's format name.
+        def format
+          @format ||= Formats.format_name(name)
         end
 
-        def valid_format?(direction, format)
-          if format.class < Base
-            direction == format.class.direction
-          else
-            formats[direction].has_key?(format)
-          end
+        # call-seq:
+        #   Athena::Formats::Base.directions -> anArray
+        #
+        # Returns an array of the directions supported by this class.
+        def directions
+          @directions ||= []
+        end
+
+        # call-seq:
+        #   Athena::Formats::Base.has_direction?(direction) -> true | false
+        #
+        # Indicates whether this class supports +direction+.
+        def has_direction?(direction)
+          directions.include?(direction)
         end
 
-        private
+        # call-seq:
+        #   Athena::Formats::Base.init(direction, *args) -> aFormat
+        #
+        # Returns a new instance of this class for +direction+ initialized
+        # with +args+ (see #init).
+        def init(direction, *args)
+          new.init(direction, *args)
+        end
 
-        def register_format(direction, *aliases, &block)
-          format = name.split('::').last.
-            gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
-            gsub(/([a-z\d])([A-Z])/, '\1_\2').
-            downcase
+        protected
 
-          register_format!(direction, format, *aliases, &block)
+        # call-seq:
+        #   Athena::Formats::Base.register_format(name = nil, relax = false) -> anArray | nil
+        #
+        # Shortcut for <tt>Athena::Formats.register(self, name, relax)</tt>.
+        # Must be called at the end of or after the class definition (in order
+        # to determine the supported direction(s), the relevant instance
+        # methods must be available).
+        def register_format(name = nil, relax = false)
+          Formats.register(self, name, relax)
         end
 
-        def register_format!(direction, format, *aliases, &block)
-          raise "must be a sub-class of #{Base}" unless self < Base
+      end
+
+      # The _input_ format's configuration hash.
+      attr_reader :config
 
-          klass = Class.new(self, &block)
+      # The _input_ format's "record element" (interpreted
+      # differently by each format).
+      attr_reader :record_element
 
-          klass.instance_eval %Q{
-            def direction; #{direction.inspect}; end
-            def name; '#{format}::#{direction}'; end
-            def to_s; '#{format}'; end
-          }
+      # The _output_ format's output target.
+      attr_reader :output
 
-          [format, *aliases].each { |name|
-            if existing = formats[direction][name]
-              raise DuplicateFormatDefinitionError,
-                "format already defined (#{direction}): #{name}"
-            else
-              formats[direction][name] = klass
-            end
-          }
+      # call-seq:
+      #   format.init(direction, *args) -> format
+      #
+      # Initializes _format_ for +direction+ with +args+ (see #init_in and
+      # #init_out), while making sure that +direction+ is actually supported
+      # by _format_. Returns _format_.
+      def init(direction, *args)
+        if self.class.has_direction?(direction)
+          send("init_#{direction}", *args)
+        else
+          raise DirectionMismatchError.new(direction, self.class.directions)
         end
 
+        self
       end
 
-      def parse(*args)
+      # call-seq:
+      #   format.parse(input) { |record| ... } -> anInteger
+      #
+      # Parses +input+ according to the format represented by this class
+      # and passes each record to the block. _Should_ return the number of
+      # records parsed.
+      #
+      # NOTE: Must be implemented by the sub-class in order to function as
+      # _input_ format.
+      def parse(input)
         raise NotImplementedError, 'must be defined by sub-class'
       end
 
+      # call-seq:
+      #   format.convert(record) -> aString | anArray | void
+      #
+      # Converts +record+ (Athena::Record) according to the format represented
+      # by this class. The return value may be different for each class; it is
+      # irrelevant when #raw? has been defined as +true+.
+      #
+      # NOTE: Must be implemented by the sub-class in order to function as
+      # _output_ format.
       def convert(record)
         raise NotImplementedError, 'must be defined by sub-class'
       end
 
-      def wrap
-        yield self
+      # call-seq:
+      #   format.raw? -> true | false
+      #
+      # Indicates whether output is written directly in #convert.
+      def raw?
+        false
       end
 
+      # call-seq:
+      #   format.deferred? -> true | false
+      #
+      # Indicates whether output is to be deferred and only be written after
+      # all records have been converted (see #run).
       def deferred?
         false
       end
 
-      def raw?
-        false
+      # call-seq:
+      #   format.run(spec, input) -> anInteger
+      #
+      # Runs the _output_ generation for _input_ format +spec+ (Athena::Formats::Base)
+      # on +input+. Outputs a sorted and unique list of records when #deferred?
+      # is +true+. Returns the return value of #parse.
+      def run(spec, input)
+        parsed, block = nil, if raw?
+          lambda { |record| record.to(self) }
+        elsif deferred?
+          deferred = []
+          lambda { |record| deferred << record.to(self) }
+        else
+          lambda { |record| output.puts(record.to(self)) }
+        end
+
+        wrap { parsed = spec.parse(input, &block) }
+
+        if deferred?
+          deferred.flatten!; deferred.sort!; deferred.uniq!
+          output.puts(deferred)
+        end
+
+        parsed
+      end
+
+      private
+
+      # call-seq:
+      #   format.init_in(config)
+      #
+      # Initialize _input_ format (with +config+).
+      def init_in(config)
+        @config = config
+
+        case @record_element = @config.delete(:__record_element)
+          when *@__record_element_ok__ || String
+            # fine!
+          when nil
+            raise NoRecordElementError, 'no record element specified'
+          else
+            raise IllegalRecordElementError, "illegal record element #{@record_element.inspect}"
+        end
+      end
+
+      # call-seq:
+      #   format.init_out(output = nil)
+      #
+      # Initialize _output_ format (with optional +output+).
+      def init_out(output = nil)
+        @output = output
+      end
+
+      # call-seq:
+      #   format.wrap { ... }
+      #
+      # Hook for wrapping the output generation in #run.
+      def wrap
+        yield
       end
 
     end
 
     class FormatError < StandardError; end
 
-    class DuplicateFormatDefinitionError < FormatError; end
-    class DirectionMismatchError         < FormatError; end
+    class DuplicateFormatDefinitionError < FormatError
+      def initialize(direction, format)
+        @direction, @format = direction, format
+      end
+
+      def to_s
+        "format already defined (#{@direction.inspect}): #{@format.inspect}"
+      end
+    end
+
+    class FormatNotFoundError < FormatError
+      def initialize(direction, format)
+        @direction, @format = direction, format
+      end
+
+      def to_s
+        "format not found (#{@direction.inspect}): #{@format.inspect}"
+      end
+    end
 
-    ConfigError = Parser::ConfigError
+    class DirectionMismatchError < FormatError
+      def initialize(direction, directions)
+        @direction, @directions = direction, directions
+      end
+
+      def to_s
+        "got #{@direction.inspect}, expected one of " <<
+          @directions.map { |d| d.inspect }.join(', ')
+      end
+    end
+
+    class ConfigError < StandardError; end
 
     class NoRecordElementError      < ConfigError; end
     class IllegalRecordElementError < ConfigError; end
@@ -143,3 +451,5 @@ end
 Dir[__FILE__.sub(/\.rb\z/, '/**/*.rb')].sort.each { |rb|
   require "athena/formats/#{File.basename(rb, '.rb')}"
 }
+
+Athena::Formats.register_all