proj4rb 4.1.0 → 5.0.0

data/lib/proj/grid.rb

@@ -1,121 +1,121 @@
-module Proj
-  # Grids define models that are used to perform dimension shifts.
-  #
-  # Grid files can be quite large and may not be included with Proj depending on how
-  # it was packaged and any grid licensing requirements. Therefore, Proj has the ability
-  # to download grids on the fly if {Context#network_enabled? networking} is enabled.
-  #
-  # @see https://proj.org/community/rfc/rfc-4.html#rfc4
-  class Grid
-    # @!attribute [r] context
-    #   @return [Context] The grid context
-    # @!attribute [r] name
-    #   @return [String] The grid's name
-    # @!attribute [r] full_name
-    #   @return [String] The grid's full name
-    # @!attribute [r] package_name
-    #   @return [String] The grid's package name
-    # @!attribute [r] url
-    #   @return [URI] A url that can be used to download the grid
-    attr_reader :context, :name, :full_name, :package_name, :url
-
-    def initialize(name, context = Context.default, full_name: nil, package_name: nil, url: nil,
-                   downloadable: false, open_license: false, available: false)
-      @name = name
-      @context = context
-      @full_name = full_name
-      @package_name = package_name
-      @url = url
-      @downloadable = downloadable
-      @open_license = open_license
-      @available = available
-    end
-
-    # Returns whether the grid can be downloaded
-    #
-    # @return [Boolean]
-    def downloadable?
-      @downloadable
-    end
-
-    # Returns whether the grid is released with an open license
-    #
-    # @return [Boolean]
-    def open_license?
-      @open_license
-    end
-
-    # Returns whether the grid is available at runtime
-    #
-    # @return [Boolean]
-    def available?
-      @available
-    end
-
-    # Returns information about this grid
-    #
-    # See https://proj.org/development/reference/functions.html#c.proj_grid_info proj_grid_info
-    #
-    # @return [GridInfo]
-    def info
-      ptr = Api.proj_grid_info(self.name)
-      GridInfo.new(ptr)
-    end
-
-    # Returns if a grid is available in the PROJ user-writable directory.
-    # This method will only return true if Context#network_enabled? is true
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_is_download_needed
-    #
-    # @param ignore_ttl [Boolean] If set to FALSE, PROJ will only check the recentness of an already downloaded file, if the delay between the last time it has been verified and the current time exceeds the TTL setting. This can save network accesses. If set to TRUE, PROJ will unconditionally check from the server the recentness of the file.
-    #
-    # @return [Boolean]
-    def downloaded?(ignore_ttl = false)
-      if self.context.network_enabled?
-        result = Api.proj_is_download_needed(self.context, self.url&.to_s || self.name, ignore_ttl ? 1 : 0)
-        result == 1 ? false : true
-      else
-        false
-      end
-    end
-
-    # Download a file in the PROJ user-writable directory if has not already been downlaoded.
-    # This function can only be used if networking is enabled
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_download_file
-    #
-    # @param ignore_ttl [Boolean] If set to FALSE, PROJ will only check the recentness of an already downloaded file, if the delay between the last time it has been verified and the current time exceeds the TTL setting. This can save network accesses. If set to TRUE, PROJ will unconditionally check from the server the recentness of the file.
-    # @yieldparam percent [Float] The progress downloading the file in the range of 0 to 1
-    #
-    # @return [Boolean] True if the download was successful or unneeded. Otherwise false
-    def download(ignore_ttl = false)
-      callback = if block_given?
-                   Proc.new do |context, percent, user_data|
-                     result = yield percent
-                     # Return 1 to tell Proj to keep downloading the file
-                     result ? 1 : 0
-                   end
-                 end
-
-      result = Api.proj_download_file(self.context, self.url&.to_s || self.name, ignore_ttl ? 1 : 0, callback, nil)
-      result == 1 ? true : false
-    end
-
-    # Deletes the grid if it has been downloaded
-    def delete
-      if self.downloaded?
-        path = File.join(self.context.user_directory, self.name)
-        File.delete(path) if File.exist?(path)
-      end
-    end
-
-    # Returns the path to the grid if it has been downloaded
-    #
-    # @return [String]
-    def path
-      if self.downloaded?
-        File.join(self.context.user_directory, self.name)
-      end
-    end
-  end
-end
+module Proj
+  # Grids define models that are used to perform dimension shifts.
+  #
+  # Grid files can be quite large and may not be included with Proj depending on how
+  # it was packaged and any grid licensing requirements. Therefore, Proj has the ability
+  # to download grids on the fly if {Context#network_enabled? networking} is enabled.
+  #
+  # @see https://proj.org/community/rfc/rfc-4.html#rfc4
+  class Grid
+    # @!attribute [r] context
+    #   @return [Context] The grid context
+    # @!attribute [r] name
+    #   @return [String] The grid's name
+    # @!attribute [r] full_name
+    #   @return [String] The grid's full name
+    # @!attribute [r] package_name
+    #   @return [String] The grid's package name
+    # @!attribute [r] url
+    #   @return [URI] A url that can be used to download the grid
+    attr_reader :context, :name, :full_name, :package_name, :url
+
+    def initialize(name, context = Context.default, full_name: nil, package_name: nil, url: nil,
+                   downloadable: false, open_license: false, available: false)
+      @name = name
+      @context = context
+      @full_name = full_name
+      @package_name = package_name
+      @url = url
+      @downloadable = downloadable
+      @open_license = open_license
+      @available = available
+    end
+
+    # Returns whether the grid can be downloaded
+    #
+    # @return [Boolean]
+    def downloadable?
+      @downloadable
+    end
+
+    # Returns whether the grid is released with an open license
+    #
+    # @return [Boolean]
+    def open_license?
+      @open_license
+    end
+
+    # Returns whether the grid is available at runtime
+    #
+    # @return [Boolean]
+    def available?
+      @available
+    end
+
+    # Returns information about this grid
+    #
+    # See https://proj.org/development/reference/functions.html#c.proj_grid_info proj_grid_info
+    #
+    # @return [GridInfo]
+    def info
+      ptr = Api.proj_grid_info(self.name)
+      GridInfo.new(ptr)
+    end
+
+    # Returns if a grid is available in the PROJ user-writable directory.
+    # This method will only return true if Context#network_enabled? is true
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_is_download_needed
+    #
+    # @param ignore_ttl [Boolean] If set to FALSE, PROJ will only check the recentness of an already downloaded file, if the delay between the last time it has been verified and the current time exceeds the TTL setting. This can save network accesses. If set to TRUE, PROJ will unconditionally check from the server the recentness of the file.
+    #
+    # @return [Boolean]
+    def downloaded?(ignore_ttl = false)
+      if self.context.network_enabled?
+        result = Api.proj_is_download_needed(self.context, self.url&.to_s || self.name, ignore_ttl ? 1 : 0)
+        result == 1 ? false : true
+      else
+        false
+      end
+    end
+
+    # Download a file in the PROJ user-writable directory if has not already been downlaoded.
+    # This function can only be used if networking is enabled
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_download_file
+    #
+    # @param ignore_ttl [Boolean] If set to FALSE, PROJ will only check the recentness of an already downloaded file, if the delay between the last time it has been verified and the current time exceeds the TTL setting. This can save network accesses. If set to TRUE, PROJ will unconditionally check from the server the recentness of the file.
+    # @yieldparam percent [Float] The progress downloading the file in the range of 0 to 1
+    #
+    # @return [Boolean] True if the download was successful or unneeded. Otherwise false
+    def download(ignore_ttl = false)
+      callback = if block_given?
+                   Proc.new do |context, percent, user_data|
+                     result = yield percent
+                     # Return 1 to tell Proj to keep downloading the file
+                     result ? 1 : 0
+                   end
+                 end
+
+      result = Api.proj_download_file(self.context, self.url&.to_s || self.name, ignore_ttl ? 1 : 0, callback, nil)
+      result == 1 ? true : false
+    end
+
+    # Deletes the grid if it has been downloaded
+    def delete
+      if self.downloaded?
+        path = File.join(self.context.user_directory, self.name)
+        File.delete(path) if File.exist?(path)
+      end
+    end
+
+    # Returns the path to the grid if it has been downloaded
+    #
+    # @return [String]
+    def path
+      if self.downloaded?
+        File.join(self.context.user_directory, self.name)
+      end
+    end
+  end
+end

data/lib/proj/grid_cache.rb

@@ -1,64 +1,65 @@
-module Proj
-  # To avoid repeated network access, it is possible to enable a local cache of grids.
-  # Grid data is stored in a SQLite3 database, cache.db, that is by default stored
-  # stored in the PROJ user writable directory.
-  #
-  # The local cache is enabled by default with a size of 300MB. Cache settings can be overridden
-  # by this class, env variables or the proj.ini file
-  #
-  # @see https://proj.org/usage/network.html#caching
-  class GridCache
-    attr_reader :context
-
-    def initialize(context)
-      @context = context
-    end
-
-    # Enables or disables the grid cache
-    #
-    # @param value [Boolean]
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_set_enable
-    def enabled=(value)
-      Api.proj_grid_cache_set_enable(self.context, value ? 1 : 0)
-    end
-
-    # Set the path and file of the local cache file which is sqlite database. By default
-    # it is stored in the user writable directory.
-    #
-    # @param value [String] - Full path to the cache. If set to nil then caching will be disabled.
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_set_filename
-    def path=(value)
-      Api.proj_grid_cache_set_filename(self.context, value.encode('UTF-8'))
-      value
-    end
-
-    # Sets the cache size
-    #
-    # @param value [Integer] Maximum size in Megabytes (1024*1024 bytes), or negative value to set unlimited size.
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_set_max_size
-    def max_size=(value)
-      Api.proj_grid_cache_set_max_size(self.context, value)
-      value
-    end
-
-    # Specifies the time-to-live delay for re-checking if the cached properties of files are still up-to-date.
-    #
-    # @param value [Integer] Delay in seconds. Use negative value for no expiration.
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_set_ttl
-    def ttl=(value)
-      Api.proj_grid_cache_set_ttl(self.context, value)
-      value
-    end
-
-    # Clears the cache
-    #
-    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_clear
-    def clear
-      Api.proj_grid_cache_clear(self.context)
-    end
-  end
-end
+module Proj
+  # To avoid repeated network access, it is possible to enable a local cache of grids.
+  # Grid data is stored in a SQLite3 database, cache.db, that is by default stored
+  # stored in the PROJ user writable directory.
+  #
+  # The local cache is enabled by default with a size of 300MB. Cache settings can be overridden
+  # by this class, env variables or the proj.ini file
+  #
+  # @see https://proj.org/usage/network.html#caching
+  class GridCache
+    attr_reader :context
+
+    def initialize(context)
+      Error.validate_context!(context)
+      @context = context
+    end
+
+    # Enables or disables the grid cache
+    #
+    # @param value [Boolean]
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_set_enable
+    def enabled=(value)
+      Api.proj_grid_cache_set_enable(self.context, value ? 1 : 0)
+    end
+
+    # Set the path and file of the local cache file which is sqlite database. By default
+    # it is stored in the user writable directory.
+    #
+    # @param value [String] - Full path to the cache. If set to nil then caching will be disabled.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_set_filename
+    def path=(value)
+      Api.proj_grid_cache_set_filename(self.context, value.encode('UTF-8'))
+      value
+    end
+
+    # Sets the cache size
+    #
+    # @param value [Integer] Maximum size in Megabytes (1024*1024 bytes), or negative value to set unlimited size.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_set_max_size
+    def max_size=(value)
+      Api.proj_grid_cache_set_max_size(self.context, value)
+      value
+    end
+
+    # Specifies the time-to-live delay for re-checking if the cached properties of files are still up-to-date.
+    #
+    # @param value [Integer] Delay in seconds. Use negative value for no expiration.
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_set_ttl
+    def ttl=(value)
+      Api.proj_grid_cache_set_ttl(self.context, value)
+      value
+    end
+
+    # Clears the cache
+    #
+    # @see https://proj.org/development/reference/functions.html#c.proj_grid_cache_clear
+    def clear
+      Api.proj_grid_cache_clear(self.context)
+    end
+  end
+end

data/lib/proj/grid_info.rb

@@ -1,19 +1,19 @@
-module Proj
-  class GridInfo
-    attr_reader :gridname, :filename, :format,
-                :lower_left, :upper_right,
-                :size_lon, :size_lat, :cell_size_lon, :cell_size_lat
-
-    def initialize(pj_grid_info)
-      @filename = pj_grid_info[:filename].to_ptr.read_string
-      @gridname = pj_grid_info[:gridname].to_ptr.read_string
-      @format = pj_grid_info[:format].to_ptr.read_string
-      @lower_left = pj_grid_info[:lowerleft]
-      @upper_right = pj_grid_info[:upperright]
-      @size_lon = pj_grid_info[:n_lon]
-      @size_lat = pj_grid_info[:n_lat]
-      @cell_size_lon = pj_grid_info[:cs_lon]
-      @cell_size_lat = pj_grid_info[:cs_lat]
-    end
-  end
-end
+module Proj
+  class GridInfo
+    attr_reader :gridname, :filename, :format,
+                :lower_left, :upper_right,
+                :size_lon, :size_lat, :cell_size_lon, :cell_size_lat
+
+    def initialize(pj_grid_info)
+      @filename = pj_grid_info[:filename].to_ptr.read_string
+      @gridname = pj_grid_info[:gridname].to_ptr.read_string
+      @format = pj_grid_info[:format].to_ptr.read_string
+      @lower_left = pj_grid_info[:lowerleft]
+      @upper_right = pj_grid_info[:upperright]
+      @size_lon = pj_grid_info[:n_lon]
+      @size_lat = pj_grid_info[:n_lat]
+      @cell_size_lon = pj_grid_info[:cs_lon]
+      @cell_size_lat = pj_grid_info[:cs_lat]
+    end
+  end
+end

data/lib/proj/life_span.rb

@@ -0,0 +1,21 @@
+module Proj
+  # Tracks whether a PROJ context is still alive. Shared between a Context and
+  # the finalizers of objects that depend on it (PjObject, Session). Because
+  # Ruby's GC finalizer ordering is non-deterministic during shutdown, a
+  # dependent's finalizer may run after its context has already been destroyed.
+  # Calling proj_destroy() in that situation segfaults (PROJ 9.8+). This object
+  # lets dependents check before calling into PROJ.
+  class LifeSpan
+    def initialize
+      @alive = true
+    end
+
+    def alive?
+      @alive
+    end
+
+    def ended!
+      @alive = false
+    end
+  end
+end

data/lib/proj/network_api_callbacks.rb

@@ -0,0 +1,86 @@
+module Proj
+  # Include this module in a class to create a custom network API for PROJ.
+  # Install it via {Context#set_network_api}.
+  #
+  # The including class must call {#install_callbacks} in its initializer and
+  # implement the following methods:
+  #
+  # * +open(uri, offset, size_to_read)+ - Open a network connection and perform
+  #   the initial read. Return a connection object (any Ruby object) that holds
+  #   the connection state, along with the data read. The return value must be a
+  #   Hash with at least a +:data+ key containing the bytes read.
+  # * +close(connection)+ - Close the network connection.
+  # * +header_value(connection, header_name)+ - Return the value of a response header.
+  # * +read_range(connection, offset, size_to_read)+ - Read a range of bytes, return a String.
+  #
+  # The +connection+ parameter passed to close/header_value/read_range is whatever
+  # object your +open+ method returned.
+  module NetworkApiCallbacks
+    def install_callbacks(context)
+      @open_cbk = self.method(:open_callback)
+      @close_cbk = self.method(:close_callback)
+      @header_value_cbk = self.method(:header_value_callback)
+      @read_range_cbk = self.method(:read_range_callback)
+
+      # Maps native address -> {proj_handle:, connection:, header_ptrs: []}
+      # Retaining proj_handle prevents the MemoryPointer from being GCed
+      # while PROJ holds the address. header_ptrs retains string pointers
+      # returned by header_value_callback.
+      @network_handles = {}
+
+      result = Api.proj_context_set_network_callbacks(context, @open_cbk, @close_cbk, @header_value_cbk, @read_range_cbk, nil)
+
+      if result != 1
+        Error.check_object(self)
+      end
+    end
+
+    def open_callback(context, url, offset, size_to_read, buffer, out_size_read, error_string_max_size, out_error_string, user_data)
+      uri = URI.parse(url)
+      connection = self.open(uri, offset, size_to_read)
+      out_size = [size_to_read, connection[:data].size].min
+      out_size_read.write(:size_t, out_size)
+      buffer.write_bytes(connection[:data], 0, out_size)
+
+      register_handle(connection)
+    end
+
+    def close_callback(context, handle, user_data)
+      connection = handle_to_connection(handle)
+      self.close(connection)
+      unregister_handle(handle)
+    end
+
+    def header_value_callback(context, handle, header_name, user_data)
+      connection = handle_to_connection(handle)
+      value = self.header_value(connection, header_name)
+      ptr = FFI::MemoryPointer.from_string(value)
+      @network_handles[handle.address][:header_ptrs] << ptr
+      ptr
+    end
+
+    def read_range_callback(context, handle, offset, size_to_read, buffer, error_string_max_size, out_error_string, user_data)
+      connection = handle_to_connection(handle)
+      data = self.read_range(connection, offset, size_to_read)
+      out_size = [size_to_read, data.size].min
+      buffer.write_bytes(data, 0, out_size)
+      out_size
+    end
+
+    private
+
+    def register_handle(connection)
+      proj_handle = FFI::MemoryPointer.new(:pointer)
+      @network_handles[proj_handle.address] = { proj_handle: proj_handle, connection: connection, header_ptrs: [] }
+      proj_handle
+    end
+
+    def handle_to_connection(handle)
+      @network_handles[handle.address][:connection]
+    end
+
+    def unregister_handle(handle)
+      @network_handles.delete(handle.address)
+    end
+  end
+end

data/lib/proj/operation.rb

@@ -1,43 +1,67 @@
-module Proj
-  class Operation
-    attr_reader :id, :description
-
-    def self.list
-      pointer_to_array = FFI::Pointer.new(Api::PJ_LIST, Api.proj_list_operations)
-      result = Array.new
-      0.step do |i|
-        operation_info = Api::PJ_LIST.new(pointer_to_array[i])
-        break result if operation_info[:id].nil?
-        id = operation_info[:id]
-        description = operation_info[:descr].read_pointer.read_string.force_encoding('UTF-8')
-        result << self.new(id, description)
-      end
-      result
-    end
-
-    def self.get(id)
-      self.list.find {|operation| operation.id == id}
-    end
-
-    def initialize(id, description)
-      @id = id
-      @description = description
-    end
-
-    def <=>(other)
-      self.id <=> other.id
-    end
-
-    def ==(other)
-      self.id == other.id
-    end
-
-    def to_s
-      self.id
-    end
-    
-    def inspect
-      "#<#{self.class} id=\"#{id}\", major=\"#{major}\", ell=\"#{ell}\", name=\"#{name}\">"
-    end
-  end
+module Proj
+  # Represents a PROJ operation (projection or conversion method).
+  # Each operation has an identifier and a human-readable description.
+  #
+  # @example List all operations
+  #   operations = Proj::Operation.list
+  #   operations.each { |op| puts "#{op.id}: #{op.description}" }
+  #
+  # @example Find a specific operation
+  #   op = Proj::Operation.get("aea")
+  #   puts op.description  #=> "Albers Equal Area"
+  class Operation
+    # @!attribute [r] id
+    #   @return [String] The operation identifier (e.g., "aea", "merc")
+    # @!attribute [r] description
+    #   @return [String] Human-readable description of the operation
+    attr_reader :id, :description
+
+    # Returns a list of all available operations.
+    #
+    # @return [Array<Operation>]
+    def self.list
+      pointer_to_array = FFI::Pointer.new(Api::PjList, Api.proj_list_operations)
+      result = Array.new
+      0.step do |i|
+        operation_info = Api::PjList.new(pointer_to_array[i])
+        break result if operation_info[:id].nil?
+        id = operation_info[:id]
+        description = operation_info[:descr].read_pointer.read_string.force_encoding('UTF-8')
+        result << self.new(id, description)
+      end
+      result
+    end
+
+    # Finds an operation by its identifier.
+    #
+    # @param id [String] The operation identifier to search for
+    #
+    # @return [Operation, nil] The matching operation or nil if not found
+    def self.get(id)
+      self.list.find {|operation| operation.id == id}
+    end
+
+    # Creates a new Operation.
+    #
+    # @param id [String] The operation identifier
+    # @param description [String] Human-readable description
+    #
+    # @return [Operation]
+    def initialize(id, description)
+      @id = id
+      @description = description
+    end
+
+    def ==(other)
+      self.id == other.id
+    end
+
+    def to_s
+      self.id
+    end
+
+    def inspect
+      "#<#{self.class} id=\"#{id}\", description=\"#{description}\">"
+    end
+  end
 end

data/lib/proj/operation_factory_context.rb

@@ -21,7 +21,9 @@ module Proj
     #                    If authority is a non-empty string different of "any", then coordinate
     #                    operations will be searched only in that authority namespace.
     def initialize(context, authority: nil)
-      @pointer = Api.proj_create_operation_factory_context(context, authority)
+      @context = context || Context.current
+      Error.validate_context!(@context)
+      @pointer = Api.proj_create_operation_factory_context(@context, authority)
       ObjectSpace.define_finalizer(self, self.class.finalize(@pointer))
     end
 
@@ -134,4 +136,4 @@ module Proj
       @pointer
     end
   end
-end
+end