stac 0.1.0 → 0.3.0

data/lib/stac/{default_http_client.rb → simple_http_client.rb}

@@ -1,23 +1,28 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'open-uri'
 require_relative 'errors'
 require_relative 'version'
 
 module STAC
+  # Raised when a HTTP request failed.
+  class HTTPError < Error; end
+
   # Simple HTTP Client using OpenURI.
-  class DefaultHTTPClient
+  class SimpleHTTPClient
     attr_reader :options
 
     def initialize(options = { 'User-Agent' => "stac-ruby v#{VERSION}" })
       @options = options
     end
 
-    # Makes a HTTP request and returns the response body as String.
+    # Makes a HTTP request and returns the responded JSON as Hash.
     #
     # Raises STAC::HTTPError when the response status is not 2XX.
-    def get(uri)
-      uri.read(options)
+    def get(url)
+      body = URI(url).read(options)
+      JSON.parse(body)
     rescue OpenURI::HTTPError => e
       raise HTTPError, e.message
     end

data/lib/stac/stac_object.rb

@@ -1,46 +1,67 @@
 # frozen_string_literal: true
 
-require 'json'
 require_relative 'errors'
+require_relative 'file_writer'
+require_relative 'hash_like'
 require_relative 'link'
 require_relative 'spec_version'
 
 module STAC
-  # Base class for \STAC objects (i.e. Catalog, Collection and Item).
+  # Raised when a STAC object does not have rel="self" link HREF.
+  class NoSelfHrefError < Error
+    attr_reader :stac_object
+
+    def initialize(msg = nil, stac_object:)
+      super(msg)
+      @stac_object = stac_object
+    end
+  end
+
+  # Base class for \STAC objects (i.e. Catalog, Collection, and Item).
   class STACObject
+    include HashLike
+
+    @@extendables = {} # rubocop:disable Style/ClassVars
+
+    # Returns available extension modules.
+    def self.extendables
+      @@extendables.values.uniq
+    end
+
+    # Adds the given extension module to .extendables.
+    def self.add_extendable(extendable)
+      @@extendables[extendable.identifier] = extendable
+      self
+    end
+
     class << self
-      attr_accessor :type # :nodoc:
+      attr_reader :type # :nodoc:
 
       # Base method to deserialize shared fields from a Hash.
       #
       # Raises ArgumentError when any required fields are missing.
       def from_hash(hash)
-        raise TypeError, "type field is not 'Catalog': #{hash['type']}" if hash.fetch('type') != type
+        h = hash.transform_keys(&:to_sym)
+        raise TypeError, "type field is not '#{type}': #{h[:type]}" if h.fetch(:type) != type
 
-        transformed = hash.transform_keys(&:to_sym).except(:type, :stac_version)
-        transformed[:links] = transformed.fetch(:links).map { |link| Link.from_hash(link) }
-        new(**transformed)
-      rescue KeyError => e
-        raise ArgumentError, "required field not found: #{e.key}"
+        new(**h.except(:type, :stac_version))
       end
     end
 
-    attr_accessor :id, :stac_extensions, :extra
+    # HTTP Client to fetch objects from HTTP HREF links.
+    attr_accessor :http_client
 
-    attr_reader :links
+    attr_reader :stac_extensions, :links
 
-    def initialize(id:, links:, stac_extensions: nil, **extra)
-      @id = id
+    def initialize(links: [], stac_extensions: [], **extra)
       @links = []
       links.each do |link|
-        add_link(link) # to set `owner`
+        add_link(**link.transform_keys(&:to_sym)) # to set `owner`
       end
       @stac_extensions = stac_extensions
       @extra = extra.transform_keys(&:to_s)
-    end
-
-    def type
-      self.class.type
+      @http_client = STAC.default_http_client
+      apply_extensions!
     end
 
     # Serializes self to a Hash.
@@ -48,21 +69,64 @@ module STAC
       {
         'type' => type,
         'stac_version' => SPEC_VERSION,
-        'stac_extensions' => stac_extensions,
-        'id' => id,
+        'stac_extensions' => stac_extensions.empty? ? nil : stac_extensions,
         'links' => links.map(&:to_h),
       }.merge(extra).compact
     end
 
-    # Serializes self to a JSON string.
-    def to_json(...)
-      to_h.to_json(...)
+    def deep_dup
+      super.tap do |obj|
+        obj.http_client = http_client.dup
+      end
+    end
+
+    def type
+      self.class.type.to_s
+    end
+
+    # Returns extended extension modules.
+    def extended
+      @extended ||= []
+    end
+
+    # Adds the given extension identifier to #stac_extensions.
+    #
+    # When the given argument is extendable, the item extends the module.
+    def add_extension(extension)
+      case extension
+      when Extension
+        stac_extensions << extension.identifier
+        apply_extension!(extension)
+      else
+        stac_extensions << extension
+        if (extension = @@extendables[extension]) && extension.scope.include?(self.class)
+          apply_extension!(extension)
+        end
+      end
+      self
+    end
+
+    # Returns a link matching the arguments.
+    def find_link(rel:, type: nil)
+      links.find do |link|
+        if type
+          link.rel == rel && link.type == type
+        else
+          link.rel == rel
+        end
+      end
     end
 
     # Adds a link with setting Link#owner as self.
-    def add_link(link)
+    #
+    # Raises ArgumentError when both target and href are not given.
+    def add_link(target = nil, rel:, href: nil, type: nil, title: nil, **extra)
+      raise ArgumentError, 'target or href must be given' if target.nil? && href.nil?
+
+      link = Link.new(target, rel: rel, href: href, type: type, title: title, **extra)
       link.owner = self
       links << link
+      self
     end
 
     # Reterns HREF of the rel="self" link.
@@ -70,22 +134,69 @@ module STAC
       find_link(rel: 'self')&.href
     end
 
-    # Adds a link with the give HREF as rel="self".
+    # Overwrites rel="self" link with the given HREF.
     #
     # When any ref="self" links already exist, removes them.
     def self_href=(absolute_href)
-      self_link = Link.new(rel: 'self', href: absolute_href, type: 'application/json')
-      remove_link(rel: 'self')
-      add_link(self_link)
+      remove_links(rel: 'self')
+      add_link(rel: 'self', href: absolute_href, type: 'application/json')
+    end
+
+    # Returns a rel="root" link as a catalog/collection object if it exists.
+    def root
+      find_link(rel: 'root')&.target
+    end
+
+    # Overwrites rel="root" link.
+    def root=(catalog)
+      remove_links(rel: 'root')
+      add_link(catalog, rel: 'root', type: 'application/json', title: catalog.title) if catalog
+    end
+
+    # Returns a rel="parent" link as a catalog/collection object if it exists.
+    def parent
+      find_link(rel: 'parent')&.target
+    end
+
+    # Overwrites rel="parent" link.
+    def parent=(catalog)
+      remove_links(rel: 'parent')
+      add_link(catalog, rel: 'parent', type: 'application/json', title: catalog.title) if catalog
+    end
+
+    # Writes self on `dest` with the given writer.
+    #
+    # The default writer is a FileWriter.
+    def save(dest = nil, writer: FileWriter.new)
+      writer.write(to_h, dest: dest || self_href!)
+    end
+
+    protected
+
+    def self_href!
+      self_href or raise NoSelfHrefError.new('no rel="self" link href', stac_object: self)
     end
 
     private
 
-    def find_link(rel:)
-      links.find { |link| link.rel == rel }
+    def extensions
+      stac_extensions
+        .map { |extension_id| @@extendables[extension_id] }
+        .compact
+        .select { |extension| extension.scope.include?(self.class) }
+    end
+
+    def apply_extensions!
+      extensions.each do |extension|
+        apply_extension!(extension)
+      end
+    end
+
+    def apply_extension!(extension)
+      extended << extension
     end
 
-    def remove_link(rel:)
+    def remove_links(rel:)
       links.reject! { |link| link.rel == rel }
     end
   end

data/lib/stac/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module STAC
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

data/lib/stac.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
 require_relative 'stac/object_resolver'
+require_relative 'stac/simple_http_client'
+require_relative 'stac/stac_object'
+require_relative 'stac/extensions/electro_optical'
+require_relative 'stac/extensions/projection'
+require_relative 'stac/extensions/scientific_citation'
+require_relative 'stac/extensions/view_geometry'
 require_relative 'stac/version'
 
 # Gem namespace.
@@ -8,6 +14,8 @@ require_relative 'stac/version'
 # Provides some utility methods.
 module STAC
   class << self
+    attr_accessor :default_http_client
+
     # Returns a \STAC object resolved from the given file path.
     def from_file(path)
       from_url("file://#{File.expand_path(path)}")
@@ -16,10 +24,18 @@ module STAC
     # Returns a \STAC object resolved from the given URL.
     #
     # When the resolved object does not have rel="self" link, adds a rel="self" link with the give url.
-    def from_url(url, resolver: ObjectResolver.new)
-      object = resolver.resolve(url)
+    def from_url(url, http_client: default_http_client)
+      object = ObjectResolver.new(http_client: http_client).resolve(url)
       object.self_href = url unless object.self_href
       object
     end
   end
+
+  self.default_http_client = SimpleHTTPClient.new
+
+  STACObject
+    .add_extendable(Extensions::ElectroOptical)
+    .add_extendable(Extensions::Projection)
+    .add_extendable(Extensions::ScientificCitation)
+    .add_extendable(Extensions::ViewGeometry)
 end

data/sig/stac/asset.rbs

@@ -1,5 +1,8 @@
 module STAC
   class Asset
+    include HashLike
+    include CommonMetadata
+
     def self.from_hash: (Hash[String, untyped] hash) -> Asset
 
     attr_accessor href: String
@@ -7,12 +10,9 @@ module STAC
     attr_accessor description: String?
     attr_accessor type: String?
     attr_accessor roles: Array[String]?
-    attr_accessor extra: Hash[String, untyped]
 
     def initialize: (
       href: String, ?title: String?, ?description: String?, ?type: String?, ?roles: Array[String]?, **untyped
     ) -> void
-
-    def to_h: -> Hash[String, untyped]
   end
 end

data/sig/stac/catalog.rbs

@@ -1,20 +1,44 @@
 module STAC
   class Catalog < STACObject
-    def self.from_hash: (Hash[String, untyped] hash) -> Catalog
+    def self.from_hash: (Hash[String | Symbol, untyped] hash) -> Catalog
+    def self.root: (
+      id: String,
+      description: String,
+      href: String,
+      ?links: Array[Hash[String, String]],
+      ?title: String?,
+      ?stac_extensions: Array[String],
+      **untyped
+    ) -> Catalog
 
+    attr_accessor id: String
     attr_accessor description: String
     attr_accessor title: String?
     
     def initialize: (
-      id: String, description: String, links: Array[Link], ?title: String?, ?stac_extensions: Array[String]?, **untyped
+      id: String,
+      description: String,
+      ?links: Array[Hash[String, String]],
+      ?title: String?,
+      ?stac_extensions: Array[String],
+      **untyped
     ) -> void
 
-    def to_h: -> Hash[String, untyped]
-    def children: -> Enumerator::Lazy[Catalog | Collection, void]
+    def children: -> Enumerator::Lazy[Catalog, void]
+    def all_children: -> Enumerator::Lazy[Catalog, void]
     def collections: -> Enumerator::Lazy[Collection, void]
-    def find_child: (String id, ?recursive: bool) -> (Catalog | Collection | nil)
+    def all_collections: -> Enumerator::Lazy[Collection, void]
+    def find_child: (String id, ?recursive: bool) -> Catalog?
     def items: -> Enumerator::Lazy[Item, void]
     def all_items: -> Enumerator::Lazy[Item, void]
     def find_item: (String id, ?recursive: bool) -> Item?
+    def add_child: (Catalog catalog, ?href: String, ?title: String?) -> self
+    def add_item: (Item item, ?href: String, ?title: String?) -> self
+    def export: (?String? dest_dir, ?writer: _Writer) -> void
+
+    private
+
+    def child_links: -> Array[Link]
+    def item_links: -> Array[Link]
   end
 end

data/sig/stac/collection.rbs

@@ -1,29 +1,37 @@
 module STAC
   class Collection < Catalog
-    def self.from_hash: (Hash[String, untyped] hash) -> Collection
+    def self.from_hash: (Hash[String | Symbol, untyped] hash) -> Collection
 
     attr_accessor license: String
     attr_accessor extent: Extent
     attr_accessor keywords: Array[String]?
     attr_accessor providers: Array[Provider]?
     attr_accessor summaries: Hash[String, untyped]?
-    attr_accessor assets: Hash[String, Asset]?
+    attr_reader assets: Hash[String, Asset]?
 
     def initialize: (
       id: String,
       description: String,
-      links: Array[Link],
       license: String,
       extent: Extent,
+      ?links: Array[Hash[String, String]],
       ?title: String?,
       ?keywords: Array[String]?,
       ?providers: Array[Provider]?,
       ?summaries: Hash[String, untyped]?,
       ?assets: Hash[String, Asset]?,
-      ?stac_extensions: Array[String]?,
+      ?stac_extensions: Array[String],
       **untyped
     ) -> void
 
-    def to_h: -> Hash[String, untyped]
+    def add_asset: (
+      key: String,
+      href: String,
+      ?title: String?,
+      ?description: String?,
+      ?type: String?,
+      ?roles: Array[String]?,
+      **untyped
+    ) -> self
   end
 end

data/sig/stac/common_metadata.rbs

@@ -0,0 +1,34 @@
+module STAC
+  module CommonMetadata
+    attr_reader extra: Hash[String, untyped]
+    
+    def title: -> String?
+    def title=: (String) -> void
+    def description: -> String?
+    def description=: (String) -> void
+    def created: -> Time?
+    def created=: (Time | String) -> void
+    def updated: -> Time?
+    def updated=: (Time | String) -> void
+    def start_datetime: -> Time?
+    def start_datetime=: (Time | String) -> void
+    def end_datetime: -> Time?
+    def end_datetime=: (Time | String) -> void
+    def datetime_range: -> Range[Time]?
+    def datetime_range=: (Range[Time]) -> void
+    def license: -> String?
+    def license=: (String) -> void
+    def providers: -> Array[Provider]
+    def providers=: (Array[Provider | Hash[String, untyped]]) -> void
+    def platform: -> String?
+    def platform=: (String) -> void
+    def instruments: -> Array[String]?
+    def instruments=: (Array[String]) -> void
+    def constellation: -> String?
+    def constellation=: (String) -> void
+    def mission: -> String?
+    def mission=: (String) -> void
+    def gsd: -> Numeric
+    def gsd=: (Numeric) -> void
+  end
+end

data/sig/stac/errors.rbs

@@ -5,9 +5,6 @@ module STAC
   class TypeError < Error
   end
 
-  class UnknownURISchemeError < Error
-  end
-
-  class HTTPError < Error
+  class NotSupportedURISchemeError < Error
   end
 end

data/sig/stac/extension.rbs

@@ -0,0 +1,12 @@
+module STAC
+  class ExtensionWithoutIdentifierError < Error
+  end
+
+  module Extension
+    @identifier: String?
+    @scope: Array[Class]?
+
+    def identifier: -> String | (String) -> String
+    def scope: -> Array[Class] | (*Class) -> Array[Class]
+  end
+end

data/sig/stac/extensions/electro_optical.rbs

@@ -0,0 +1,40 @@
+module STAC
+  module Extensions
+    module ElectroOptical
+      extend Extension
+
+      module Properties
+        attr_reader extra: Hash[String, untyped]
+
+        def eo_bands: -> Array[Band]
+        def eo_bands=: (Array[Hash[String, untyped] | Band]) -> void
+        def eo_cloud_cover: -> Numeric?
+        def eo_cloud_cover=: (Numeric) -> void
+      end
+
+      module Asset
+        include Properties
+      end
+                     
+      class Band
+        attr_reader raw_hash: Hash[String, untyped]
+
+        def initialize: (Hash[String, untyped] raw_hash) -> void
+        
+        def to_h: -> Hash[String, untyped]
+        def name: -> String?
+        def name=: (String) -> void
+        def common_name: -> String?
+        def common_name=: (String) -> void
+        def description: -> String?
+        def description=: (String) -> void
+        def center_wavelength: -> Numeric?
+        def center_wavelength=: (Numeric) -> void
+        def full_width_half_max: -> Numeric?
+        def full_width_half_max=: (Numeric) -> void
+        def solar_illumination: -> Numeric?
+        def solar_illumination=: (Numeric) -> void
+      end
+    end
+  end
+end

data/sig/stac/extensions/projection.rbs

@@ -0,0 +1,32 @@
+module STAC
+  module Extensions
+    module Projection
+      extend Extension
+
+      module Properties
+        attr_reader extra: Hash[String, untyped]
+
+        def proj_epsg: -> Numeric?
+        def proj_epsg=: (Numeric) -> void
+        def proj_wkt2: -> String?
+        def proj_wkt2=: (String) -> void
+        def proj_projjson: -> Hash[String, untyped]?
+        def proj_projjson=: (Hash[String, untyped]) -> void
+        def proj_geometry: -> Hash[String, untyped]?
+        def proj_geometry=: (Hash[String, untyped]) -> void
+        def proj_bbox: -> Array[Numeric]?
+        def proj_bbox=: (Array[Numeric]) -> void
+        def proj_centroid: -> {'lat' => Numeric, 'lon' => Numeric}?
+        def proj_centroid=: ({'lat' => Numeric, 'lon' => Numeric}) -> void
+        def proj_shape: -> Array[Integer]?
+        def proj_shape=: (Array[Integer]) -> void
+        def proj_transform: -> Array[Numeric]?
+        def proj_transform=: (Array[Numeric]) -> void
+      end
+
+      module Asset
+        include Properties
+      end
+    end
+  end
+end

data/sig/stac/extensions/scientific_citation.rbs

@@ -0,0 +1,38 @@
+module STAC
+  module Extensions
+    module ScientificCitation
+      extend Extension
+
+      module Properties
+        attr_reader extra: Hash[String, untyped]
+
+        def sci_doi: -> String?
+        def sci_doi=: (String) -> void
+        def sci_citation: -> String?
+        def sci_citation=: (String) -> void
+        def sci_publications: -> Array[Publication]
+        def sci_publications=: (Array[Hash[String, String] | Publication]) -> void
+      end
+
+      module Asset
+        include Properties
+      end
+
+      module Collection
+        include Properties
+      end
+
+      class Publication
+        attr_reader raw_hash: Hash[String, String]
+
+        def initialize: (Hash[String, String] raw_hash) -> void
+        
+        def to_h: -> Hash[String, String]
+        def doi: -> String?
+        def doi=: (String) -> void
+        def citation: -> String?
+        def citation=: (String) -> void
+      end
+    end
+  end
+end

data/sig/stac/extensions/view_geometry.rbs

@@ -0,0 +1,22 @@
+module STAC
+  module Extensions
+    module ViewGeometry
+      extend Extension
+
+      module Properties
+        attr_reader extra: Hash[String, untyped]
+
+        def view_off_nadir: -> Numeric?
+        def view_off_nadir=: (Numeric) -> void
+        def view_incidence_angle: -> Numeric?
+        def view_incidence_angle=: (Numeric) -> void
+        def view_azimuth: -> Numeric?
+        def view_azimuth=: (Numeric) -> void
+        def view_sun_azimuth: -> Numeric?
+        def view_sun_azimuth=: (Numeric) -> void
+        def view_sun_elevation: -> Numeric?
+        def view_sun_elevation=: (Numeric) -> void
+      end
+    end
+  end
+end

data/sig/stac/extent.rbs

@@ -1,35 +1,32 @@
 module STAC
   class Extent
+    include HashLike
+
+    def self.from_hash: (Hash[String, untyped] hash) -> Extent
+
+    attr_accessor spatial: Spatial
+    attr_accessor temporal: Temporal
+
+    def initialize: (spatial: Spatial, temporal: Temporal, **untyped) -> void
+    
     class Spatial
+      include HashLike
+
       def self.from_hash: (Hash[String, untyped] hash) -> Spatial
 
       attr_accessor bbox: Array[Array[Numeric]]
-      attr_accessor extra: Hash[String, untyped]
 
       def initialize: (bbox: Array[Array[Numeric]], **untyped) -> void
-
-      def to_h: -> Hash[String, untyped]
     end
 
     class Temporal
+      include HashLike
+
       def self.from_hash: (Hash[String, untyped] hash) -> Temporal
 
       attr_accessor interval: Array[Array[String?]]
-      attr_accessor extra: Hash[String, untyped]
 
       def initialize: (interval: Array[Array[String?]], **untyped) -> void
-
-      def to_h: -> Hash[String, untyped]
     end
-
-    def self.from_hash: (Hash[String, untyped] hash) -> Extent
-
-    attr_accessor spatial: Spatial
-    attr_accessor temporal: Temporal
-    attr_accessor extra: Hash[String, untyped]
-
-    def initialize: (spatial: Spatial, temporal: Temporal, **untyped) -> void
-
-    def to_h: -> Hash[String, untyped]
   end
 end