xlsxrb 0.1.7 → 0.1.9

data/sig/generated/xlsxrb/elements/worksheet.rbs

@@ -2,33 +2,138 @@
 
 module Xlsxrb
   module Elements
-    # Represents a single worksheet in a workbook.
+    # Represents a single fully parsed, in-memory worksheet in a workbook.
+    # Provides coordinate random access (sheet["A1"]), row lookups (row_at),
+    # and immutable cell updates (update_cell).
     #
     # @example Access cells and rows
-    #   sheet = workbook.sheet(0)
+    #   sheet = workbook.sheet(0).load
     #   cell = sheet["A1"]
-    #   sheet.each_row { |row| puts row.to_a.inspect }
+    #   row = sheet.row_at(0)
     #
     # @api public
-    class Worksheet < Data
-      attr_reader name(): untyped
+    class Worksheet
+      attr_reader name: untyped
 
-      attr_reader rows(): untyped
+      attr_reader rows: untyped
 
-      attr_reader columns(): untyped
+      attr_reader columns: untyped
 
-      attr_reader charts(): untyped
+      attr_reader charts: untyped
 
-      attr_reader unmapped_data(): untyped
+      attr_reader unmapped_data: untyped
 
-      attr_reader errors(): untyped
+      attr_reader errors: untyped
 
-      def self.new: (untyped name, untyped rows, untyped columns, untyped charts, untyped unmapped_data, untyped errors) -> instance
-                  | (name: untyped, rows: untyped, columns: untyped, charts: untyped, unmapped_data: untyped, errors: untyped) -> instance
+      # @param name [String] The worksheet name (max 31 characters).
+      # @param rows [Array<Elements::Row>] Rows in the sheet.
+      # @param columns [Array<Elements::Column>] Column definitions.
+      # @param charts [Array<Hash>] Charts in the sheet.
+      # @param unmapped_data [Hash] Additional metadata for round-tripping.
+      # @param errors [Array<String>, nil] Validation errors.
+      # : (name: String?, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
+      def initialize: (name: String?, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
 
-      def self.members: () -> [ :name, :rows, :columns, :charts, :unmapped_data, :errors ]
+      # Iterate over rows in the worksheet.
+      #
+      # @example
+      #   sheet.each do |row|
+      #     puts row.to_a.inspect
+      #   end
+      #
+      # @yield [row]
+      # @yieldparam row [Elements::Row]
+      # @return [Enumerator, void]
+      # @api public
+      # : () { (Elements::Row) -> void } -> void
+      # : () -> Enumerator[Elements::Row, void]
+      def each: () { (Elements::Row) -> void } -> void
+              | () -> Enumerator[Elements::Row, void]
 
-      def members: () -> [ :name, :rows, :columns, :charts, :unmapped_data, :errors ]
+      # Iterate over rows in the worksheet.
+      #
+      # @example
+      #   sheet.each_row do |row|
+      #     puts "Row #{row.index}: #{row.to_a.inspect}"
+      #   end
+      #
+      # @yield [row]
+      # @yieldparam row [Elements::Row]
+      # @return [Enumerator, void]
+      # @api public
+      # : () { (Elements::Row) -> void } -> void
+      # : () -> Enumerator[Elements::Row, void]
+      def each_row: () { (Elements::Row) -> void } -> void
+                  | () -> Enumerator[Elements::Row, void]
+
+      # Iterate over all cells across rows.
+      #
+      # @yield [cell]
+      # @yieldparam cell [Elements::Cell]
+      # @return [Enumerator, void]
+      # @api public
+      # : () { (Elements::Cell) -> void } -> void
+      # : () -> Enumerator[Elements::Cell, void]
+      def each_cell: () { (Elements::Cell) -> void } -> void
+                   | () -> Enumerator[Elements::Cell, void]
+
+      # Returns whether the worksheet is valid according to OOXML specifications.
+      #
+      # @return [Boolean]
+      # : () -> bool
+      def valid?: () -> bool
+
+      # Returns a new Worksheet with the specified cell updated.
+      #
+      # @example
+      #   new_sheet = sheet.update_cell("B1", value: "Updated")
+      #
+      # @param ref [String] The cell reference (e.g. "B1").
+      # @param value [Object] The new cell value.
+      # @param style_index [Integer, String, nil] Optional new style index.
+      # @param formula [Elements::Formula, nil] Optional new formula.
+      # @return [Worksheet] A new Worksheet instance.
+      # @api public
+      # : (String ref, ?value: untyped, ?style_index: Integer | String | nil, ?formula: Elements::Formula?) -> Elements::Worksheet
+      def update_cell: (String ref, ?value: untyped, ?style_index: Integer | String | nil, ?formula: Elements::Formula?) -> Elements::Worksheet
+
+      # Returns a new Worksheet with attributes replaced (Data-like behavior).
+      #
+      # @param changes [Hash]
+      # @return [Worksheet]
+      # @api public
+      # : (**untyped) -> Elements::Worksheet
+      def with: (**untyped) -> Elements::Worksheet
+
+      # Support pattern matching.
+      # : (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, untyped]
+
+      # Compare worksheets for equality.
+      # : (untyped other) -> bool
+      def ==: (untyped other) -> bool
+
+      alias eql? ==
+
+      # : () -> Integer
+      def hash: () -> Integer
+
+      # Returns self when load is called on an already in-memory Worksheet.
+      #
+      # @return [Elements::Worksheet]
+      # @api public
+      # : () -> Elements::Worksheet
+      def load: () -> Elements::Worksheet
+
+      alias to_worksheet load
+
+      # Validates worksheet name and rows against OOXML limits.
+      #
+      # @param name [String]
+      # @param rows [Array<Elements::Row>]
+      # @return [Array<String>] List of errors.
+      # : (untyped name, untyped rows) -> Array[String]
+      def self.validate: (untyped name, untyped rows) -> Array[String]
     end
   end
 end

data/sig/generated/xlsxrb/ooxml/cfb.rbs

@@ -0,0 +1,121 @@
+# Generated from lib/xlsxrb/ooxml/cfb.rb with RBS::Inline
+
+module Xlsxrb
+  module Ooxml
+    # Pure-Ruby Compound File Binary (CFB / OLE Structured Storage) implementation for [MS-CFB] / [MS-OFFCRYPTO].
+    module Cfb
+      MAGIC: untyped
+
+      FREESECT: ::Integer
+
+      ENDOFCHAIN: ::Integer
+
+      FATSECT: ::Integer
+
+      DIFATSECT: ::Integer
+
+      NOSTREAM: ::Integer
+
+      OBJ_UNKNOWN: ::Integer
+
+      OBJ_STORAGE: ::Integer
+
+      OBJ_STREAM: ::Integer
+
+      OBJ_ROOT: ::Integer
+
+      MINI_STREAM_CUTOFF: ::Integer
+
+      SECTOR_SIZE: ::Integer
+
+      MINI_SECTOR_SIZE: ::Integer
+
+      # Represents a directory entry in a Compound File.
+      class DirEntry
+        attr_accessor name: untyped
+
+        attr_accessor type: untyped
+
+        attr_accessor color: untyped
+
+        attr_accessor left_sibling_id: untyped
+
+        attr_accessor right_sibling_id: untyped
+
+        attr_accessor child_id: untyped
+
+        attr_accessor clsid: untyped
+
+        attr_accessor state_flags: untyped
+
+        attr_accessor created_time: untyped
+
+        attr_accessor modified_time: untyped
+
+        attr_accessor start_sector: untyped
+
+        attr_accessor size: untyped
+
+        attr_accessor entry_id: untyped
+
+        def initialize: (?name: untyped, ?type: untyped, ?start_sector: untyped, ?size: untyped) -> untyped
+
+        def stream?: () -> untyped
+
+        def root?: () -> untyped
+
+        def storage?: () -> untyped
+      end
+
+      # Reads streams from a Compound File Binary buffer.
+      class Reader
+        attr_reader entries: untyped
+
+        def self.cfb?: (untyped data) -> untyped
+
+        def initialize: (untyped data) -> untyped
+
+        def stream_names: () -> untyped
+
+        def read_stream: (untyped name) -> untyped
+
+        private
+
+        def parse_header: () -> untyped
+
+        def sector_offset: (untyped sector_id) -> untyped
+
+        def read_sector: (untyped sector_id) -> untyped
+
+        def build_fat: () -> untyped
+
+        def load_difat_and_fat: () -> untyped
+
+        def parse_directory: () -> untyped
+
+        def load_mini_stream: () -> untyped
+
+        def read_regular_stream_data: (untyped start_sector, untyped total_size) -> untyped
+
+        def read_mini_stream_data: (untyped start_mini_sector, untyped total_size) -> untyped
+      end
+
+      # Writes named streams into a Compound File Binary (v3, 512-byte sectors) format with Mini Stream support.
+      class Writer
+        def self.write: (untyped streams) -> untyped
+
+        def initialize: (untyped streams) -> untyped
+
+        def build: () -> untyped
+
+        private
+
+        def serialize_dir_entry: (untyped entry) -> untyped
+
+        def insert_entry_to_tree: (untyped entries, untyped root_node, untyped new_node) -> untyped
+
+        def compare_entry_names: (untyped a_name, untyped b_name) -> untyped
+      end
+    end
+  end
+end

data/sig/generated/xlsxrb/ooxml/crypto/agile.rbs

@@ -0,0 +1,46 @@
+# Generated from lib/xlsxrb/ooxml/crypto/agile.rb with RBS::Inline
+
+module Xlsxrb
+  module Ooxml
+    module Crypto
+      # Implements Microsoft Office Agile Encryption specified in [MS-OFFCRYPTO] Section 2.3.4.
+      class Agile
+        BLOCK_KEY_VERIFIER_INPUT: untyped
+
+        BLOCK_KEY_VERIFIER_VALUE: untyped
+
+        BLOCK_KEY_KEY: untyped
+
+        BLOCK_KEY_INTEGRITY_KEY: untyped
+
+        BLOCK_KEY_INTEGRITY_VALUE: untyped
+
+        SEGMENT_SIZE: ::Integer
+
+        # Decrypts an encrypted package given the EncryptionInfo stream data and EncryptedPackage stream data.
+        def self.decrypt: (untyped encryption_info_bytes, untyped encrypted_package_bytes, untyped password) -> untyped
+
+        # Encrypts a plain zip payload with the given password into EncryptionInfo and EncryptedPackage streams.
+        def self.encrypt: (untyped plain_bytes, untyped password) -> untyped
+
+        private def self.parse_encryption_info: (untyped bytes) -> untyped
+
+        private def self.digest_for: (untyped name) -> untyped
+
+        private def self.cipher_name_for: (untyped algo, untyped key_bits) -> untyped
+
+        private def self.derive_h_final: (untyped digest, untyped password, untyped salt, untyped spin_count) -> untyped
+
+        private def self.derive_key: (untyped digest, untyped h_final, untyped block_key, untyped key_bytes) -> untyped
+
+        private def self.aes_decrypt: (untyped cipher_name, untyped key, untyped init_vector, untyped data) -> untyped
+
+        private def self.aes_encrypt: (untyped cipher_name, untyped key, untyped init_vector, untyped data) -> untyped
+
+        private def self.aes_decrypt_block: (untyped cipher_name, untyped key, untyped init_vector, untyped data) -> untyped
+
+        private def self.aes_encrypt_block: (untyped cipher_name, untyped key, untyped init_vector, untyped data) -> untyped
+      end
+    end
+  end
+end

data/sig/generated/xlsxrb/ooxml/crypto/standard.rbs

@@ -0,0 +1,28 @@
+# Generated from lib/xlsxrb/ooxml/crypto/standard.rb with RBS::Inline
+
+module Xlsxrb
+  module Ooxml
+    module Crypto
+      # Implements Microsoft Office Standard Encryption specified in [MS-OFFCRYPTO] Section 2.3.6.
+      class Standard
+        CSP_NAME: untyped
+
+        ITERATION_COUNT: ::Integer
+
+        # Decrypts a Standard-encrypted package.
+        def self.decrypt: (untyped encryption_info_bytes, untyped encrypted_package_bytes, untyped password) -> untyped
+
+        # Encrypts plain zip data into Standard Encryption streams.
+        def self.encrypt: (untyped plain_bytes, untyped password) -> untyped
+
+        private def self.parse_encryption_info: (untyped bytes) -> untyped
+
+        private def self.derive_key: (untyped password, untyped salt, ?untyped block_num) -> untyped
+
+        private def self.aes_ecb_encrypt: (untyped key, untyped data) -> untyped
+
+        private def self.aes_ecb_decrypt: (untyped key, untyped data) -> untyped
+      end
+    end
+  end
+end

data/sig/generated/xlsxrb/ooxml/crypto.rbs

@@ -0,0 +1,17 @@
+# Generated from lib/xlsxrb/ooxml/crypto.rb with RBS::Inline
+
+module Xlsxrb
+  module Ooxml
+    # High-level encryption and decryption facade for [MS-OFFCRYPTO] Excel document protection.
+    module Crypto
+      # Checks if the binary data is an encrypted Compound File Binary package.
+      def self.encrypted?: (untyped data) -> untyped
+
+      # Decrypts an encrypted XLSX (CFB) package with the given password.
+      def self.decrypt: (untyped cfb_data, untyped password) -> untyped
+
+      # Encrypts a plain ZIP payload with the given password into an encrypted CFB package.
+      def self.encrypt: (untyped plain_zip_data, untyped password, ?mode: untyped) -> untyped
+    end
+  end
+end

data/sig/generated/xlsxrb/ooxml/worksheet_parser.rbs

@@ -62,6 +62,8 @@ module Xlsxrb
       def self.fast_scan_rows_direct: (untyped xml_src, untyped shared_strings, untyped part_name) ?{ (?) -> untyped } -> untyped
 
       def self.fast_parse_cells_direct: (untyped xml, untyped from, untyped to, untyped shared_strings, untyped row_source) -> untyped
+
+      def self.fast_scan_cells_direct: (untyped xml, untyped from, untyped to, untyped shared_strings, untyped row_source) ?{ (?) -> untyped } -> untyped
     end
   end
 end

data/sig/generated/xlsxrb/stream_row.rbs

@@ -0,0 +1,127 @@
+# Generated from lib/xlsxrb/stream_row.rb with RBS::Inline
+
+module Xlsxrb
+  # Streaming row implementation that parses cells on-demand / lazily.
+  # Provides O(1) memory consumption even for rows with tens of thousands of columns.
+  #
+  # @example Streaming cells one-by-one (O(1) memory)
+  #   row.each_cell do |cell|
+  #     puts "#{cell.ref}: #{cell.value}"
+  #   end
+  #
+  # @example Random access or array conversion (cached on-demand)
+  #   cell = row[0]
+  #   values = row.to_a
+  #
+  # @api public
+  class StreamRow
+    attr_reader index: untyped
+
+    attr_reader height: untyped
+
+    attr_reader hidden: untyped
+
+    attr_reader custom_height: untyped
+
+    attr_reader outline_level: untyped
+
+    # @param index [Integer] 0-based row index.
+    # @param xml_bytes [String] Raw ASCII-8BIT XML bytes.
+    # @param from [Integer] Byte offset where cells start.
+    # @param to [Integer] Byte offset where cells end.
+    # @param shared_strings [Array<String>] Shared strings table.
+    # @param height [Float, Integer, nil] Row height in points.
+    # @param hidden [Boolean] Whether the row is hidden.
+    # @param custom_height [Boolean] Whether custom height is set.
+    # @param outline_level [Integer, nil] Grouping/outline level.
+    # : (index: Integer, xml_bytes: String, from: Integer, to: Integer, shared_strings: Array[String], ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil) -> void
+    def initialize: (index: Integer, xml_bytes: String, from: Integer, to: Integer, shared_strings: Array[String], ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil) -> void
+
+    # Iterate over cells in this streaming row one by one.
+    #
+    # @yield [cell]
+    # @yieldparam cell [Elements::Cell]
+    # @return [Enumerator, void]
+    # @api public
+    # : () { (Elements::Cell) -> void } -> void
+    # : () -> Enumerator[Elements::Cell, void]
+    def each_cell: () { (Elements::Cell) -> void } -> void
+                 | () -> Enumerator[Elements::Cell, void]
+
+    # Iterate over cells in this streaming row.
+    #
+    # @yield [cell]
+    # @yieldparam cell [Elements::Cell]
+    # @return [Enumerator, void]
+    # @api public
+    # : () { (Elements::Cell) -> void } -> void
+    # : () -> Enumerator[Elements::Cell, void]
+    def each: () { (Elements::Cell) -> void } -> void
+            | () -> Enumerator[Elements::Cell, void]
+
+    # Returns all cells as an Array. Cached on first access.
+    #
+    # @return [Array<Elements::Cell>]
+    # @api public
+    # : () -> Array[Elements::Cell]
+    def cells: () -> Array[Elements::Cell]
+
+    # Access a cell by 0-based column index, or access row attributes via Symbol.
+    #
+    # @param col_index [Integer, Symbol] Column index or attribute symbol.
+    # @return [Elements::Cell, Object, nil]
+    # @api public
+    # : (Integer | Symbol col_index) -> untyped
+    def []: (Integer | Symbol col_index) -> untyped
+
+    # Access a cell by 0-based column index.
+    #
+    # @param col_index [Integer] 0-based column index.
+    # @return [Elements::Cell, nil]
+    # @api public
+    # : (Integer col_index) -> Elements::Cell?
+    def cell_at: (Integer col_index) -> Elements::Cell?
+
+    # Convert row cells to an Array of raw values (sparse columns get nil).
+    #
+    # @return [Array<Object>]
+    # @api public
+    # : () -> Array[untyped]
+    def to_a: () -> Array[untyped]
+
+    # Returns cell values as an Array.
+    #
+    # @return [Array<Object>]
+    # @api public
+    # : () -> Array[untyped]
+    def values: () -> Array[untyped]
+
+    # Returns whether the row is valid according to OOXML specifications.
+    #
+    # @return [Boolean]
+    # @api public
+    # : () -> bool
+    def valid?: () -> bool
+
+    # Unmapped metadata for compatibility with Elements::Row.
+    #
+    # @return [Hash]
+    # @api public
+    # : () -> Hash[untyped, untyped]
+    def unmapped_data: () -> Hash[untyped, untyped]
+
+    # Validation errors for compatibility with Elements::Row.
+    #
+    # @return [Array<String>]
+    # @api public
+    # : () -> Array[String]
+    def errors: () -> Array[String]
+
+    # Human-readable representation.
+    #
+    # @return [String]
+    # @api public
+    # : () -> String
+    def inspect: () -> String
+  end
+end