xlsxrb 0.1.7 → 0.1.9

data/sig/generated/xlsxrb.rbs

@@ -27,6 +27,15 @@ module Xlsxrb
   class ZipError < Error
   end
 
+  class EncryptedFileError < Error
+  end
+
+  class InvalidPasswordError < EncryptedFileError
+  end
+
+  class DecryptionError < EncryptedFileError
+  end
+
   TRACER: untyped
 
   def self.in_span: (untyped name, ?attributes: untyped) ?{ (?) -> untyped } -> untyped
@@ -266,33 +275,87 @@ module Xlsxrb
   # : (String expression, ?cached_value: String | Numeric | bool | nil) -> Elements::Formula
   def self.formula: (String expression, ?cached_value: String | Numeric | bool | nil) -> Elements::Formula
 
-  # Reads an XLSX file into an in-memory Elements::Workbook.
+  # Reads an XLSX file (streaming / lazy-loaded by default) from a file path, IO stream, or binary String.
   #
-  # @example Read from file path
-  #   workbook = Xlsxrb.read("data.xlsx")
-  #   sheet = workbook["Sheet1"]
-  #   puts sheet["A1"].value
+  # Sheets and rows are streamed lazily with O(1) constant memory. If a block is given,
+  # yields each StreamSheet sequentially.
+  #
+  # Call #load on the returned Workbook or Sheet to convert to an in-memory representation
+  # for coordinate random access (e.g. sheet["A1"]).
+  #
+  # @example Streaming read across sheets and rows (O(1) memory)
+  #   Xlsxrb.read("large.xlsx") do |sheet|
+  #     puts "Sheet: #{sheet.name}"
+  #     sheet.each_row do |row|
+  #       row.each_cell { |cell| puts "#{cell.ref}: #{cell.value}" }
+  #     end
+  #   end
   #
-  # @example Read from IO stream
-  #   workbook = File.open("data.xlsx", "rb") { |io| Xlsxrb.read(io) }
+  # @example Lazy workbook access and explicit in-memory loading
+  #   wb = Xlsxrb.read("data.xlsx")
+  #   sheet = wb.sheets.first
+  #   sheet.each_row { |row| ... }   # streams with O(1) memory
+  #   doc_sheet = sheet.load         # explicitly load into memory
+  #   puts doc_sheet["A1"].value     # coordinate random access
   #
-  # @param source [String, IO] File path or IO object.
-  # @return [Elements::Workbook] The parsed workbook.
+  # @param source [String, IO] File path, binary content string (starting with PK..), or IO object.
+  # @param password [String, nil] Optional password to decrypt password-protected XLSX files.
+  # @yield [sheet] Yields each streaming sheet.
+  # @yieldparam sheet [StreamSheet] The streaming worksheet object.
+  # @return [Elements::Workbook, void] Returns Elements::Workbook when no block is given.
   # @api public
-  # : (untyped source) -> Elements::Workbook
-  def self.read: (untyped source) -> Elements::Workbook
+  # : (untyped source, ?password: String?) { (StreamSheet) -> void } -> void
+  # : (untyped source, ?password: String?) -> Elements::Workbook
+  def self.read: (untyped source, ?password: String?) { (StreamSheet) -> void } -> void
+               | (untyped source, ?password: String?) -> Elements::Workbook
 
-  # Writes an Elements::Workbook to an XLSX file or IO stream.
+  # Writes an XLSX file or IO stream (streaming or in-memory), or returns a binary string.
+  #
+  # @overload write(target, password: nil, strict_excel_mode: true, &block)
+  #   Streaming write: yields a StreamWriter context for high-speed, zero-allocation XLSX generation.
+  #   @param target [String, IO] Destination file path or writable IO object.
+  #   @param password [String, nil] Optional password to encrypt the generated XLSX file.
+  #   @param strict_excel_mode [Boolean] Whether to enforce Excel specifications.
+  #   @yield [stream_writer]
+  #   @yieldparam stream_writer [Xlsxrb::StreamWriter]
+  #   @return [void]
+  #
+  # @overload write(workbook, password: nil)
+  #   In-memory write: exports the workbook to an in-memory binary String.
+  #   @param workbook [Elements::Workbook] The workbook to write.
+  #   @param password [String, nil] Optional password to encrypt the binary string.
+  #   @return [String] Binary data representing the XLSX file.
+  #
+  # @overload write(target, workbook, password: nil)
+  #   In-memory write: writes the workbook to a file path or IO stream.
+  #   @param target [String, IO] Destination file path or writable IO object.
+  #   @param workbook [Elements::Workbook] The workbook to write.
+  #   @param password [String, nil] Optional password to encrypt the output file.
+  #   @return [void]
+  #
+  # @example Streaming write to file
+  #   Xlsxrb.write("output.xlsx") do |writer|
+  #     writer.sheet("Sheet1") { |s| s.row(["Hello", "World"]) }
+  #   end
   #
-  # @example Write to file
+  # @example Password-protected streaming write
+  #   Xlsxrb.write("protected.xlsx", password: "secret_password") do |writer|
+  #     writer.sheet("Confidential") { |s| s.row(["Private Data", 100]) }
+  #   end
+  #
+  # @example In-memory export to binary string
+  #   binary_data = Xlsxrb.write(workbook)
+  #
+  # @example In-memory write to file
   #   Xlsxrb.write("output.xlsx", workbook)
   #
-  # @param target [String, IO] File path or IO object.
-  # @param workbook [Elements::Workbook] The workbook to write.
-  # @return [void]
   # @api public
-  # : (untyped target, untyped workbook) -> void
-  def self.write: (untyped target, untyped workbook) -> void
+  # : (Elements::Workbook workbook, ?password: String?, ?encryption_mode: Symbol) -> String
+  # : (untyped target, Elements::Workbook | untyped workbook, ?password: String?, ?encryption_mode: Symbol) -> void
+  # : (untyped target_or_workbook, ?Elements::Workbook | untyped workbook_or_nil, ?password: String?, ?encryption_mode: Symbol, ?strict_excel_mode: bool) ?{ (StreamWriter) -> void } -> untyped
+  def self.write: (Elements::Workbook workbook, ?password: String?, ?encryption_mode: Symbol) -> String
+                | (untyped target, Elements::Workbook | untyped workbook, ?password: String?, ?encryption_mode: Symbol) -> void
+                | (untyped target_or_workbook, ?Elements::Workbook | untyped workbook_or_nil, ?password: String?, ?encryption_mode: Symbol, ?strict_excel_mode: bool) ?{ (StreamWriter) -> void } -> untyped
 
   # Modifies an existing XLSX file.
   # Reads the workbook, passes it to the block, and writes the result.
@@ -309,24 +372,36 @@ module Xlsxrb
   #
   # @param source [String, IO] The source file path or IO object.
   # @param target [String, IO, nil] The target file path or IO object. If nil, overwrites source.
+  # @param password [String, nil] Optional password for reading and writing protected files.
   # @yield [workbook] Yields the parsed workbook.
   # @yieldparam workbook [Elements::Workbook] The parsed workbook.
   # @yieldreturn [Elements::Workbook] The modified workbook.
   # @return [void]
   # @api public
-  # : (untyped source, ?untyped target) ?{ (Elements::Workbook) -> untyped } -> void
-  def self.modify: (untyped source, ?untyped target) ?{ (Elements::Workbook) -> untyped } -> void
+  # : (untyped source, ?untyped target, ?password: String?) ?{ (Elements::Workbook) -> untyped } -> void
+  def self.modify: (untyped source, ?untyped target, ?password: String?) ?{ (Elements::Workbook) -> untyped } -> void
 
   # Represents a sheet being streamed sequentially from an XLSX file.
+  # Provides O(1) constant-memory streaming over rows and cells.
+  #
+  # Call #load (or #to_worksheet) to convert this streaming sheet into an
+  # in-memory Elements::Worksheet supporting coordinate random access (sheet["A1"]).
   #
-  # @example Iterate rows in streaming mode
-  #   Xlsxrb.foreach("large_data.xlsx") do |sheet|
+  # @example Iterate rows and cells in streaming mode (O(1) memory)
+  #   Xlsxrb.read("large_data.xlsx") do |sheet|
   #     puts "Processing sheet: #{sheet.name}"
   #     sheet.each_row do |row|
-  #       puts row.to_a.inspect
+  #       row.each_cell do |cell|
+  #         puts "#{cell.ref}: #{cell.value}"
+  #       end
   #     end
   #   end
   #
+  # @example Load into an in-memory Worksheet for coordinate random access
+  #   wb = Xlsxrb.read("data.xlsx")
+  #   doc_sheet = wb.sheet(0).load
+  #   puts doc_sheet["A1"].value
+  #
   # @api public
   class StreamSheet
     attr_reader name: untyped
@@ -334,65 +409,54 @@ module Xlsxrb
     # @param name [String] The sheet name.
     # @param sheet_xml [String] Raw XML content of the sheet.
     # @param shared_strings [Array<String>] Shared strings table.
-    # : (String name, String sheet_xml, Array[String] shared_strings) -> void
-    def initialize: (String name, String sheet_xml, Array[String] shared_strings) -> void
+    # @param styles [Hash, nil] Styles table.
+    # : (String name, String sheet_xml, Array[String] shared_strings, ?Hash[untyped, untyped]? styles) -> void
+    def initialize: (String name, String sheet_xml, Array[String] shared_strings, ?Hash[untyped, untyped]? styles) -> void
 
-    # Iterate over rows in this streaming sheet.
+    # Iterate over rows in this streaming sheet (O(1) memory).
     #
     # @yield [row]
-    # @yieldparam row [Elements::Row]
+    # @yieldparam row [StreamRow, Elements::Row]
     # @return [Enumerator, void]
     # @api public
-    # : () { (Elements::Row) -> void } -> void
-    # : | () -> Enumerator[Elements::Row, void]
-    def each_row: () { (Elements::Row) -> void } -> void
+    # : () { (StreamRow | Elements::Row) -> void } -> void
+    # : () -> Enumerator[StreamRow | Elements::Row, void]
+    def each_row: () { (StreamRow | Elements::Row) -> void } -> void
+                | () -> Enumerator[StreamRow | Elements::Row, void]
 
-    # Iterate over rows in this streaming sheet.
+    # Iterate over all cells across rows continuously (O(1) memory).
     #
-    # @yield [row]
-    # @yieldparam row [Elements::Row]
+    # @yield [cell]
+    # @yieldparam cell [Elements::Cell]
     # @return [Enumerator, void]
     # @api public
-    # : () { (Elements::Row) -> void } -> void
-    # : | () -> Enumerator[Elements::Row, void]
-    def each: () { (Elements::Row) -> void } -> void
-  end
+    # : () { (Elements::Cell) -> void } -> void
+    # : () -> Enumerator[Elements::Cell, void]
+    def each_cell: () { (Elements::Cell) -> void } -> void
+                 | () -> Enumerator[Elements::Cell, void]
 
-  # Streaming read: yields StreamSheet objects one at a time for each sheet in the workbook.
-  # Keeps memory usage minimal even for multi-gigabyte XLSX files.
-  #
-  # @example
-  #   Xlsxrb.foreach("large.xlsx") do |sheet|
-  #     puts "Sheet: #{sheet.name}"
-  #     sheet.each_row { |row| process(row) }
-  #   end
-  #
-  # @param source [String, IO] File path or IO object.
-  # @yield [sheet] Yields each sheet.
-  # @yieldparam sheet [StreamSheet] The streaming sheet object.
-  # @return [Enumerator, void]
-  # @api public
-  # : (untyped source) ?{ (StreamSheet) -> void } -> untyped
-  def self.foreach: (untyped source) ?{ (StreamSheet) -> void } -> untyped
+    # Default Enumerable iteration iterates rows in the streaming sheet.
+    #
+    # @yield [row]
+    # @yieldparam row [StreamRow, Elements::Row]
+    # @return [Enumerator, void]
+    # @api public
+    # : () { (StreamRow | Elements::Row) -> void } -> void
+    # : () -> Enumerator[StreamRow | Elements::Row, void]
+    def each: () { (StreamRow | Elements::Row) -> void } -> void
+            | () -> Enumerator[StreamRow | Elements::Row, void]
+
+    # Loads this sheet completely into an in-memory Elements::Worksheet,
+    # enabling coordinate random access (sheet["A1"]), row lookups (row_at),
+    # and immutable cell updates (update_cell).
+    #
+    # @return [Elements::Worksheet] The fully parsed in-memory worksheet.
+    # @api public
+    # : () -> Elements::Worksheet
+    def load: () -> Elements::Worksheet
 
-  # Streaming write: yields a StreamWriter context for high-speed, zero-allocation XLSX generation.
-  #
-  # @example Generate an Excel file with styles and multiple sheets
-  #   Xlsxrb.generate("sales.xlsx") do |stream_writer|
-  #     stream_writer.sheet("Q1") do |sheet|
-  #       sheet.row(["Product", "Revenue"], styles: :bold)
-  #       sheet.row(["Widget", 15000])
-  #     end
-  #   end
-  #
-  # @param target [String, IO] File path or IO stream (e.g. pipe, socket, Rails response buffer).
-  # @param strict_excel_mode [Boolean] Whether to enforce Excel specifications (max rows/cols/length).
-  # @yield [stream_writer]
-  # @yieldparam stream_writer [Xlsxrb::StreamWriter]
-  # @return [void]
-  # @api public
-  # : (untyped target, ?strict_excel_mode: bool) ?{ (StreamWriter) -> void } -> void
-  def self.generate: (untyped target, ?strict_excel_mode: bool) ?{ (StreamWriter) -> void } -> void
+    alias to_worksheet load
+  end
 
   # Builds an in-memory Elements::Workbook using a declarative DSL.
   #

data/vendor/sdk_runner/Program.cs

@@ -46,13 +46,15 @@ async Task<ScenarioExecResult> RunScenario(string code, string xlsxPath)
             typeof(Enumerable).Assembly,
             typeof(Console).Assembly,
             typeof(SpreadsheetDocument).Assembly,
-            typeof(OpenXmlValidator).Assembly
+            typeof(OpenXmlValidator).Assembly,
+            typeof(System.Security.Cryptography.Aes).Assembly
         )
         .AddImports(
             "System",
             "System.IO",
             "System.Linq",
             "System.Collections.Generic",
+            "System.Security.Cryptography",
             "DocumentFormat.OpenXml",
             "DocumentFormat.OpenXml.Packaging",
             "DocumentFormat.OpenXml.Spreadsheet",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xlsxrb
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.9
 platform: ruby
 authors:
 - niku
@@ -184,11 +184,16 @@ files:
 - lib/xlsxrb/elements.rb
 - lib/xlsxrb/elements/cell.rb
 - lib/xlsxrb/elements/column.rb
+- lib/xlsxrb/elements/coordinate_access.rb
 - lib/xlsxrb/elements/row.rb
 - lib/xlsxrb/elements/types.rb
 - lib/xlsxrb/elements/workbook.rb
 - lib/xlsxrb/elements/worksheet.rb
 - lib/xlsxrb/ooxml.rb
+- lib/xlsxrb/ooxml/cfb.rb
+- lib/xlsxrb/ooxml/crypto.rb
+- lib/xlsxrb/ooxml/crypto/agile.rb
+- lib/xlsxrb/ooxml/crypto/standard.rb
 - lib/xlsxrb/ooxml/reader.rb
 - lib/xlsxrb/ooxml/shared_strings_parser.rb
 - lib/xlsxrb/ooxml/styles_parser.rb
@@ -203,6 +208,7 @@ files:
 - lib/xlsxrb/ooxml/zip_generator.rb
 - lib/xlsxrb/ooxml/zip_reader.rb
 - lib/xlsxrb/ooxml/zip_writer.rb
+- lib/xlsxrb/stream_row.rb
 - lib/xlsxrb/style_builder.rb
 - lib/xlsxrb/version.rb
 - rbs_collection.lock.yaml
@@ -211,11 +217,16 @@ files:
 - sig/generated/xlsxrb/elements.rbs
 - sig/generated/xlsxrb/elements/cell.rbs
 - sig/generated/xlsxrb/elements/column.rbs
+- sig/generated/xlsxrb/elements/coordinate_access.rbs
 - sig/generated/xlsxrb/elements/row.rbs
 - sig/generated/xlsxrb/elements/types.rbs
 - sig/generated/xlsxrb/elements/workbook.rbs
 - sig/generated/xlsxrb/elements/worksheet.rbs
 - sig/generated/xlsxrb/ooxml.rbs
+- sig/generated/xlsxrb/ooxml/cfb.rbs
+- sig/generated/xlsxrb/ooxml/crypto.rbs
+- sig/generated/xlsxrb/ooxml/crypto/agile.rbs
+- sig/generated/xlsxrb/ooxml/crypto/standard.rbs
 - sig/generated/xlsxrb/ooxml/reader.rbs
 - sig/generated/xlsxrb/ooxml/shared_strings_parser.rbs
 - sig/generated/xlsxrb/ooxml/styles_parser.rbs
@@ -230,6 +241,7 @@ files:
 - sig/generated/xlsxrb/ooxml/zip_generator.rbs
 - sig/generated/xlsxrb/ooxml/zip_reader.rbs
 - sig/generated/xlsxrb/ooxml/zip_writer.rbs
+- sig/generated/xlsxrb/stream_row.rbs
 - sig/generated/xlsxrb/style_builder.rbs
 - sig/generated/xlsxrb/version.rbs
 - sig/rexml.rbs