rukbat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9e1adcf1d5362c707d385caf7e0035b9aa358286bc45752d67abe012606a9961
+  data.tar.gz: ec59e5a8ac486e57bded8e8f3a54129ac7514321722132edbae4181aabcefc4f
+SHA512:
+  metadata.gz: 207d10683c00d7ce74ac3c101f0facd2c8e39385ee186f09e2c38dbbb15e19e7ee603e3b9f6a0ff528a5d46006a52693e12511ebc36981324e6c469d61bea5ef
+  data.tar.gz: f2ee8e18a439ae0fc7a7ad271aa44ea783250504b1362afe82cae72af1461c3f5304861bd3334e1bec3880fe1689d9b52d7f2451b1deda883609b61e8f58f2e9

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 — 2026-09-23
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# Rukbat
+
+Rukbat (α Sagittarii), from Arabic *rukbat al-rāmī* (“the archer’s knee”), is
+a spreadsheet application built on a sparse, persistent Denebola sheet and the
+Furud formula engine.
+
+The current implementation includes a virtualized million-row grid, formula
+editing and completion, multi-sheet formulas, range summaries, undo/redo,
+structural row/column edits, formatting, sorting, filtering, duplicate removal,
+find/replace, comments, named ranges, conditional formatting, line/bar/pie
+charts, CSV/TSV import/export, and searchable PDF export. The application is
+still under development and has not been released as `0.1.0`. On arm64 macOS
+with Ruby 4.0.6, the million-row integrated scroll benchmark measured 11.383 ms
+against a 16.67 ms budget, and the 100,000-cell edit/recalculation benchmark
+measured 1.773 s against a 3 s budget. Formula compatibility, public CI, and
+dependency releases remain before the first release.
+
+## Install
+
+```ruby
+gem "rukbat"
+```
+
+Rukbat requires Ruby 3.2 or newer.
+
+## Workbooks
+
+```ruby
+require "rukbat"
+
+book = Rukbat::Workbook.new
+book.set(1, 1, 12)
+book.set(2, 1, 30)
+book.set(1, 2, "=SUM(A1:A2)")
+book[1, 2] # => 42
+
+book.add_sheet("Annual Plan")
+book.set(1, 1, 2026, sheet: "Annual Plan")
+book.undo
+book.redo
+```
+
+Workbook coordinates and Furud references are one-based. Denebola storage is
+zero-based internally. Sheets are immutable persistent snapshots, so undo and
+redo retain prior roots instead of copying all cells. The formula engine is
+storage-agnostic; Rukbat adapts sparse range iteration through `CellSource`.
+
+## CSV and TSV
+
+```ruby
+book = Rukbat::CSVFile.read("sales.csv", hint: "Windows-31J")
+Rukbat::CSVFile.write(book, "sales-export.csv")
+Rukbat::CSVFile.read("data.tsv", delimiter: :tsv)
+```
+
+Import detects and strictly decodes text with Menkar, then infers integer and
+decimal literals while leaving other fields as strings. Export writes UTF-8
+with CRLF row separators; formula cells export their calculated values by
+default. Pass `values: :input` to export stored formulas/inputs instead.
+The application refuses to replace an existing file unless it is the exact
+file read into the workbook and has not changed since loading.
+
+Run `bundle exec rukbat sales.csv` to open the graphical editor. A missing CSV
+path starts a new workbook; `--tsv` selects tab-delimited input and output.
+Use the mouse to select ranges, arrow keys to move, Enter or a double-click to
+edit, and Apply to commit the formula bar value. `Ctrl-S`/`Cmd-S` saves;
+`Ctrl-Z`/`Cmd-Z` undo and the shifted shortcut redoes. The selected range's
+count, numeric count, sum, and average appear in the status bar.
+
+The toolbar provides common number, font, alignment, fill, and border formats;
+sorting, filtering, duplicate removal, search/replace, comments, named ranges,
+positive-value highlighting, freeze/unfreeze panes, print areas, and line/bar/pie charts.
+Freeze panes are kept per sheet and restored by undo/redo; the selected cell and
+the row/column headers before it stay visible while scrolling. **Unfreeze** removes
+all frozen rows and columns. Clear highlights removes conditional formatting
+from the active sheet.
+Select a range and choose **Set print area** to constrain PDF export; **Clear
+print area** restores full-sheet output. **Export PDF** prompts for an embeddable
+font and output path, applying the current print area. The CLI can also export
+with `bundle exec rukbat --export-pdf report.pdf --font /path/to/font.ttf`.
+Print areas are session metadata; CSV has no place to store them, so they reset
+when the workbook is reopened.
+PDF export embeds the supplied font, resolves formatted font families from the
+system font database, and applies bold/italic along with cell formatting; bold
+and italic are synthesized in the PDF when the selected face has no matching
+variant. Charts are not yet rendered.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake spec
+BUDGET=1 bundle exec rake bench
+bundle exec rbs -I sig -I "$(bundle info --path furud)/sig" -I "$(bundle info --path denebola)/sig" validate
+gem build --strict rukbat.gemspec
+```
+
+The implementation is not yet a `0.1.0` release. Local performance gates pass;
+check the workplan's M17 acceptance gate for remaining compatibility, public
+CI, and dependency-release checks.

data/exe/rukbat

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "rukbat"
+
+begin
+options = {delimiter: :comma}
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: rukbat [options] FILE.csv|FILE.tsv"
+  opts.on("-t", "--tsv", "Use tab-separated values") { options[:delimiter] = :tsv }
+  opts.on("--export-pdf PATH", "Write the workbook as PDF and exit") { |path| options[:pdf] = path }
+  opts.on("--font PATH", "TrueType font to embed in PDF output") { |path| options[:font] = path }
+  opts.on("-v", "--version", "Print version") { puts Rukbat::VERSION; exit }
+  opts.on("-h", "--help", "Show help") { puts opts; exit }
+end
+parser.parse!
+abort parser.to_s unless ARGV.length == 1
+
+path = File.expand_path(ARGV.fetch(0))
+delimiter = options[:delimiter] == :tsv || File.extname(path).downcase == ".tsv" ? :tsv : :comma
+workbook = File.file?(path) ? Rukbat::CSVFile.read(path, delimiter: delimiter) : Rukbat::Workbook.new
+if options[:pdf]
+  abort "--font PATH is required for PDF export" unless options[:font]
+  Rukbat::PDFFile.write(workbook, options[:pdf], font: options[:font])
+  puts "Exported #{File.basename(options[:pdf])}"
+  exit
+end
+Rukbat::Application.new(workbook: workbook, path: path, delimiter: delimiter).run
+rescue OptionParser::ParseError => error
+  warn "rukbat: #{error.message}"
+  warn parser
+  exit 2
+rescue Rukbat::Error, Menkar::Error, SystemCallError => error
+  warn "rukbat: #{error.message}"
+  exit 1
+end

data/lib/rukbat/application.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Rukbat
+  class Application
+    attr_reader :workbook, :path, :view
+
+    def initialize(workbook:, path:, delimiter: :comma, backend: :auto)
+      @workbook, @path, @delimiter = workbook, File.expand_path(path), delimiter
+      @backend = backend == :auto ? default_backend : backend
+      @view = GridView.new(workbook, on_save: method(:save))
+    end
+
+    def run
+      app = Zaniah::App.new
+      window = app.open_window(backend: @backend, width: 1100, height: 720,
+        title: "Rukbat — #{File.basename(@path)}") { @view }
+      window.on_input { |event| @view.handle_shortcut(event, window) }
+      app.run
+    end
+
+    def save
+      CSVFile.write(@workbook, @path, delimiter: @delimiter)
+      "Saved #{File.basename(@path)}"
+    end
+
+    private
+
+    def default_backend
+      return :mac if RUBY_PLATFORM.include?("darwin")
+      return :windows if RUBY_PLATFORM.match?(/mswin|mingw/)
+      return :linux if ENV["DISPLAY"] || ENV["WAYLAND_DISPLAY"]
+      return :tui if $stdin.tty? && $stdout.tty?
+
+      raise Error, "no display or interactive terminal is available"
+    end
+  end
+end

data/lib/rukbat/atomic_file.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Rukbat
+  module AtomicFile
+    module_function
+
+    def install(source, target, replace:)
+      replace ? File.rename(source, target) : File.link(source, target)
+    end
+  end
+end

data/lib/rukbat/cell_source.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Rukbat
+  class CellSource
+    def initialize(workbook)
+      @workbook = workbook
+    end
+
+    def value_at(reference)
+      @workbook.input_at(reference.row, reference.column, sheet: reference.sheet)
+    end
+
+    def each_in(area)
+      return enum_for(__method__, area) unless block_given?
+
+      sheet_name = area.sheet || @workbook.active_sheet
+      return self unless @workbook.sheet_names.include?(sheet_name)
+
+      @workbook.sheet(sheet_name).each_in(area.top - 1, area.left - 1, area.bottom - 1, area.right - 1) do |point, value|
+        yield Furud::Reference.new(sheet: sheet_name, row: point.row + 1, column: point.column + 1), value
+      end
+      self
+    end
+  end
+end

data/lib/rukbat/csv_file.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "digest"
+require "tempfile"
+
+module Rukbat
+  module CSVFile
+    module_function
+    MAX_EXPORT_CELLS = 10_000_000
+
+    def read(path, delimiter: :comma, sheet: "Sheet1", hint: nil)
+      snapshot = Xamidimura::SourceRevision.read(path)
+      bytes = snapshot.bytes
+      detection = Menkar.detect(bytes, hint: hint)
+      raise Error, "CSV input is binary" if detection.binary
+
+      text = Menkar.decode(bytes, detection)
+      delimiter = delimiter_for(delimiter)
+      rows = CSV.parse(text, col_sep: delimiter).map { |row| row.map { |value| value && parse_cell(value) } }
+      Workbook.from_rows(rows, sheet: sheet).tap do |workbook|
+        workbook.__send__(:bind_source, path, snapshot.digest)
+      end
+    rescue CSV::MalformedCSVError => error
+      raise Error, "invalid CSV: #{error.message}"
+    rescue Menkar::Error, SystemCallError => error
+      raise Error, "cannot read CSV: #{error.message}"
+    rescue Xamidimura::Error => error
+      raise Error, "cannot read CSV: #{error.message}"
+    end
+
+    def write(workbook, path, delimiter: :comma, sheet: workbook.active_sheet, values: :calculated,
+      expected_digest: :auto)
+      col_sep = delimiter_for(delimiter)
+      raise ArgumentError, "values must be :calculated or :input" unless %i[calculated input].include?(values)
+      expected_digest = workbook.source_digest_for(path) if expected_digest == :auto
+      unless expected_digest.nil? || expected_digest == :absent || expected_digest.is_a?(String)
+        raise ArgumentError, "expected_digest must be :auto, :absent, a String, or nil"
+      end
+
+      current = workbook.sheet(sheet)
+      rows, columns = current.row_count, current.column_count
+      exported_cells = rows * [columns, 1].max
+      raise Error, "CSV export exceeds #{MAX_EXPORT_CELLS} cells" if exported_cells > MAX_EXPORT_CELLS
+
+      digest = Digest::SHA256.new
+      write_atomically(path, expected_digest) do |file|
+        current.row_count.times do |row|
+          row_cells = Array.new(current.column_count) do |column|
+            input = workbook.input_at(row + 1, column + 1, sheet: sheet)
+            value = values == :input || !input.is_a?(String) || !input.start_with?("=") ? input : workbook[row + 1, column + 1, sheet: sheet]
+            value.is_a?(Furud::ErrorValue) ? value.to_s : value
+          end
+          line = CSV.generate_line(row_cells, col_sep: col_sep, row_sep: "\r\n").encode(Encoding::UTF_8).b
+          file.write(line)
+          digest.update(line)
+        end
+      end
+      workbook.__send__(:bind_source, path, digest.hexdigest)
+      path
+    rescue Xamidimura::Error, SystemCallError, EncodingError => error
+      raise Error, "cannot write CSV: #{error.message}"
+    end
+
+    def infer(value)
+      return Integer(value, 10) if value.match?(/\A[+-]?(?:0|[1-9]\d*)\z/)
+      if value.match?(/\A[+-]?(?:(?:0|[1-9]\d*)(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?\z/i)
+        number = Float(value)
+        return number if number.finite?
+      end
+
+      value
+    end
+    private_class_method :infer
+
+    def parse_cell(value)
+      return nil if value.empty?
+
+      infer(value)
+    end
+
+    def delimiter_for(value)
+      case value
+      when :comma then ","
+      when :tab, :tsv then "\t"
+      when String then value
+      else raise ArgumentError, "delimiter must be :comma, :tab, :tsv, or a String"
+      end
+    end
+    private_class_method :delimiter_for
+
+    def write_atomically(path, expected_digest)
+      target = File.expand_path(path)
+      Tempfile.create([".rukbat-", ".tmp"], File.dirname(target), binmode: true) do |file|
+        yield file
+        file.flush
+        file.fsync
+        stat = begin
+          File.lstat(target)
+        rescue Errno::ENOENT
+          nil
+        end
+        raise Error, "CSV target must be a regular file" if stat && !stat.file?
+        if expected_digest == :absent && stat
+          raise Error, "CSV file appeared since the workbook was opened"
+        elsif expected_digest.is_a?(String) && (!stat || Xamidimura::SourceRevision.file_digest(target) != expected_digest)
+          raise Error, "CSV file changed since it was loaded"
+        end
+
+        mode = stat ? stat.mode & 0o7777 : 0o666 & ~File.umask
+        # ponytail: the digest check is advisory; an external writer racing the final rename needs OS-specific compare-and-swap locking.
+        file.chmod(mode)
+        file.close
+        AtomicFile.install(file.path, target, replace: expected_digest != :absent)
+      end
+      begin
+        File.open(File.dirname(target), "r", &:fsync)
+      rescue SystemCallError, IOError
+        # Directory fsync is unavailable on some supported platforms.
+      end
+    rescue Errno::ENOENT
+      raise Error, "CSV target directory does not exist"
+    end
+    private_class_method :write_atomically
+  end
+end