imw 0.2.18 → 0.3.0

data/lib/imw/formats/yaml.rb

@@ -1,41 +0,0 @@
-module IMW
-  module Formats
-
-    # Provides methods for reading and writing YAML data.
-    module Yaml
-
-      include Enumerable
-
-      # Return the content of this resource.
-      #
-      # Will pass a block to the outermost YAML data structure's each
-      # method.
-      #
-      # @return [Hash, Array, String, Fixnum] whatever the YAML contained
-      def load &block
-        require 'yaml'
-        yaml = YAML.load(io)
-        if block_given?
-          yaml.each(&block)
-        else
-          yaml
-        end
-      end
-
-      # Iterate over the elements in the YAML.
-      def each &block
-        load(&block)
-      end
-      
-      # Emit the +data+ into this resource.  It must be opened for
-      # writing.
-      #
-      # @param [Hash, String, Array, Fixnum] data the Ruby object to emit
-      def emit data, options={}
-        require 'yaml'
-        write(data.to_yaml)
-        self
-      end
-    end
-  end
-end

data/lib/imw/metadata.rb

@@ -1,83 +0,0 @@
-module IMW
-
-  # A collection of classes for describing the metadata associated
-  # with a dataset's fields.
-  class Metadata < Hash
-    
-    autoload :Field,            'imw/metadata/field'
-    autoload :Schema,           'imw/metadata/schema'
-    autoload :ContainsMetadata, 'imw/metadata/contains_metadata'
-    autoload :HasSummary,       'imw/metadata/has_summary'
-    autoload :HasMetadata,      'imw/metadata/has_metadata'
-
-    # The resource this metadata is anchored to.
-    #
-    # This attribute is useful for letting relative paths in a
-    # schema file refer to a common base URL.
-    #
-    # @return [IMW::Resource]
-    attr_reader :base
-    
-    # Set the base resource this metdata is anchored to.
-    #
-    # @param [IMW::Resource, String, Addressable::URI] new_base
-    def base= new_base
-      base_resource = IMW.open(new_base)
-      base_resource.should_exist!("Metadata base directory must exist")
-      raise IMW::PathError.new("Metadata base must be a directory") unless base_resource.is_directory?
-      @base = base_resource
-    end
-
-    def initialize obj=nil, options={}
-      super()
-      self.base = options[:base] if options[:base]
-      if obj
-        obj.each_pair do |resource, metadata|
-          self[resource] = metadata
-        end
-      end
-    end
-
-    def self.load obj, options={}
-      resource = IMW.open(obj)
-      new(resource.load, {:base => resource.dirname}.merge(options))
-    end
-
-    def []= resource, metadata
-      super(absolute_uri(resource), metadata)
-    end
-
-    def [] resource
-      super(absolute_uri(resource))
-    end
-
-    def describe? resource
-      self[(absolute_uri(resource))]
-    end
-    alias_method :describes?, :describe?
-
-    def description_for resource
-      return unless describes?(resource)
-      self[resource]['description']
-    end
-
-    def fields_for resource
-      return unless describes?(resource)
-      (self[resource]['fields'] || []).map { |f| Metadata::Field.new(f) }
-    end
-
-    protected
-
-    def absolute_uri resource
-      obj = IMW.open(resource)
-      if base && obj.uri.to_s !~ %r{(^/|://)} # relative path
-        s = base.join(obj.uri.to_s).uri.to_s
-        s
-      else
-        s = obj.uri.to_s
-        s
-      end
-    end
-    
-  end
-end

data/lib/imw/metadata/contains_metadata.rb

@@ -1,54 +0,0 @@
- module IMW
-  class Metadata
-
-    # A module for finding metadata describing the sub-resources of a
-    # given resource.
-    #
-    # An including class describing the parent resource must define
-    # the +contents+ method which must return an Array of Strings
-    # contained within the parent .  These objects will be matched
-    # against possible metadata URIs and the corresponding
-    # IMW::Metadata class created on the fly.
-    #
-    # In case no such object is found, the class should also define
-    # the +basename+ and +path+ methods which will be used to generate
-    # a default URI where metadata about the parent's resources should
-    # live.
-    module ContainsMetadata
-      
-      # The URI containing the metadata for this resource and its
-      # contents.
-      #
-      # Looks for an existing JSON or YAML file containing the strings
-      # "icss" or "metadata" directly contained within this resource.
-      #
-      # If none are found, defaults to a URI named after this
-      # resource's basename with the string ".icss.yaml" appended.
-      #
-      # @return [String, nil]
-      def default_metadata_uri
-        contents.detect { |path| path =~ /metadata.*\.(ya?ml|json)$/i } || File.join(path, "#{basename}.metadata.yaml")
-      end
-
-      # Return the metadata for this resource if it exists.
-      #
-      # Will look for an existing resource at +default_metadata_uri+.
-      #
-      # @return [IMW::Metadata, nil]
-      def metadata
-        return @metadata if @metadata
-        obj = IMW.open(default_metadata_uri)
-        self.metadata=(obj) if obj.exist?
-        @metadata
-      end
-
-      # Set the metadata for this resource to +obj+.
-      #
-      # @param [String, Addressable::URI, IMW::Resource] obj
-      def metadata= obj
-        @metadata = IMW::Metadata.load(obj)
-      end
-      
-    end
-  end
-end

data/lib/imw/metadata/dsl.rb

@@ -1,111 +0,0 @@
-module IMW
-  class Metadata
-
-    # A module which defines a DSL that can be used to define metadata
-    # for an object.
-    module DSL
-      
-      # Open a new resource at the given URI.
-      #
-      # If this dataset has metadata and it describes the resource
-      # then configure the resource to understand its schema..
-      #
-      # The +schema+ property passed via the options hash will
-      # override this.
-      # 
-      # @param [String, Addressable::Uri, IMW::Resource] uri
-      # @param [Hash] options
-      # @return [IMW::Resource]
-      # @see IMW.open
-      def open uri, options={}, &block
-        schema_options = (options[:schema].nil? && metadata && metadata.describe?(uri)) ? {:schema => metadata[uri]} : {}
-        IMW.open(uri, options.merge(schema_options), &block)
-      end
-
-      def open! uri, options={}, &block
-        self.open(uri, options.merge(:mode => 'w'), &block)
-      end
-
-      # When called without a block return this object's metadata.
-      # 
-      #   metadata
-      #   #=> { '/path/to/file' => [...], '/path/to/other/file' => [...], ... }
-      #
-      # When called with a block, accumulate schema and fields into
-      # this object's metadata
-      #
-      #   metadata do
-      #
-      #     schema "/path/to/file" do
-      #       # ...
-      #     end
-      #
-      #     schema "/path/to/other/file" do
-      #       # ...
-      #     end
-      #   end
-      #
-      # @see [IMW::Metadata::Schema]
-      # @see [IMW::Metadata::Field]      
-      # @return [IMW::Metadata]
-      def metadata arg=nil, options={}, &block
-        case arg
-        when Hash 
-          @metadata ||= Metadata.new(arg, options)
-        when nil
-          @metadata ||= Metadata.new nil, options
-        else
-          @metadata ||= Metadata.load(arg, options)
-        end
-        @metadata.base = options[:base] if options[:base]
-        return @metadata unless block_given?
-        yield
-      end
-
-      def schema resource, options={}, &block
-        new_field_accumulator!
-        yield
-        metadata[resource] = Schema.new(last_field_accumulator!)
-      end
-
-      def field name, options={}
-        accumulate_field Field.new(options.merge(:name => name))
-      end
-
-      def has_one name, options={}, &block
-        new_field_accumulator!
-        yield
-        accumulate_field Field.new(options.merge(:name => name, :has_one => last_field_accumulator!))
-      end
-
-      def has_many name, options={}, &block
-        new_field_accumulator!
-        yield
-        accumulate_field Field.new(options.merge(:name => name, :has_many => last_field_accumulator!))
-      end
-
-      protected
-
-      def field_accumulators    # :nodoc:
-        @field_accumulators ||= []
-      end
-      
-      def new_field_accumulator!    # :nodoc:
-        field_accumulators.push([])
-      end
-
-      def last_field_accumulator!    # :nodoc:
-        field_accumulators.pop
-      end
-      
-      def field_accumulator?    # :nodoc:
-        ! field_accumulators.empty?
-      end
-
-      def accumulate_field f    # :nodoc:
-        # raise IMW::SchemaError.new("No record or sub-record to accumulate fields in!") unless field_accumulator?
-        field_accumulators.last << f if field_accumulator?
-      end
-    end
-  end
-end

data/lib/imw/metadata/field.rb

@@ -1,37 +0,0 @@
-module IMW
-
-  class Metadata
-    
-    # Conceptually, a field is a "slot" for which "records" can have
-    # values.
-    #
-    # An IMW::Metadata::Field is essentially a Hash that has one required
-    # property: a name.
-    #
-    #   IMW::Metadata::Field.new('id')
-    #   #=> { 'name' => 'id' }
-    #
-    # But you can declare as many other properties as you want (as long
-    # as you include a +name+):
-    #
-    #   IMW::Metadata::Field.new 'name' => 'id', 'type' => :integer, 'title' => "ID", 'description' => "Auto-incremented."
-    #   #=> { 'name' => 'id', 'type' => :integer, 'title' > "ID", 'description' => "Auto-incremented." }
-    class Field < Hash
-
-      def initialize obj
-        super()
-        if obj.is_a?(Hash) || obj.is_a?(Field)
-          merge!(obj)
-          raise IMW::ArgumentError.new("A field must have a name") if obj['name'].blank?
-        else
-          self['name'] = obj.to_s.strip
-        end
-      end
-
-      def titleize
-        self['title'] || self['name'].capitalize # FIXME we can do better than this!
-      end
-
-    end
-  end
-end

data/lib/imw/metadata/has_metadata.rb

@@ -1,98 +0,0 @@
-module IMW
-  class Metadata
-
-
-    # A module which defines how a resource finds Metadata that it can
-    # look up metadata about itself.
-    #
-    # "metadata" in this context is defined as accessors for
-    # +metadata+ (IMW::Metadata), +schema+ (IMW::Metadata::Schema),
-    # +fields+ (IMW::Metadata::Field), and +description+ (String).
-    #
-    # An including class should define a method +dir+ which should
-    # return an object that might contain Metadata, i.e. - that
-    # includes the IMW::Metadata::ContainsMetadata module.
-    #
-    # An including class can optionally define the methods +snippet+
-    # which returns a snippet of the resource as well as
-    # +record_count+ to return a count of how many records the
-    # resource contains.
-    module HasMetadata
-
-      # The schema for this object.
-      #
-      # @return [Hash]
-      def schema
-        return @schema if @schema
-        @schema = IMW::Metadata::Schema.new
-        @schema[:type]      = "record"
-        @schema[:namespace] = "schema.imw.resource"
-        @schema[:name]      = (basename || '')        
-        begin
-          @schema[:doc]       = description
-          @schema[:fields]    = fields
-          
-          @schema[:non_avro ] = {}
-          @schema[:non_avro][:snippet]      = snippet      if respond_to?(:snippet) rescue nil
-          @schema[:non_avro][:record_count] = record_count if respond_to?(:record_count)
-          @schema
-        rescue => e
-          $stdout.puts "Error in producing schema for #{self}: #{e.class} -- #{e.message}"
-          return @schema
-        end
-      end
-      
-      # Return the metadata object that contains metadata for this
-      # resource.
-      #
-      # Will look in this resource's directory and recursively upward
-      # till the root directory is reached or a metadata file is
-      # discovered.
-      #
-      # @return [IMW::Metadata, nil]
-      def metadata
-        return @metadata if @metadata
-        d = dir
-        while d.path != '/'
-          break if d.metadata && d.metadata.describes?(self)
-          d = d.dir
-        end
-        @metadata = d.metadata
-      end
-
-      # The fields for this resource's data.
-      #
-      # Each field will be a Hash of information.
-      #
-      # @return [Array<Hash>]
-      def fields
-        @fields ||= metadata && metadata.fields_for(self)
-      end
-
-      # Set the fields for this resource.
-      #
-      # @param [Array<Hash>] new_fields
-      # @return [Array<Hash>]
-      def fields= new_fields
-        @fields = new_fields.map { |f| Metadata::Field.new(f) }
-      end
-
-      # A description for this Resource.
-      #
-      # @return [String]
-      def description
-        @description ||= metadata && metadata.description_for(self)
-      end
-
-      # Set the description of this Resource.
-      #
-      # @param [String] new_description
-      # @return [String]
-      def description= new_description
-        @description = new_description
-      end
-      
-    end
-  end
-end
-

data/lib/imw/metadata/has_summary.rb

@@ -1,57 +0,0 @@
-module IMW
-  class Metadata
-
-    # A module for generating a summary & schema of a resource.
-    #
-    # The including class should define methods +uri+, +basename+, +extension+.
-    module HasSummary
-      
-      # Return a full summary of this Resource.
-      #
-      # The summary will include "external" information about how this
-      # resource appears to the world (via its URI), "internal"
-      # metadata about this resource (its description, &c.), as well
-      # as the structure of this resource's data (it's schema's fields
-      # and a snippet).
-      #
-      # Will return a Hash, with a <tt>:schema</tt> key which maps to
-      # a well-formed AVRO schema for this resource.
-      #
-      # @return [Hash]
-      def summary
-        return @summary if @summary
-        @summary = {}
-        begin
-          @summary.merge!(external_summary)
-          @summary[:schema]   = schema                   if respond_to?(:schema)
-          @summary[:contents] = resources.map(&:summary) if respond_to?(:resources)
-          @summary
-        rescue => e
-          # IMW.warn "Error in producing summary for #{self}: #{e.class} -- #{e.message}"
-          return @summary
-        end
-      end
-
-      # Return information (usually scheme-dependent) on how this
-      # resource is situated in the world, i.e. - its URI, its size,
-      # how many lines it has, &c.
-      #
-      # Modules which override this should chain with +super+:
-      #
-      #   # in my_scheme.rb
-      #   def external_summary
-      #     super().merge(:user => 'bob', :password => 'smith')
-      #   end
-      #
-      # @return [Hash]
-      def external_summary
-        {
-          :uri       => uri.to_s,
-          :basename  => basename,
-          :extension => extension
-        }
-      end
-    end
-
-  end
-end