xlsxrb 0.1.7 → 0.1.9

data/lib/xlsxrb.rb

@@ -22,8 +22,10 @@ require_relative "xlsxrb/version"
 require_relative "xlsxrb/ooxml/zip_generator"
 require_relative "xlsxrb/ooxml/writer"
 require_relative "xlsxrb/ooxml/reader"
+require_relative "xlsxrb/ooxml/crypto"
 require_relative "xlsxrb/ooxml"
 require_relative "xlsxrb/elements"
+require_relative "xlsxrb/stream_row"
 require_relative "xlsxrb/style_builder"
 
 # Ruby XLSX read/write library.
@@ -41,6 +43,9 @@ module Xlsxrb
   class ParseError < Error; end
   class ValidationError < Error; end
   class ZipError < Error; end
+  class EncryptedFileError < Error; end
+  class InvalidPasswordError < EncryptedFileError; end
+  class DecryptionError < EncryptedFileError; end
 
   TRACER = OpenTelemetry.tracer_provider.tracer("xlsxrb", Xlsxrb::VERSION)
 
@@ -360,28 +365,80 @@ module Xlsxrb
     )
   end
 
-  # 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.
   #
-  # @example Read from IO stream
-  #   workbook = File.open("data.xlsx", "rb") { |io| Xlsxrb.read(io) }
+  # Call #load on the returned Workbook or Sheet to convert to an in-memory representation
+  # for coordinate random access (e.g. sheet["A1"]).
   #
-  # @param source [String, IO] File path or IO object.
-  # @return [Elements::Workbook] The parsed workbook.
+  # @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 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, 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(source)
+  #: (untyped source, ?password: String?) { (StreamSheet) -> void } -> void
+  #: (untyped source, ?password: String?) -> Elements::Workbook
+  def self.read(source, password: nil, &)
+    if source.is_a?(String)
+      if source.start_with?("PK\x03\x04") || source.include?("\x00") || Ooxml::Cfb::Reader.cfb?(source)
+        if Ooxml::Cfb::Reader.cfb?(source)
+          decrypted_zip = Ooxml::Crypto.decrypt(source, password)
+          source = StringIO.new(decrypted_zip)
+        else
+          source = StringIO.new(source)
+        end
+      elsif File.file?(source)
+        first_bytes = begin
+          File.binread(source, 8)
+        rescue StandardError
+          nil
+        end
+        if Ooxml::Cfb::Reader.cfb?(first_bytes)
+          encrypted_data = File.binread(source)
+          decrypted_zip = Ooxml::Crypto.decrypt(encrypted_data, password)
+          source = StringIO.new(decrypted_zip)
+        end
+      end
+    elsif source.respond_to?(:read) && source.respond_to?(:pos) && source.respond_to?(:seek)
+      begin
+        cur_pos = source.pos
+        first_bytes = source.read(8)
+        source.seek(cur_pos)
+        if Ooxml::Cfb::Reader.cfb?(first_bytes)
+          full_data = source.read
+          decrypted_zip = Ooxml::Crypto.decrypt(full_data, password)
+          source = StringIO.new(decrypted_zip)
+        end
+      rescue StandardError
+        # Fall through to standard reader if seeking fails
+      end
+    end
+
     attributes = source.is_a?(String) ? { "filepath" => source } : {}
     Xlsxrb.in_span("Xlsxrb.read", attributes: attributes) do
       entries = Ooxml::ZipReader.open(source, &:read_all)
       shared_strings = Ooxml::SharedStringsParser.parse(entries["xl/sharedStrings.xml"])
-      styles = Ooxml::StylesParser.parse(entries["xl/styles.xml"])
       workbook_sheets = Ooxml::WorkbookParser.parse(entries["xl/workbook.xml"])
       rels = Ooxml::RelationshipsParser.parse(entries["xl/_rels/workbook.xml.rels"])
+      styles = Ooxml::StylesParser.parse(entries["xl/styles.xml"])
 
       sheets = workbook_sheets.map do |sheet_info|
         target = rels[sheet_info[:r_id]]
@@ -389,24 +446,119 @@ module Xlsxrb
 
         sheet_path = target.start_with?("/") ? target.delete_prefix("/") : "xl/#{target}"
         sheet_xml = entries[sheet_path]
-        build_worksheet(sheet_info[:name], sheet_xml, shared_strings, styles)
+        next nil if sheet_xml.nil? || sheet_xml.empty?
+
+        StreamSheet.new(
+          sheet_info[:name],
+          sheet_xml,
+          shared_strings,
+          styles
+        )
       end.compact
 
-      Elements::Workbook.new(sheets: sheets, shared_strings: shared_strings, styles: styles)
+      wb = Elements::Workbook.new(sheets: sheets, shared_strings: shared_strings, styles: styles)
+
+      if block_given?
+        sheets.each(&)
+        nil
+      else
+        wb
+      end
     end
   end
 
-  # 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]
   #
-  # @example Write to file
+  # @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 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(target, workbook)
+  #: (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(target_or_workbook, workbook_or_nil = nil, password: nil, encryption_mode: :standard, strict_excel_mode: true, &block)
+    if block_given?
+      target = target_or_workbook
+      raise Error, "target is required" if target.nil?
+
+      attributes = target.is_a?(String) ? { "filepath" => target } : {}
+      return Xlsxrb.in_span("Xlsxrb.write", attributes: attributes) do
+        if password && !password.empty?
+          buf = StringIO.new
+          buf.binmode
+          stream_writer = StreamWriter.new(buf, strict_excel_mode: strict_excel_mode)
+          begin
+            yield stream_writer
+            stream_writer.close
+            plain_bytes = buf.string.b
+            encrypted_bytes = Ooxml::Crypto.encrypt(plain_bytes, password, mode: encryption_mode)
+            if target.is_a?(String)
+              File.binwrite(target, encrypted_bytes)
+            elsif target.respond_to?(:write)
+              target.write(encrypted_bytes)
+            end
+          ensure
+            stream_writer.cleanup!
+          end
+        else
+          stream_writer = StreamWriter.new(target, strict_excel_mode: strict_excel_mode)
+          begin
+            yield stream_writer
+            stream_writer.close
+          ensure
+            stream_writer.cleanup!
+          end
+        end
+      end
+    end
+
+    if workbook_or_nil.nil?
+      wb = target_or_workbook
+      raise Error, "workbook must be an Elements::Workbook" unless wb.is_a?(Elements::Workbook)
+
+      io = StringIO.new
+      io.binmode
+      write(io, wb, password: password, encryption_mode: encryption_mode)
+      return io.string.b
+    end
+
+    target = target_or_workbook
+    workbook = workbook_or_nil
     raise Error, "target is required" if target.nil?
     raise Error, "workbook must be an Elements::Workbook" unless workbook.is_a?(Elements::Workbook)
 
@@ -416,7 +568,8 @@ module Xlsxrb
       sst_index = {}
 
       # Collect shared strings and build index without allocating new Hashes
-      sheet_data = workbook.sheets.map do |ws|
+      sheet_data = workbook.sheets.map do |raw_ws|
+        ws = raw_ws.respond_to?(:load) ? raw_ws.load : raw_ws
         ws.rows.each do |row|
           row.cells.each do |cell|
             val = cell.value
@@ -444,19 +597,44 @@ module Xlsxrb
 
       # Extract workbook-level facade metadata
       wb_facade = workbook.unmapped_data[:facade] || {}
-      Ooxml::WorkbookWriter.write(
-        target,
-        sheets: sheet_data,
-        shared_strings: sst,
-        shared_strings_index: sst_index,
-        styles: workbook.styles,
-        defined_names: wb_facade[:defined_names],
-        core_properties: wb_facade[:core_properties],
-        app_properties: wb_facade[:app_properties],
-        custom_properties: wb_facade[:custom_properties],
-        workbook_protection: wb_facade[:workbook_protection],
-        workbook_properties: wb_facade[:workbook_properties]
-      )
+
+      if password && !password.empty?
+        buf = StringIO.new
+        buf.binmode
+        Ooxml::WorkbookWriter.write(
+          buf,
+          sheets: sheet_data,
+          shared_strings: sst,
+          shared_strings_index: sst_index,
+          styles: workbook.styles,
+          defined_names: wb_facade[:defined_names],
+          core_properties: wb_facade[:core_properties],
+          app_properties: wb_facade[:app_properties],
+          custom_properties: wb_facade[:custom_properties],
+          workbook_protection: wb_facade[:workbook_protection],
+          workbook_properties: wb_facade[:workbook_properties]
+        )
+        encrypted_bytes = Ooxml::Crypto.encrypt(buf.string.b, password, mode: encryption_mode)
+        if target.is_a?(String)
+          File.binwrite(target, encrypted_bytes)
+        elsif target.respond_to?(:write)
+          target.write(encrypted_bytes)
+        end
+      else
+        Ooxml::WorkbookWriter.write(
+          target,
+          sheets: sheet_data,
+          shared_strings: sst,
+          shared_strings_index: sst_index,
+          styles: workbook.styles,
+          defined_names: wb_facade[:defined_names],
+          core_properties: wb_facade[:core_properties],
+          app_properties: wb_facade[:app_properties],
+          custom_properties: wb_facade[:custom_properties],
+          workbook_protection: wb_facade[:workbook_protection],
+          workbook_properties: wb_facade[:workbook_properties]
+        )
+      end
     end
   end
 
@@ -475,34 +653,46 @@ 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(source, target = nil)
+  #: (untyped source, ?untyped target, ?password: String?) ?{ (Elements::Workbook) -> untyped } -> void
+  def self.modify(source, target = nil, password: nil)
     raise Error, "source is required" if source.nil?
     raise Error, "block is required" unless block_given?
 
-    workbook = read(source)
+    workbook = read(source, password: password).load
     result_workbook = yield workbook
     result_workbook = workbook unless result_workbook.is_a?(Elements::Workbook)
 
     write_target = target || source
-    write(write_target, result_workbook)
+    write(write_target, result_workbook, password: password)
   end
 
   # 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
     [Enumerable].each { |m| include m }
@@ -512,26 +702,28 @@ 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(name, sheet_xml, shared_strings)
+    # @param styles [Hash, nil] Styles table.
+    #: (String name, String sheet_xml, Array[String] shared_strings, ?Hash[untyped, untyped]? styles) -> void
+    def initialize(name, sheet_xml, shared_strings, styles = nil)
       @name = name
       @sheet_xml = sheet_xml
       @shared_strings = shared_strings
+      @styles = styles
     end
 
-    # 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]
+    #: () { (StreamRow | Elements::Row) -> void } -> void
+    #: () -> Enumerator[StreamRow | Elements::Row, void]
     def each_row
       return enum_for(:each_row) unless block_given?
 
       Ooxml::WorksheetParser.each_row(@sheet_xml, shared_strings: @shared_strings) do |row|
-        if row.is_a?(Elements::Row)
+        if row.is_a?(Elements::Row) || row.is_a?(StreamRow)
           yield row
         else
           yield Xlsxrb.send(:build_row_from_raw, row)
@@ -539,88 +731,45 @@ module Xlsxrb
       end
     end
 
-    # 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(&)
-      each_row(&)
-    end
-  end
+    #: () { (Elements::Cell) -> void } -> void
+    #: () -> Enumerator[Elements::Cell, void]
+    def each_cell(&)
+      return enum_for(:each_cell) unless block_given?
 
-  # 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(source)
-    return enum_for(:foreach, source) unless block_given?
-
-    attributes = source.is_a?(String) ? { "filepath" => source } : {}
-    Xlsxrb.in_span("Xlsxrb.foreach", attributes: attributes) do
-      entries = Ooxml::ZipReader.open(source, &:read_all)
-      shared_strings = Ooxml::SharedStringsParser.parse(entries["xl/sharedStrings.xml"])
-      workbook_sheets = Ooxml::WorkbookParser.parse(entries["xl/workbook.xml"])
-      rels = Ooxml::RelationshipsParser.parse(entries["xl/_rels/workbook.xml.rels"])
-
-      workbook_sheets.each do |sheet_info|
-        target = rels[sheet_info[:r_id]]
-        next unless target
-
-        sheet_path = target.start_with?("/") ? target.delete_prefix("/") : "xl/#{target}"
-        sheet_xml = entries[sheet_path]
-        next if sheet_xml.nil? || sheet_xml.empty?
-
-        yield StreamSheet.new(sheet_info[:name], sheet_xml, shared_strings)
+      each_row do |row|
+        row.each_cell(&)
       end
     end
-  end
 
-  # 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(target, strict_excel_mode: true)
-    raise Error, "target is required" if target.nil?
-    raise Error, "block is required" unless block_given?
+    # 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(&)
+      each_row(&)
+    end
 
-    attributes = target.is_a?(String) ? { "filepath" => target } : {}
-    Xlsxrb.in_span("Xlsxrb.generate", attributes: attributes) do
-      stream_writer = StreamWriter.new(target, strict_excel_mode: strict_excel_mode)
-      begin
-        yield stream_writer
-        stream_writer.close
-      ensure
-        stream_writer.cleanup!
-      end
+    # 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
+      Xlsxrb.send(:build_worksheet, @name, @sheet_xml, @shared_strings, @styles)
     end
+    alias to_worksheet load
   end
 
   # Builds an in-memory Elements::Workbook using a declarative DSL.

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

@@ -0,0 +1,70 @@
+# Generated from lib/xlsxrb/elements/coordinate_access.rb with RBS::Inline
+
+module Xlsxrb
+  module Elements
+    # Mixin providing coordinate-based and random-access cell/row lookups
+    # for in-memory worksheet structures.
+    #
+    # Expects the including class to provide a `#rows` method returning an `Array<Elements::Row>`.
+    #
+    # @api public
+    module CoordinateAccess
+      # Returns a Hash mapping Excel cell references (e.g. "A1") to Cell objects.
+      #
+      # @return [Hash<String, Elements::Cell>]
+      # : () -> Hash[String, Elements::Cell]
+      def cells_hash: () -> Hash[String, Elements::Cell]
+
+      # Returns all cells ordered by row and column index.
+      #
+      # @return [Array<Elements::Cell>]
+      # @api public
+      # : () -> Array[Elements::Cell]
+      def cells: () -> Array[Elements::Cell]
+
+      # Access a cell by its Excel-style reference (e.g. "A1").
+      #
+      # @example
+      #   sheet["A1"] #=> #<Elements::Cell value="Hello">
+      #
+      # @param ref [String, Symbol] Cell reference (e.g. "A1" or :A1).
+      # @return [Elements::Cell, nil]
+      # @api public
+      # : (String | Symbol ref) -> Elements::Cell?
+      def []: (String | Symbol ref) -> Elements::Cell?
+
+      # Returns the row at the given 0-based index, or nil.
+      #
+      # @param index [Integer] 0-based row index.
+      # @return [Elements::Row, nil]
+      # @api public
+      # : (Integer index) -> Elements::Row?
+      def row_at: (Integer index) -> Elements::Row?
+
+      # Returns the first row in the sheet, or nil.
+      #
+      # @return [Elements::Row, nil]
+      # @api public
+      # : () -> Elements::Row?
+      def first_row: () -> Elements::Row?
+
+      # Returns the last row in the sheet, or nil.
+      #
+      # @return [Elements::Row, nil]
+      # @api public
+      # : () -> Elements::Row?
+      def last_row: () -> Elements::Row?
+
+      # Returns the raw cell value at the given Excel-style reference (e.g. "A1").
+      #
+      # @example
+      #   sheet.cell_value("A1") #=> "Sales Report"
+      #
+      # @param ref [String] Cell reference (e.g. "A1").
+      # @return [Object, nil]
+      # @api public
+      # : (String ref) -> untyped
+      def cell_value: (String ref) -> untyped
+    end
+  end
+end