fast_xlsx 0.1.0

data/lib/fast_xlsx/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FastXlsx
+  VERSION = "0.1.0"
+end

data/lib/fast_xlsx.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require_relative "fast_xlsx/version"
+
+# Fast .xlsx writer backed by rust_xlsxwriter.
+module FastXlsx
+  class Error < StandardError; end
+
+  # Cell value written as an Excel formula, e.g. Formula.new("SUM(A1:A9)").
+  Formula = Data.define(:expression) do
+    def initialize(expression:)
+      super(expression: expression.to_s)
+    end
+  end
+
+  # Cell value written as a hyperlink, e.g. URL.new("https://example.com").
+  # text: shown in the cell instead of the URL itself.
+  # Subclassed (not a Data.define block) so .new can call super, which lets it
+  # accept URL.new(url, text: ...) as well as the usual Data forms.
+  class URL < Data.define(:url, :text) # rubocop:disable Style/DataInheritance
+    def self.new(*args, **kwargs)
+      raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..2)" if args.size > 2
+
+      kwargs[:url] = args[0] unless args.empty?
+      kwargs[:text] = args[1] if args.size > 1
+      super(**kwargs)
+    end
+
+    # Also reached by URL[...] and #with, so values are normalized here.
+    def initialize(url:, text: nil)
+      super(url: url.to_s, text: text&.to_s)
+    end
+  end
+
+  # Text with a format per segment, e.g. RichString.new(["Total: ", bold], "1,234").
+  # Each segment is a String (default font) or [String, Format].
+  class RichString
+    attr_reader :segments
+
+    def initialize(*parts)
+      raise ArgumentError, "RichString needs at least one segment" if parts.empty?
+
+      @segments = parts.map { |part| part.is_a?(Array) ? [part[0].to_s, part[1]] : [part.to_s, nil] }.freeze
+    end
+  end
+
+  # The native extension looks up FastXlsx::Error, so load it after Error is defined.
+  require "fast_xlsx/fast_xlsx"
+
+  # Owns the worksheets; serialize with #to_xlsx or #save.
+  class Workbook
+    MEMORY_MODES = %i[standard constant low].freeze
+
+    # memory: :standard keeps every cell in memory until saving. :constant and
+    # :low write each finished row to disk, so each worksheet must be filled
+    # top to bottom. :constant stores strings inline (memory stays flat); :low
+    # keeps Excel's shared string table (memory grows with the number of
+    # unique strings, output is standard).
+    def self.new(memory: :standard)
+      unless MEMORY_MODES.include?(memory)
+        raise ArgumentError, "unknown memory mode #{memory.inspect} (expected one of #{MEMORY_MODES.join(", ")})"
+      end
+
+      _new(memory == :constant, memory == :low)
+    end
+
+    def add_worksheet(name = nil)
+      _add_worksheet(name).tap { |ws| worksheets << ws }
+    end
+
+    # The same Worksheet objects add_worksheet returned, so their append
+    # position is shared.
+    def worksheets
+      @worksheets ||= []
+    end
+
+    def worksheet(name)
+      worksheets.find { |ws| ws.name == name }
+    end
+
+    # Document properties shown in Excel's File > Info: title:, subject:,
+    # author:, manager:, company:, category:, keywords:, comments:, status:.
+    # Later calls add to earlier ones.
+    def properties(**fields)
+      merged = (@properties || {}).merge(fields)
+      _properties(merged) # validates before anything is remembered
+      @properties = merged
+      self
+    end
+  end
+
+  # Cell writer for one sheet; create with Workbook#add_worksheet.
+  class Worksheet
+    def write(row, col, value, format = nil)
+      _write(row, col, value, format)
+      self
+    end
+
+    def append(values, format: nil)
+      _append(values, format)
+    end
+
+    # columns: a 0-based column index or a Range of them. width is in characters.
+    def column_width(columns, width)
+      bounds = column_bounds(columns)
+      _column_width(*bounds, width)
+      @fixed_widths ||= {}
+      @fixed_widths.delete(bounds) # re-insert so autofit replays calls in order
+      @fixed_widths[bounds] = width
+      self
+    end
+
+    # Sizes columns to the data written so far. Widths set with
+    # column_width are kept.
+    def autofit
+      _autofit
+      @fixed_widths&.each { |bounds, width| _column_width(*bounds, width) }
+      self
+    end
+
+    # Merges the range and writes value (any cell type) into its first cell.
+    def merge_range(first_row, first_col, last_row, last_col, value, format = nil)
+      _merge_range(first_row, first_col, last_row, last_col, value, format)
+    end
+
+    # Highlights cells in the range by rule. type: :cell, :text, :formula,
+    # :data_bar or :color_scale; see the README for each type's options.
+    def conditional_format(first_row, first_col, last_row, last_col, type:, **)
+      _conditional_format(first_row, first_col, last_row, last_col, { type: type, ** })
+    end
+
+    # Restricts what can be entered in the range. type: :list, :whole_number,
+    # :decimal or :text_length; see the README for the options.
+    def data_validation(first_row, first_col, last_row, last_col, type:, **)
+      _data_validation(first_row, first_col, last_row, last_col, { type: type, ** })
+    end
+
+    # Adds a comment (Excel "note") to a cell.
+    def write_comment(row, col, text, author: nil)
+      _write_comment(row, col, text, author)
+    end
+
+    # Inserts a PNG, JPEG, GIF or BMP image with its top-left corner in the
+    # cell. source is a file path or an IO (anything responding to #read).
+    # Options: scale: or width:/height: (pixels), x_offset:, y_offset: (pixels), alt_text:.
+    def insert_image(row, col, source, **)
+      bytes = source.respond_to?(:read) ? source.read : File.binread(source)
+      _insert_image(row, col, bytes, { ** })
+    end
+
+    # Inserts a chart with its top-left corner in the cell. series is an Array
+    # of { values:, categories:, name: } with Excel ranges such as
+    # "Sheet1!$B$2:$B$13". Options: title:, x_axis:, y_axis:, width:, height:.
+    def insert_chart(row, col, type:, series:, **)
+      _insert_chart(row, col, { type: type, series: series, ** })
+    end
+
+    # Turns the range (header row included, total row too when total_row: true)
+    # into an Excel table. columns: header Strings or { header:, total:,
+    # total_label:, format: }; other options: style:, name:, total_row:,
+    # banded_rows:, autofilter:.
+    def add_table(first_row, first_col, last_row, last_col, **)
+      _add_table(first_row, first_col, last_row, last_col, { ** })
+    end
+
+    # Printed page header/footer using Excel codes such as "&CPage &P of &N".
+    # margin: is in inches.
+    def page_header(text, margin: nil)
+      _page_header(text)
+      margin ? margins(header: margin) : self
+    end
+
+    def page_footer(text, margin: nil)
+      _page_footer(text)
+      margin ? margins(footer: margin) : self
+    end
+
+    # Print margins in inches; margins not given keep their current value.
+    def margins(left: nil, right: nil, top: nil, bottom: nil, header: nil, footer: nil)
+      _margins(*[left, right, top, bottom, header, footer].map { |m| m || -1.0 })
+      self
+    end
+
+    # Default format for cells in these columns that are written without one.
+    def column_format(columns, format)
+      _column_format(*column_bounds(columns), format)
+      self
+    end
+
+    private
+
+    def column_bounds(columns)
+      columns.is_a?(Integer) ? [columns, columns] : columns.minmax
+    end
+  end
+
+  # Cell style, e.g. Format.new(bold: true). Pass to Worksheet#write.
+  class Format
+    def self.new(**options)
+      # Apply border: first so border_left: etc. override it whatever the order.
+      options = { border: options[:border], **options.except(:border) } if options.key?(:border)
+      _new(options)
+    end
+  end
+end

data/sig/fast_xlsx.rbs

@@ -0,0 +1,100 @@
+module FastXlsx
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  interface _Reader
+    def read: () -> String
+  end
+
+  type cell = Numeric | String | Time | Date | Formula | URL | RichString | bool | nil | _ToS
+
+  class RichString
+    attr_reader segments: Array[[String, Format?]]
+    def initialize: (*(_ToS | [_ToS, Format?]) parts) -> void
+  end
+
+  class Formula
+    attr_reader expression: String
+    def self.new: (_ToS expression) -> Formula
+  end
+
+  class URL
+    attr_reader url: String
+    attr_reader text: String?
+    def self.new: (_ToS url, ?text: _ToS?) -> URL
+  end
+
+  class Workbook
+    MEMORY_MODES: Array[Symbol]
+    def self.new: (?memory: :standard | :constant | :low) -> Workbook
+    def add_worksheet: (?String? name) -> Worksheet
+    def worksheets: () -> Array[Worksheet]
+    def worksheet: (String name) -> Worksheet?
+    def properties: (?title: String, ?subject: String, ?author: String, ?manager: String,
+                     ?company: String, ?category: String, ?keywords: String,
+                     ?comments: String, ?status: String) -> self
+    def to_xlsx: () -> String
+    def save: (String path) -> void
+  end
+
+  class Format
+    type color = String | Integer
+    type border = :thin | :medium | :thick | :dashed | :dotted | :double | :hair
+
+    type underline = bool | :single | :double | :single_accounting | :double_accounting
+
+    def self.new: (?bold: bool, ?italic: bool, ?underline: underline, ?strikeout: bool, ?text_wrap: bool,
+                   ?shrink: bool, ?num_format: String, ?font_size: Numeric, ?font_name: String,
+                   ?font_color: color, ?bg_color: color, ?font_script: :superscript | :subscript,
+                   ?align: :left | :center | :right, ?valign: :top | :center | :bottom,
+                   ?rotation: Integer, ?indent: Integer,
+                   ?border: border, ?border_left: border, ?border_right: border,
+                   ?border_top: border, ?border_bottom: border, ?border_color: color) -> Format
+  end
+
+  class Worksheet
+    def write: (Integer row, Integer col, cell value, ?Format? format) -> self
+    def append: (Array[cell] values, ?format: Format? | Array[Format?]) -> self
+    def <<: (Array[cell] row) -> self
+    def concat: (Array[Array[cell]] rows) -> self
+    def column_width: (Integer | Range[Integer] columns, Numeric width) -> self
+    def column_format: (Integer | Range[Integer] columns, Format format) -> self
+    def autofit: () -> self
+    def autofilter: (Integer first_row, Integer first_col, Integer last_row, Integer last_col) -> self
+    def freeze_panes: (Integer row, Integer col) -> self
+    def row_height: (Integer row, Numeric height) -> self
+    def page_breaks: (Array[Integer] rows) -> self
+    def vertical_page_breaks: (Array[Integer] cols) -> self
+    def page_header: (String text, ?margin: Numeric?) -> self
+    def page_footer: (String text, ?margin: Numeric?) -> self
+    def margins: (?left: Numeric?, ?right: Numeric?, ?top: Numeric?, ?bottom: Numeric?,
+                  ?header: Numeric?, ?footer: Numeric?) -> self
+    def merge_range: (Integer first_row, Integer first_col, Integer last_row, Integer last_col, cell value, ?Format? format) -> self
+    def conditional_format: (Integer first_row, Integer first_col, Integer last_row, Integer last_col,
+                             type: :cell | :text | :formula | :data_bar | :color_scale,
+                             ?criteria: Symbol, ?value: Numeric | String | Array[Numeric | String],
+                             ?format: Format, ?colors: 2 | 3) -> self
+    def data_validation: (Integer first_row, Integer first_col, Integer last_row, Integer last_col,
+                          type: :list | :whole_number | :decimal | :text_length,
+                          ?criteria: Symbol, ?value: Numeric | String | Array[Numeric | String],
+                          ?input_title: String, ?input_message: String,
+                          ?error_title: String, ?error_message: String) -> self
+    def write_comment: (Integer row, Integer col, String text, ?author: String?) -> self
+    def insert_image: (Integer row, Integer col, String | _Reader source, ?scale: Numeric, ?width: Numeric, ?height: Numeric,
+                       ?x_offset: Integer, ?y_offset: Integer, ?alt_text: String) -> self
+    type chart_series = { values: String, ?categories: String, ?name: String }
+
+    def insert_chart: (Integer row, Integer col, type: Symbol, series: Array[chart_series],
+                       ?title: String, ?x_axis: String, ?y_axis: String,
+                       ?width: Integer, ?height: Integer) -> self
+    type table_column = String | { header: String, ?total: Symbol, ?total_label: String, ?format: Format }
+
+    def add_table: (Integer first_row, Integer first_col, Integer last_row, Integer last_col,
+                    ?columns: Array[table_column], ?style: Symbol, ?name: String,
+                    ?total_row: bool, ?banded_rows: bool, ?autofilter: bool) -> self
+    def name: () -> String
+    def next_row: () -> Integer
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: fast_xlsx
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Zac
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+description: Writes Excel .xlsx files from Ruby through a native Rust extension (rust_xlsxwriter
+  + magnus).
+email:
+- 579103+7a6163@users.noreply.github.com
+executables: []
+extensions:
+- ext/fast_xlsx/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.lock
+- Cargo.toml
+- LICENSE.txt
+- README.md
+- Rakefile
+- bench/Gemfile
+- bench/Gemfile.lock
+- bench/compare.rb
+- bench/memory.rb
+- bench/write.rb
+- examples/showcase.rb
+- ext/fast_xlsx/Cargo.toml
+- ext/fast_xlsx/build.rs
+- ext/fast_xlsx/extconf.rb
+- ext/fast_xlsx/src/lib.rs
+- lib/fast_xlsx.rb
+- lib/fast_xlsx/version.rb
+- sig/fast_xlsx.rbs
+homepage: https://github.com/7a6163/fast_xlsx
+licenses:
+- MIT
+metadata:
+  github_repo: ssh://github.com/7a6163/fast_xlsx
+  homepage_uri: https://github.com/7a6163/fast_xlsx
+  source_code_uri: https://github.com/7a6163/fast_xlsx
+  changelog_uri: https://github.com/7a6163/fast_xlsx/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Fast xlsx writer for Ruby, powered by rust_xlsxwriter
+test_files: []