ffi-gphoto2 0.4.1 → 0.5.0

data/lib/gphoto2/camera.rb

@@ -1,9 +1,24 @@
 module GPhoto2
   class Camera
     include FFI::GPhoto2
+    include GPhoto2::Struct
 
-    attr_reader :context, :model, :port
+    include Capture
+    include Configuration
+    include Event
+    include Filesystem
 
+    # @return [String]
+    attr_reader :model
+
+    # @return [String]
+    attr_reader :port
+
+    # @example
+    #   cameras = GPhoto2::Camera.all
+    #   # => [#<GPhoto2::Camera>, #<GPhoto2::Camera>, ...]
+    #
+    # @return [Array<GPhoto2::Camera>] a list of all available devices
     def self.all
       context = Context.new
 
@@ -20,37 +35,74 @@ module GPhoto2
       entries
     end
 
-    def self.first
+    # @example
+    #   camera = GPhoto2::Camera.first
+    #
+    #   begin
+    #     # ...
+    #   ensure
+    #     camera.finalize
+    #   end
+    #
+    #   # Alternatively, pass a block, which will automatically close the camera.
+    #   GPhoto2::Camera.first do |camera|
+    #     # ...
+    #   end
+    #
+    # @return [GPhoto2::Camera] the first detected camera
+    # @raise [RuntimeError] when no devices are detected
+    def self.first(&blk)
       entries = all
       raise RuntimeError, 'no devices detected' if entries.empty?
-      entries.first
-    end
-
-    def self.open(model, port)
+      camera = entries.first
+      autorelease(camera, &blk)
+   end
+
+    # @example
+    #   model = 'Nikon DSC D5100 (PTP mode)'
+    #   port = 'usb:250,006'
+    #
+    #   camera = GPhoto2::Camera.open(model, port)
+    #
+    #   begin
+    #     # ...
+    #   ensure
+    #     camera.finalize
+    #   end
+    #
+    #   # Alternatively, pass a block, which will automatically close the camera.
+    #   GPhoto2::Camera.open(model, port) do |camera|
+    #     # ...
+    #   end
+    #
+    # @param [String] model
+    # @param [String] port
+    # @return [GPhoto2::Camera]
+    def self.open(model, port, &blk)
       camera = new(model, port)
-
-      if block_given?
-        begin
-          yield camera
-        ensure
-          camera.finalize
-        end
-      else
-        camera
-      end
+      autorelease(camera, &blk)
     end
 
+    # @example
+    #   # Find the cameras whose model names contain Nikon.
+    #   cameras = GPhoto2::Camera.where(model: /nikon/i)
+    #
+    # @param [Hash] condition
+    # @return [Array<GPhoto2::Camera>]
     def self.where(condition)
       name = condition.keys.first
       pattern = condition.values.first
       all.select { |c| c.send(name).match(pattern) }
     end
 
+    # @param [String] model
+    # @param [String] port
     def initialize(model, port)
+      super
       @model, @port = model, port
-      @dirty = false
     end
 
+    # @return [void]
     def finalize
       @context.finalize if @context
       @window.finalize if @window
@@ -58,111 +110,59 @@ module GPhoto2
     end
     alias_method :close, :finalize
 
+    # @return [void]
     def exit
       _exit
     end
 
-    def capture(type = :image)
-      save
-      path = _capture(type)
-      CameraFile.new(self, path.folder, path.name)
-    end
-
-    def preview
-      save
-      capture_preview
-    end
-
-    # timeout in milliseconds
-    def wait(timeout = 2000)
-      wait_for_event(timeout)
-    end
-
-    def wait_for(event_type)
-      begin
-        event = wait
-      end until event.type == event_type
-
-      event
-    end
-
+    # @return [FFI::GPhoto::Camera]
     def ptr
       @ptr || (init && @ptr)
     end
 
+    # @return [GPhoto2::CameraAbilities]
     def abilities
       @abilities || (init && @abilities)
     end
 
+    # @return [GPhoto2::PortInfo]
     def port_info
       @port_info || (init && @port_info)
     end
 
+    # @return [GPhoto2::Context]
     def context
       @context ||= Context.new
     end
 
-    def window
-      @window ||= get_config
-    end
-
-    def config
-      @config ||= window.flatten
-    end
-
-    def filesystem(root = '/')
-      root = "/#{root}" if root[0] != '/'
-      CameraFolder.new(self, root)
-    end
-    alias_method :/, :filesystem
-
-    def file(file)
-      file_get(file)
-    end
-
-    def delete(file)
-      file_delete(file)
-    end
-
-    def [](key)
-      config[key.to_s]
-    end
-
-    def []=(key, value)
-      self[key].value = value
-      @dirty = true
-      value
-    end
-
-    def update(attributes = {})
-      attributes.each do |key, value|
-        self[key] = value
-      end
-
-      save
-    end
-
-    def dirty?
-      @dirty
-    end
-
+    # @example
+    #   camera.can? :capture_image
+    #   # => true
+    #
+    # @param [CameraOperation] operation
+    # @return [Boolean]
     def can?(operation)
       (abilities[:operations] & CameraOperation[operation]) != 0
     end
 
-    def save
-      return false unless dirty?
-      set_config
-      @dirty = false
-      true
-    end
+    private
 
-    def to_ptr
-      @ptr
+    # Ensures the given camera is finalized when passed a block.
+    #
+    # If no block is given, the camera is returned and the caller must must
+    # manually close it.
+    def self.autorelease(camera)
+      if block_given?
+        begin
+          yield camera
+        ensure
+          camera.finalize
+        end
+      else
+        camera
+      end
     end
 
-    private
-
     def init
       new
       set_abilities(CameraAbilities.find(@model))
@@ -193,80 +193,9 @@ module GPhoto2
       @abilities = abilities
     end
 
-    def _capture(type)
-      path = CameraFilePath.new
-      rc = gp_camera_capture(ptr, type, path.ptr, context.ptr)
-      GPhoto2.check!(rc)
-      path
-    end
-
-    def capture_preview
-      file = CameraFile.new(self)
-      rc = gp_camera_capture_preview(ptr, file.ptr, context.ptr)
-      GPhoto2.check!(rc)
-      file
-    end
-
-    def get_config
-      widget_ptr = FFI::MemoryPointer.new(FFI::GPhoto2::CameraWidget)
-      rc = gp_camera_get_config(ptr, widget_ptr, context.ptr)
-      GPhoto2.check!(rc)
-      widget = FFI::GPhoto2::CameraWidget.new(widget_ptr.read_pointer)
-      CameraWidget.factory(widget)
-    end
-
-    def set_config
-      rc = gp_camera_set_config(ptr, window.ptr, context.ptr)
-      GPhoto2.check!(rc)
-    end
-
-    def file_get(file, type = :normal)
-      rc = gp_camera_file_get(ptr, file.folder, file.name, type, file.ptr, context.ptr)
-      GPhoto2.check!(rc)
-      file
-    end
-
-    def file_delete(file)
-      rc = gp_camera_file_delete(ptr, file.folder, file.name, context.ptr)
-      GPhoto2.check!(rc)
-    end
-
     def unref
       rc = gp_camera_unref(ptr)
       GPhoto2.check!(rc)
     end
-
-    def wait_for_event(timeout)
-      # assume CameraEventType is an int
-      type = FFI::MemoryPointer.new(:int)
-
-      data = FFI::MemoryPointer.new(:pointer)
-      data_ptr = FFI::MemoryPointer.new(:pointer)
-      data_ptr.write_pointer(data)
-
-      rc = gp_camera_wait_for_event(ptr, timeout, type, data_ptr, context.ptr)
-      GPhoto2.check!(rc)
-
-      type = CameraEventType[type.read_int]
-      data = data_ptr.read_pointer
-
-      data =
-        case type
-        when :unknown
-          data.null? ? nil : data.read_string
-        when :file_added
-          path_ptr = FFI::GPhoto2::CameraFilePath.new(data)
-          path = CameraFilePath.new(path_ptr)
-          CameraFile.new(self, path.folder, path.name)
-        when :folder_added
-          path_ptr = FFI::GPhoto2::CameraFilePath.new(data)
-          path = CameraFilePath.new(path_ptr)
-          CameraFolder.new(self, '%s/%s' % [path.folder, path.name])
-        else
-          nil
-        end
-
-      CameraEvent.new(type, data)
-    end
   end
 end

data/lib/gphoto2/camera_abilities.rb

@@ -1,9 +1,10 @@
 module GPhoto2
   class CameraAbilities
     include FFI::GPhoto2
+    include GPhoto2::Struct
 
-    attr_reader :ptr
-
+    # @param [String] model the name of the device
+    # @return [GPhoto2::CameraAbilities]
     def self.find(model)
       context = Context.new
 
@@ -16,20 +17,19 @@ module GPhoto2
       abilities
     end
 
+    # @param [GPhoto2::CameraAbilitiesList] camera_abilities_list
+    # @param [Integer] index
     def initialize(camera_abilities_list, index)
       @camera_abilities_list = camera_abilities_list
       @index = index
       get_abilities
     end
 
+    # @return [Object]
     def [](field)
       ptr[field]
     end
 
-    def to_ptr
-      @ptr
-    end
-
     private
 
     def get_abilities

data/lib/gphoto2/camera_abilities_list.rb

@@ -1,33 +1,34 @@
 module GPhoto2
   class CameraAbilitiesList
     include FFI::GPhoto2
+    include GPhoto2::Struct
 
-    attr_reader :ptr
-
+    # @param [GPhoto2::Context] context
     def initialize(context)
       @context = context
       new
       load
     end
 
+    # @return [GPhoto2::CameraList]
     def detect
       _detect
     end
 
+    # @param [String] model
+    # @return [Integer]
     def lookup_model(model)
       _lookup_model(model)
     end
     alias_method :index, :lookup_model
 
+    # @param [Integer] index
+    # @return [GPhoto2::CameraAbilities]
     def at(index)
       CameraAbilities.new(self, index)
     end
     alias_method :[], :at
 
-    def to_ptr
-      @ptr
-    end
-
     private
 
     def new

data/lib/gphoto2/camera_event.rb

@@ -1,10 +1,3 @@
 module GPhoto2
-  class CameraEvent
-    attr_reader :type, :data
-
-    def initialize(type, data)
-      @type = type
-      @data = data
-    end
-  end
+  CameraEvent = ::Struct.new(:type, :data)
 end

data/lib/gphoto2/camera_file.rb

@@ -1,39 +1,49 @@
 module GPhoto2
   class CameraFile
     include FFI::GPhoto2
+    include GPhoto2::Struct
 
-    attr_reader :folder, :name, :ptr
+    # @return [String]
+    attr_reader :folder
 
+    # @return [String]
+    attr_reader :name
+
+    # @param [GPhoto2::Camera] camera
+    # @param [String] folder
+    # @param [String] name
     def initialize(camera, folder = nil, name = nil)
       @camera = camera
       @folder, @name = folder, name
       new
     end
 
+    # @return [Boolean]
     def preview?
       @folder.nil? && @name.nil?
     end
 
+    # @param [String] pathname
+    # @return [Integer] the number of bytes written
     def save(pathname = default_filename)
       File.binwrite(pathname, data)
     end
 
+    # @return [void]
     def delete
       @camera.delete(self)
     end
 
+    # @return [String]
     def data
       data_and_size.first
     end
 
+    # @return [Integer]
     def size
       data_and_size.last
     end
 
-    def to_ptr
-      @ptr
-    end
-
     private
 
     def data_and_size