xlsx_drone 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8555cd4364e05902cd79fcd328a43ff23f694193291bbb6cbcdb1515cddfd2d2
+  data.tar.gz: 8812b80c1c535f14ea3968a6f1e5b4e2854d3ef5531d7a9a7ebe18030e248368
+SHA512:
+  metadata.gz: 850d6628ac744ab5d5ff85aea37fa8368a43ccd583abebb16bbc3004333d9925683b367a9f5bf1984f680d5053e476a43303ce9512e6b1cc3d90f984b521b645
+  data.tar.gz: 8ab46bb4c07eee9375eea43ea08db2eaa487990737d371f833259d35483cc8ca6992595e1d64e8d65e0227e09c80babbac296b4d1b602e2e92bc54974151aab1

data/lib/xlsx_drone.rb

@@ -0,0 +1,17 @@
+# external libraries
+require 'ffi'
+
+# source code
+require_relative 'xlsx_drone/exceptions'
+require_relative 'xlsx_drone/native_binding'
+require_relative 'xlsx_drone/xlsx_drone'
+require_relative 'xlsx_drone/workbook'
+require_relative 'xlsx_drone/sheet'
+
+# turn off err printing from the native library
+XLSXDrone::NativeBinding.xlsx_set_print_err_messages(0)
+
+# ensure that all opened workbooks get closed (if can't OS will claim it anyways, just filling a duty here)
+at_exit do
+  XLSXDrone::Workbook.close_workbooks()
+end

data/lib/xlsx_drone/exceptions.rb

@@ -0,0 +1,42 @@
+# Exceptions defs.
+module XLSXDrone
+
+  # Errors caused by the user because of doing something invalid or not allowed.
+  module UserError
+
+    # May happen on xlsx_load_sheet().
+    class IndexOutOfBounds < RuntimeError; end
+
+    # May happen on xlsx_load_sheet().
+    class NonExistent < RuntimeError; end
+    
+    # May happen when try to interact with a workbook already closed.
+    class WorkbookClosed < RuntimeError; end
+  end
+
+  # Errors caused by the system itself.
+  module LogicError
+
+    # Errors on the library itself.
+    module InternalError
+
+      # May happen on xlsx_open().
+      class CantDeployFile < RuntimeError; end
+
+      # May happen on xlsx_open(), xlsx_load_sheet().
+      class XMLParsingError < RuntimeError; end
+    end
+
+    # Caused because of wrong use of the library.
+    module ClientError
+
+      # May happen on xlsx_load_sheet().
+      class MalformedParams < RuntimeError; end
+    end
+  end
+
+  # Something is flooded or temporary offline, usually the user is suggested to try later.
+  module TransientFailure
+
+  end
+end

data/lib/xlsx_drone/native_binding.rb

@@ -0,0 +1,76 @@
+# Namespace (protector) of the library.
+module XLSXDrone
+  
+  # All things related to the binding with the native C library.
+  module NativeBinding
+    
+    PLATFORM_X64 = RUBY_PLATFORM.match(/64/) ? true : false
+    EXT_PATH = "#{File.dirname(File.dirname(File.dirname(__FILE__)))}/ext"
+    DLL_PATH = PLATFORM_X64 ? "#{EXT_PATH}/xlsx_drone_x64.dll" : "#{EXT_PATH}/xlsx_drone_x86.dll"
+    
+    class XLSXWorkbookT < FFI::Struct
+      
+      layout \
+        :deployment_path, :pointer,
+        :shared_strings_xml, :pointer,
+        :n_styles, :int,
+        :styles, :pointer,
+        :n_sheets, :int,
+        :sheets, :pointer
+    end
+    
+    class XLSXStyleT < FFI::Struct
+      
+      layout \
+        :style_id, :int,
+        :related_category, :int,
+        :format_code, :pointer
+    end
+    
+    class XLSXReferenceToRowT < FFI::Struct
+      
+      layout \
+        :row_n, :int,
+        :sheetdata_child_i, :int
+    end
+    
+    class XLSXSheetT < FFI::Struct
+      
+      layout \
+        :xlsx, :pointer,
+        :name, :pointer,
+        :sheet_xml, :pointer,
+        :sheetdata, :pointer,
+        :last_row, :int,
+        :last_row_looked, XLSXReferenceToRowT
+    end
+    
+    class XLSXCellValue < FFI::Union
+      
+      layout \
+        :pointer_to_char_value, :pointer,
+        :int_value, :int,
+        :long_long_value, :long_long,
+        :double_value, :double
+    end
+    
+    class XLSXCellT < FFI::Struct
+      
+      layout \
+        :style, :pointer,
+        :value_type, :int,
+        :value, XLSXCellValue
+    end
+    
+    extend FFI::Library
+    ffi_lib DLL_PATH
+    
+    # function attachings
+    attach_function :xlsx_get_xlsx_errno, [], :int
+    attach_function :xlsx_set_print_err_messages, [:int], :void
+    attach_function :xlsx_open, [:string, :pointer], :int
+    attach_function :xlsx_load_sheet, [:pointer, :int, :string], :pointer
+    attach_function :xlsx_read_cell, [:pointer, :uint, :string, :pointer], :void
+    attach_function :xlsx_close, [:pointer], :int
+  end
+end

data/lib/xlsx_drone/sheet.rb

@@ -0,0 +1,108 @@
+# Namespace (protector) of the library.
+module XLSXDrone
+
+  # XLSX Sheet.
+  class Sheet
+
+    # @return [XLSXDrone::Sheet]
+    def initialize(xlsx_sheet_mpointer)
+      @native_sheet = XLSXDrone::NativeBinding::XLSXSheetT.new(xlsx_sheet_mpointer)
+      @native_cell = XLSXDrone::NativeBinding::XLSXCellT.new(FFI::MemoryPointer.new(1, XLSXDrone::NativeBinding::XLSXCellT.size, true))
+      @styles = {}
+    end
+
+    # @return [Integer] 0 if the sheet is empty
+    def last_row
+      @native_sheet[:last_row]
+    end
+
+    # @return [String]
+    def name
+      @native_sheet[:name].get_string(0).force_encoding(Encoding::UTF_8)
+    end
+    
+    # @param row [Integer]
+    # @param column [String]
+    # @return [Integer, Float, String, Time, NilClass]
+    def read_cell(row, column)
+      XLSXDrone::NativeBinding.xlsx_read_cell(@native_sheet, row, column, @native_cell)
+      # if it has no style, then it's either a string or a number
+      if(@native_cell[:style].null?)
+        case @native_cell[:value_type]
+          when 0
+            @native_cell[:value][:pointer_to_char_value].get_string(0).force_encoding(Encoding::UTF_8)
+          when 1
+            @native_cell[:value][:int_value]
+          when 2
+            @native_cell[:value][:long_long_value]
+          when 3
+            @native_cell[:value][:double_value]
+          else
+            nil
+        end
+      else
+        address = @native_cell[:style].address
+        # speeding purpose
+        if(!(@styles.has_key?(address)))
+          style_obj = XLSXDrone::NativeBinding::XLSXStyleT.new(@native_cell[:style])
+          @styles[address] = style_obj[:related_category]
+        end
+        case @styles[address]
+          when 2
+            # XLSX_DATE, it could be represented also as plain string
+            if(@native_cell[:value_type] == 0)
+              @native_cell[:value][:pointer_to_char_value].get_string(0).force_encoding(Encoding::UTF_8)
+            else
+              Time.new(1900) + ((@native_cell[:value][:int_value] - 2) * 86400)
+            end
+          when 4
+            # XLSX_DATE_TIME, there are specific cases in which it's a DATE_TIME, but the internal representation appears as an int, so basically
+            # the "time" part of the data comes fixed at mid-day or at the start of the day, that's what you actually see on Excel
+            case(@native_cell[:value_type])
+              when 0
+                @native_cell[:value][:pointer_to_char_value].get_string(0).force_encoding(Encoding::UTF_8)
+              when 1
+                Time.new(1900) + ((@native_cell[:value][:int_value] - 2) * 86400)
+              else
+                match = @native_cell[:value][:double_value].to_s.match(/(\d+)\.(\d+)/)
+                integral_part = match[1].to_i
+                floating_part = "0.#{match[2]}".to_f
+                Time.new(1900) + ((integral_part - 2) * 86400) + (floating_part * 86400)
+            end
+          when 0
+            # XLSX_NUMBER
+            case @native_cell[:value_type]
+              when 1
+                @native_cell[:value][:int_value]
+              when 2
+                @native_cell[:value][:long_long_value]
+              when 3
+                @native_cell[:value][:double_value]
+              else
+                nil
+            end
+          when 1
+            # XLSX_TEXT
+            @native_cell[:value][:pointer_to_char_value].get_string(0).force_encoding(Encoding::UTF_8)
+          when 3
+            # XLSX_TIME
+            (Time.new(1900) + (@native_cell[:value][:double_value] * 86400)).strftime("%H:%M:%S")
+          else
+            # XLSX_UNKNOWN
+            case @native_cell[:value_type]
+              when 0
+                @native_cell[:value][:pointer_to_char_value].get_string(0).force_encoding(Encoding::UTF_8)
+              when 1
+                @native_cell[:value][:int_value]
+              when 2
+                @native_cell[:value][:long_long_value]
+              when 3
+                @native_cell[:value][:double_value]
+              else
+                nil
+            end
+        end
+      end
+    end
+  end
+end

data/lib/xlsx_drone/workbook.rb

@@ -0,0 +1,76 @@
+# Namespace (protector) of the library.
+module XLSXDrone
+
+  # XLSX Workbook.
+  class Workbook
+    
+    @@opened_workbooks = []
+
+    # You could use this method to close all opened workbooks at the same time.
+    def self.close_workbooks
+      @@opened_workbooks.each do |wb|
+        wb.close
+      end
+    end
+    
+    # @param xlsx_workbook_mpointer [FFI::MemoryPointer]
+    # @return [Workbook]
+    def initialize(xlsx_workbook_mpointer)
+      @native_workbook = XLSXDrone::NativeBinding::XLSXWorkbookT.new(xlsx_workbook_mpointer)
+      @@opened_workbooks << self
+    end
+
+    # Sheets aren't loaded by default. You have to load them one by one, once you need them. You can *reference* a sheet passing its name or its index (first one is 1). Raises an exception if it can't for some reason.
+    # @param reference [String, Integer]
+    # @return [XLSXDrone::Sheet]
+    def load_sheet(reference)
+      if(@native_workbook)
+        loaded_sheet = \
+          case reference
+            when String
+              XLSXDrone::NativeBinding.xlsx_load_sheet(@native_workbook, 0, reference)
+            when Integer
+              XLSXDrone::NativeBinding.xlsx_load_sheet(@native_workbook, reference, nil)
+            else
+              raise XLSXDrone::LogicError::ClientError::MalformedParams, "Pass a valid index as an #Integer (> 0 && <= #sheets_amount()), or a valid sheet name as a #String."
+          end
+        if(!loaded_sheet.null?)
+          XLSXDrone::Sheet.new(loaded_sheet)
+        else
+          # no sheet was loaded
+          case XLSXDrone::NativeBinding.xlsx_get_xlsx_errno()
+            when -11
+              raise XLSXDrone::LogicError::ClientError::MalformedParams, "Pass a valid index (> 0 && <= #sheets_amount()), or a valid sheet name."
+            when -12
+              raise NoMemoryError
+            when -13
+              raise XLSXDrone::UserError::IndexOutOfBounds, "If you pass an integer as parameter, note that can't surpass #sheets_amount()."
+            when -14
+              raise XLSXDrone::LogicError::InternalError::XMLParsingError, "The XLSX may be corrupted or it belongs to a version unsupported by this library."
+            when -15
+              raise XLSXDrone::UserError::NonExistent, "There's not such sheet with that name."
+          end
+        end
+      else
+        raise XLSXDrone::UserError::WorkbookClosed, "The workbook you're trying to access was already closed."
+      end
+    end
+    
+    # @return [Integer] the amount of sheets contained on this workbook
+    def sheets_amount
+      @native_workbook[:n_sheets]
+    end
+
+    # Should-call method, once you finish working with the workbook.
+    # @return [TrueClass, FalseClass] depending on if the close was successful or not
+    def close
+      if(XLSXDrone::NativeBinding.xlsx_close(@native_workbook) == 1)
+        @@opened_workbooks.delete(self)
+        @native_workbook = nil
+        true
+      else
+        false
+      end
+    end
+  end
+end

data/lib/xlsx_drone/xlsx_drone.rb

@@ -0,0 +1,27 @@
+# Namespace (protector) and #open() functionallity for the library.
+module XLSXDrone
+  
+  # @param path [String]
+  # @return [XLSXDrone::Workbook]
+  # Opens an XLSX file, should be closed after working with him. Can raise several exceptions.
+  def self.open(path)
+    # check that the *path* is always a #String
+    raise XLSXDrone::LogicError::ClientError::MalformedParams, "A #String is expected." if(!path.is_a?(String))
+    # reserve memory for an xlsx_workbook struct
+    xlsx_workbook_mpointer = FFI::MemoryPointer.new(1, XLSXDrone::NativeBinding::XLSXWorkbookT.size, false)
+    if(XLSXDrone::NativeBinding.xlsx_open(File.absolute_path(path), xlsx_workbook_mpointer) == 1)
+      # everything went ok
+      XLSXDrone::Workbook.new(xlsx_workbook_mpointer)
+    else
+      # something went wrong
+      case XLSXDrone::NativeBinding.xlsx_get_xlsx_errno()
+        when -2
+          raise NoMemoryError
+        when -3
+          raise XLSXDrone::LogicError::InternalError::CantDeployFile, "Can't deploy #{path}. Check that the file isn't already opened.unl"
+        when -4
+          raise XLSXDrone::LogicError::InternalError::XMLParsingError, "The XLSX may be corrupted or it belongs to a version unsupported by this library."
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: xlsx_drone
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Damián M. González
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-01-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ext/xlsx_drone_x64.dll
+- ext/xlsx_drone_x86.dll
+- lib/xlsx_drone.rb
+- lib/xlsx_drone/exceptions.rb
+- lib/xlsx_drone/native_binding.rb
+- lib/xlsx_drone/sheet.rb
+- lib/xlsx_drone/workbook.rb
+- lib/xlsx_drone/xlsx_drone.rb
+homepage: https://github.com/damian-m-g/xlsx_drone_rb
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: '2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: Fast Microsoft Excel's XLSX reader. Binding of C's xlsx_drone lib.
+test_files: []