stac 0.2.0 → 0.3.0

data/lib/stac/extent.rb

@@ -1,18 +1,50 @@
 # frozen_string_literal: true
 
+require_relative 'hash_like'
+
 module STAC
-  # Represents \STAC extent object, which describes the spatio-temporal extents of a Collection.
+  # Represents \STAC extent object, which describes the spatio-temporal extents of a collection.
   #
   # Specification: https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#extent-object
   class Extent
-    # Describes the spatial extents of a Collection
+    include HashLike
+
+    class << self
+      # Deserializes an Extent from a Hash.
+      def from_hash(hash)
+        transformed = hash.transform_keys(&:to_sym)
+        transformed[:spatial] = Spatial.from_hash(transformed.fetch(:spatial))
+        transformed[:temporal] = Temporal.from_hash(transformed.fetch(:temporal))
+        new(**transformed)
+      end
+    end
+
+    attr_accessor :spatial, :temporal
+
+    def initialize(spatial:, temporal:, **extra)
+      @spatial = spatial
+      @temporal = temporal
+      @extra = extra.transform_keys(&:to_s)
+    end
+
+    # Serializes self to a Hash.
+    def to_h
+      {
+        'spatial' => spatial.to_h,
+        'temporal' => temporal.to_h,
+      }.merge(extra)
+    end
+
+    # Describes the spatial extents of a collection
     class Spatial
+      include HashLike
+
       # Deserializes a Spatial from a Hash.
       def self.from_hash(hash)
         new(**hash.transform_keys(&:to_sym))
       end
 
-      attr_accessor :bbox, :extra
+      attr_accessor :bbox
 
       def initialize(bbox:, **extra)
         @bbox = bbox
@@ -27,14 +59,16 @@ module STAC
       end
     end
 
-    # Describes the temporal extents of a Collection.
+    # Describes the temporal extents of a collection.
     class Temporal
+      include HashLike
+
       # Deserializes a Temporal from a Hash.
       def self.from_hash(hash)
         new(**hash.transform_keys(&:to_sym))
       end
 
-      attr_accessor :interval, :extra
+      attr_accessor :interval
 
       def initialize(interval:, **extra)
         @interval = interval
@@ -48,31 +82,5 @@ module STAC
         }.merge(extra)
       end
     end
-
-    class << self
-      # Deserializes an Extent from a Hash.
-      def from_hash(hash)
-        transformed = hash.transform_keys(&:to_sym)
-        transformed[:spatial] = Spatial.from_hash(transformed.fetch(:spatial))
-        transformed[:temporal] = Temporal.from_hash(transformed.fetch(:temporal))
-        new(**transformed)
-      end
-    end
-
-    attr_accessor :spatial, :temporal, :extra
-
-    def initialize(spatial:, temporal:, **extra)
-      @spatial = spatial
-      @temporal = temporal
-      @extra = extra.transform_keys(&:to_s)
-    end
-
-    # Serializes self to a Hash.
-    def to_h
-      {
-        'spatial' => spatial.to_h,
-        'temporal' => temporal.to_h,
-      }.merge(extra)
-    end
   end
 end

data/lib/stac/file_writer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'json'
+require 'uri'
+require_relative 'errors'
+
+module STAC
+  # Class to write a hash as JSON on a file.
+  class FileWriter
+    def initialize(hash_to_json: ->(hash) { JSON.generate(hash) })
+      @hash_to_json = hash_to_json
+    end
+
+    # Creates a file on `dest` with the given hash as JSON.
+    def write(hash, dest:)
+      dest_uri = URI.parse(dest)
+      path = if dest_uri.relative?
+               dest
+             elsif dest_uri.is_a?(URI::File)
+               dest_uri.path.to_s
+             else
+               raise NotSupportedURISchemeError, "not supported URI scheme: #{dest}"
+             end
+
+      pathname = Pathname(path)
+      pathname.dirname.mkpath
+      pathname.write(@hash_to_json.call(hash))
+    end
+  end
+end

data/lib/stac/hash_like.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module STAC
+  # Enables included class to behave like Hash.
+  module HashLike
+    # Extra fields that do not belong to the STAC core specification.
+    attr_reader :extra
+
+    # When there is an attribute with the given name, returns the attribute value.
+    # Otherwise, calls `extra [key]`.
+    def [](key)
+      if respond_to?(key) && method(key).arity.zero?
+        public_send(key)
+      else
+        extra[key.to_s]
+      end
+    end
+
+    # When there is an attribute writer with the given name, assigns the value to the attribute.
+    # Otherwise, adds the given key-value pair to `extra` hash.
+    def []=(key, value)
+      method = "#{key}="
+      if respond_to?(method)
+        public_send(method, value)
+      else
+        extra[key.to_s] = value
+      end
+    end
+
+    # Sets the attributes (like ActiveModel::AttributeAssignment#assign_attributes)
+    # or merges the args into `extra` hash (like Hash#update).
+    def update(**options)
+      options.each do |key, value|
+        self[key] = value
+      end
+      self
+    end
+
+    def to_hash # :nodoc:
+      to_h
+    end
+
+    # Serializes self to a Hash.
+    def to_h
+      extra
+    end
+
+    # Serializes self to a JSON string.
+    def to_json(...)
+      to_h.to_json(...)
+    end
+
+    # Returns `true` if all of the followings are true:
+    # - the given object is an instance of tha same class
+    # - `self.to_hash == other.to_hash`
+    #
+    # Otherwise, returns `false`.
+    def ==(other)
+      other.instance_of?(self.class) && to_hash == other.to_hash
+    end
+
+    # Returns a copy of self by serializes self to a JSON and desirializes it by `.from_hash`.
+    def deep_dup
+      unless self.class.respond_to?(:from_hash)
+        raise NotImplementedError, "#{self.class} must implement `.from_hash(hash)` to use `HashLike#deep_dup`"
+      end
+
+      hash = JSON.parse(to_json)
+      self.class.from_hash(hash)
+    end
+  end
+end

data/lib/stac/item.rb

@@ -10,25 +10,26 @@ module STAC
   #
   # \STAC \Item Specification: https://github.com/radiantearth/stac-spec/tree/master/item-spec
   class Item < STAC::STACObject
-    self.type = 'Feature'
+    @type = 'Feature'
 
     class << self
       def from_hash(hash)
-        h = hash.dup
-        h['properties'] = Properties.from_hash(h.fetch('properties'))
-        h['assets'] = h.fetch('assets').transform_values { |v| Asset.from_hash(v) }
+        h = hash.transform_keys(&:to_sym)
+        h[:properties] = Properties.from_hash(h.fetch(:properties, {}))
+        h[:assets] = h.fetch(:assets, {}).transform_values { |v| Asset.from_hash(v) }
         super(h)
       rescue KeyError => e
         raise ArgumentError, "required field not found: #{e.key}"
       end
     end
 
-    attr_accessor :id, :geometry, :bbox, :properties, :assets, :collection_id
+    attr_accessor :id, :geometry, :bbox, :collection_id
+
+    attr_reader :properties, :assets
 
     def initialize(
-      id:, geometry:, properties:, links:, assets:, bbox: nil, collection: nil, stac_extensions: nil, **extra
+      id:, geometry:, properties:, links: [], assets: {}, bbox: nil, collection: nil, stac_extensions: [], **extra
     )
-      super(links: links, stac_extensions: stac_extensions, **extra)
       @id = id
       @geometry = geometry
       @properties = properties
@@ -40,6 +41,16 @@ module STAC
       else
         @collection_id = collection
       end
+      super(links: links, stac_extensions: stac_extensions, **extra)
+    end
+
+    def [](key)
+      value = super
+      if value.nil?
+        properties.extra[key.to_s]
+      else
+        value
+      end
     end
 
     def to_h
@@ -58,11 +69,6 @@ module STAC
       )
     end
 
-    # Returns datetime from #properties.
-    def datetime
-      properties.datetime
-    end
-
     # Returns a rel="collection" link as a collection object if it exists.
     def collection
       link = find_link(rel: 'collection')
@@ -71,17 +77,45 @@ module STAC
 
     # Overwrites rel="collection" link and #collection_id attribute.
     def collection=(collection)
-      raise ArgumentError, 'collection must have a rel="self" link' unless (collection_href = collection.self_href)
-
       @collection_id = collection.id
-      collection_link = Link.new(
-        rel: 'collection',
-        href: collection_href,
-        type: 'application/json',
-        title: collection.title,
-      )
-      remove_link(rel: 'collection')
-      add_link(collection_link)
+      remove_links(rel: 'collection')
+      add_link(collection, rel: 'collection', type: 'application/json', title: collection.title)
+    end
+
+    # Adds an asset with the given key.
+    #
+    # When the item has extendable stac_extensions, make the asset extend the extension modules.
+    def add_asset(key:, href:, title: nil, description: nil, type: nil, roles: nil, **extra)
+      asset = Asset.new(href: href, title: title, description: description, type: type, roles: roles, **extra)
+      extensions.each do |extension|
+        asset.extend(extension::Asset) if extension.const_defined?(:Asset)
+      end
+      assets[key] = asset
+      self
+    end
+
+    private
+
+    def respond_to_missing?(symbol, include_all)
+      if properties.respond_to?(symbol)
+        true
+      else
+        super
+      end
+    end
+
+    def method_missing(symbol, *args, **options, &block)
+      if properties.respond_to?(symbol)
+        properties.public_send(symbol, *args, **options, &block)
+      else
+        super
+      end
+    end
+
+    def apply_extension!(extension)
+      super
+      properties.extend(extension::Properties) if extension.const_defined?(:Properties)
+      assets.each_value { |asset| asset.extend(extension::Asset) } if extension.const_defined?(:Asset)
     end
   end
 end

data/lib/stac/link.rb

@@ -3,10 +3,23 @@
 require 'pathname'
 require 'uri'
 require_relative 'errors'
+require_relative 'hash_like'
 
 module STAC
+  # Raised when a link does not have href or owner.
+  class LinkHrefError < Error
+    attr_reader :link
+
+    def initialize(msg = nil, link:)
+      super(msg)
+      @link = link
+    end
+  end
+
   # Represents \STAC link object, which describes a relationship with another entity.
   class Link
+    include HashLike
+
     class << self
       # Deserializes a Link from a Hash.
       def from_hash(hash)
@@ -14,14 +27,15 @@ module STAC
       end
     end
 
-    attr_accessor :rel, :href, :type, :title, :extra
+    attr_accessor :rel, :type, :title
+
+    attr_writer :href
 
     # Owner object of this link.
     attr_accessor :owner
 
-    attr_writer :resolver # :nodoc:
-
-    def initialize(rel:, href:, type: nil, title: nil, **extra)
+    def initialize(target = nil, rel:, href:, type: nil, title: nil, **extra)
+      @target = target
       @rel = rel
       @href = href
       @type = type
@@ -39,14 +53,30 @@ module STAC
       }.merge(extra).compact
     end
 
+    # Determines if the link's target is a resolved STACObject.
+    def resolved?
+      !@target.nil?
+    end
+
+    def href
+      @href || @target&.self_href
+    end
+
     # Returns the absolute HREF for this link.
-    #
-    # When it could not assemble the absolute HREF, it returns nil.
     def absolute_href
-      if URI(href).absolute?
-        href
+      if URI(href!).absolute?
+        href!
+      elsif (base_href = owner&.self_href)
+        Pathname(base_href).dirname.join(href!).to_s
+      end
+    end
+
+    # Returns the relative HREF for this link.
+    def relative_href
+      if URI(href!).relative?
+        href!
       elsif (base_href = owner&.self_href)
-        Pathname(base_href).dirname.join(href).to_s
+        Pathname(href!).relative_path_from(Pathname(base_href).dirname).to_s
       end
     end
 
@@ -60,5 +90,17 @@ module STAC
                     object
                   end
     end
+
+    def href! # :nodoc:
+      href or raise LinkHrefError.new('href is nil', link: self)
+    end
+
+    def absolute_href! # :nodoc:
+      absolute_href or raise LinkHrefError.new('could not assemble absolute href', link: self)
+    end
+
+    def relative_href! # :nodoc:
+      relative_href or raise LinkHrefError.new('could not assemble relative href', link: self)
+    end
   end
 end

data/lib/stac/object_resolver.rb

@@ -11,10 +11,10 @@ module STAC
   class ObjectResolver
     class << self
       # Resolvable classes. Default is Catalog, Collection and Item.
-      attr_accessor :resolvables
+      attr_reader :resolvables
     end
 
-    self.resolvables = [Catalog, Collection, Item]
+    @resolvables = [Catalog, Collection, Item]
 
     attr_reader :http_client
 
@@ -30,7 +30,7 @@ module STAC
     # - file
     #
     # Raises:
-    # - STAC::UnknownURISchemeError when a URL with unsupported scheme was given
+    # - STAC::NotSupportedURISchemeError when a URL with not supported scheme was given
     # - STAC::TypeError when it could not resolve any \STAC objects
     def resolve(url)
       hash = read(url)
@@ -53,7 +53,7 @@ module STAC
         str = File.read(uri.path.to_s)
         JSON.parse(str)
       else
-        raise UnknownURISchemeError, "unknown URI scheme: #{url}"
+        raise NotSupportedURISchemeError, "not supported URI scheme: #{url}"
       end
     end
   end

data/lib/stac/properties.rb

@@ -2,12 +2,14 @@
 
 require 'time'
 require_relative 'common_metadata'
+require_relative 'hash_like'
 
 module STAC
   # Represents \STAC properties object, which is additional metadata for Item.
   #
   # Specification: https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md#properties-object
   class Properties
+    include HashLike
     include CommonMetadata
 
     class << self
@@ -23,7 +25,7 @@ module STAC
 
     def initialize(datetime:, **extra)
       @datetime = datetime
-      self.extra = extra.transform_keys(&:to_s)
+      @extra = extra.transform_keys(&:to_s)
     end
 
     # Serializes self to a Hash.

data/lib/stac/provider.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require_relative 'hash_like'
+
 module STAC
   # Represents \STAC provider object, which provides information about a provider.
   #
   # Specicication: https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#provider-object
   class Provider
+    include HashLike
+
     class << self
       # Deserializes a Provider from a Hash.
       def from_hash(hash)
@@ -12,7 +16,7 @@ module STAC
       end
     end
 
-    attr_accessor :name, :description, :roles, :url, :extra
+    attr_accessor :name, :description, :roles, :url
 
     def initialize(name:, description: nil, roles: nil, url: nil, **extra)
       @name = name

data/lib/stac/simple_http_client.rb

@@ -6,6 +6,9 @@ require_relative 'errors'
 require_relative 'version'
 
 module STAC
+  # Raised when a HTTP request failed.
+  class HTTPError < Error; end
+
   # Simple HTTP Client using OpenURI.
   class SimpleHTTPClient
     attr_reader :options