sangi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ffacfdf861aea59dabc76828c2dd031aca04c085a44879483e97065b213c3a5
+  data.tar.gz: c20326becf52746e40dde658664098e74f7542d0e890e6f1971525793f95bcb5
+SHA512:
+  metadata.gz: c3a73cf7c5c9a9ab9cc37969ebe1aaa23015bc3ab75f20574aae81c63291f6d441fe01a4755594b994ac91ef0217fad5f88fe2dcb48a933c758e6145591585bc
+  data.tar.gz: 8691de8b1f57efdf538f4d84f874e01599278c3e121210faf513b98cecf160a9e54a9c8c237f43fb2cc3adeb2341504127c3fcd8ef4ce47b59cb0fc621fee41d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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,111 @@
+# 算木
+
+此器者，象算木之法，以西字之畫陳整數加減之程者也。其器以紅玉之術作之，行於命令之列。甲行、乙行存本數以爲觀，作行則置棒一枚，去棒一枚，令算術進退之迹，皆見於目。
+
+## 置法
+
+此庫不假外玉。
+
+```
+ruby -Ilib exe/sangi --version
+```
+
+欲鑄爲玉，則行下命。
+
+```
+gem build sangi.gemspec
+gem install ./sangi-0.1.0.gem
+```
+
+## 用法
+
+```
+exe/sangi
+exe/sangi "128+47"
+exe/sangi "100-7" --all
+exe/sangi "-12+7" --learn
+exe/sangi "3--5" --mode hist --all
+exe/sangi "128+47" --export steps.txt
+```
+
+無引數而起之，則入讀評印之場，待人書式。
+
+```
+sangi> 7+8
+```
+
+## 所受之式
+
+今之初版，唯受二項有符整數之加減。
+
+```
+1+2
+1 - 2
+-1+2
+-1 - 2
+3--5
+3 - -5
+0+0
+```
+
+## 鍵法
+
+觀段之時，用鍵如下。
+
+```
+n / Enter  進一段
+p          退一段
+r          還始段
+e          至終段
+a          自行進止
+q          去觀段
+?          示鍵法
+```
+
+## 選項
+
+```
+--mode edu|hist
+--zero blank|digit|circle
+--sign modern|slash|color|dual
+--explain none|brief|learn
+--learn
+--all
+--export PATH
+--max-digits N
+--max-steps N
+--no-color
+--version
+--help
+```
+
+教育之式，以 `0` 顯零，以今符 `-` 顯負數。史風之式，零則空之，負數則加斜記以識之。然史風者，取算木之風而濃之耳，非謂盡合古籍舊法，毫釐不差也。
+
+## 例
+
+```
+exe/sangi "7+8" --all
+exe/sangi "99+1" --all
+exe/sangi "100-7" --all
+exe/sangi "-12+7" --all
+exe/sangi "3--5" --all
+exe/sangi "128+47" --mode edu --learn --all
+exe/sangi "128+47" --mode hist --all
+exe/sangi "128+47" --zero blank --sign slash --all
+exe/sangi "128+47" --export steps.txt
+```
+
+其所得當如下。
+
+```
+7+8       -> 15
+99+1      -> 100
+100-7     -> 93
+-12+7     -> -5
+3--5      -> 8
+128+47    -> 175
+```
+
+## 未及
+
+乘除、小數、分數、萬國符號之算木字、萬國符號之罫線、圖形窓、網版，今皆未及。數大則段亦多，畫幅亦廣。若端末座之幅不足，則出警辭；然終端狹隘，畫或折行。

data/exe/sangi

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/sangi"
+
+exit Sangi::CLI.new.run(ARGV)

data/lib/sangi/board.rb

@@ -0,0 +1,35 @@
+module Sangi
+  class Board
+    attr_accessor :rows, :highlight
+
+    def self.from_numbers(a:, b:, work:, place_count:, rod_factory:)
+      new(
+        rows: {
+          a: Row.from_integer(name: :a, value: a, place_count: place_count, rod_factory: rod_factory),
+          b: Row.from_integer(name: :b, value: b, place_count: place_count, rod_factory: rod_factory),
+          work: Row.from_integer(name: :work, value: work, place_count: place_count, rod_factory: rod_factory)
+        }
+      )
+    end
+
+    def initialize(rows:, highlight: nil)
+      @rows = rows
+      @highlight = highlight
+    end
+
+    def row(name)
+      rows.fetch(name)
+    end
+
+    def place_count
+      rows.values.map { |row| row.cells.size }.max || 0
+    end
+
+    def clone_deep
+      Board.new(
+        rows: rows.transform_values(&:clone_deep),
+        highlight: highlight&.dup
+      )
+    end
+  end
+end

data/lib/sangi/cell.rb

@@ -0,0 +1,60 @@
+module Sangi
+  class Cell
+    attr_reader :place_index
+    attr_accessor :unit_rods, :five_rods
+
+    def self.from_digit(place_index:, digit:, rod_factory:)
+      raise ValidationError, "digit must be between 0 and 9" unless (0..9).cover?(digit)
+
+      five_count = digit / 5
+      unit_count = digit % 5
+      new(
+        place_index: place_index,
+        unit_rods: unit_count.times.map { rod_factory.build(:unit) },
+        five_rods: five_count.times.map { rod_factory.build(:five) }
+      )
+    end
+
+    def self.empty(place_index:)
+      new(place_index: place_index)
+    end
+
+    def initialize(place_index:, unit_rods: [], five_rods: [])
+      @place_index = place_index
+      @unit_rods = unit_rods
+      @five_rods = five_rods
+    end
+
+    def orientation
+      place_index.even? ? :vertical : :horizontal
+    end
+
+    def value
+      unit_rods.size + five_rods.size * 5
+    end
+
+    def add_rod(rod)
+      case rod.kind
+      when :unit then unit_rods << rod
+      when :five then five_rods << rod
+      else raise ValidationError, "invalid rod kind"
+      end
+    end
+
+    def remove_rod(kind)
+      case kind
+      when :unit then unit_rods.pop
+      when :five then five_rods.pop
+      else raise ValidationError, "invalid rod kind"
+      end
+    end
+
+    def clone_deep
+      Cell.new(
+        place_index: place_index,
+        unit_rods: unit_rods.dup,
+        five_rods: five_rods.dup
+      )
+    end
+  end
+end

data/lib/sangi/cli.rb

@@ -0,0 +1,142 @@
+require "optparse"
+
+module Sangi
+  class CLI
+    SEPARATOR = "=" * 60
+
+    def run(argv)
+      args = argv.dup
+      expression_source = extract_expression!(args)
+      options, parser = parse_options(args)
+      if options[:help]
+        puts parser
+        return 0
+      end
+      if options[:version]
+        puts VERSION
+        return 0
+      end
+
+      expression_source ||= args.shift
+      raise ParseError, "式は1つだけ指定してください。" unless args.empty?
+
+      config = build_config(options)
+      return REPL.new(config: config).start if expression_source.nil?
+
+      run_expression(expression_source, config)
+      0
+    rescue OptionParser::ParseError => e
+      warn e.message
+      1
+    rescue Sangi::Error => e
+      warn e.message
+      warn e.full_message if ENV["SANGI_DEBUG"] == "1"
+      1
+    end
+
+    private
+
+    def extract_expression!(args)
+      expression_index = args.index { |arg| expression_like?(arg) }
+      return nil if expression_index.nil?
+
+      args.delete_at(expression_index)
+    end
+
+    def expression_like?(arg)
+      /\A\s*[+-]?\d+\s*[+-]\s*[+-]?\d+\s*\z/.match?(arg.to_s)
+    end
+
+    def parse_options(args)
+      options = {
+        mode: :edu,
+        zero_mode: nil,
+        sign_mode: nil,
+        explain_mode: :brief,
+        all: false,
+        export_path: nil,
+        max_digits: 8,
+        max_steps: 10_000,
+        color: true,
+        version: false,
+        help: false
+      }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: sangi [EXPR] [options]"
+        opts.separator ""
+        opts.separator "Examples:"
+        opts.separator "  sangi"
+        opts.separator "  sangi \"128+47\""
+        opts.separator "  sangi \"100-7\" --all"
+        opts.separator "  sangi \"-12+7\" --learn"
+        opts.separator "  sangi \"3--5\" --mode hist --all"
+        opts.separator "  sangi \"128+47\" --export steps.txt"
+        opts.separator ""
+        opts.separator "Options:"
+
+        opts.on("--mode MODE", "edu or hist") { |value| options[:mode] = value.to_sym }
+        opts.on("--zero MODE", "blank, digit, circle") { |value| options[:zero_mode] = value.to_sym }
+        opts.on("--sign MODE", "modern, slash, color, dual") { |value| options[:sign_mode] = value.to_sym }
+        opts.on("--explain MODE", "none, brief, learn") { |value| options[:explain_mode] = value.to_sym }
+        opts.on("--learn", "same as --explain learn") { options[:explain_mode] = :learn }
+        opts.on("--all", "print all steps") { options[:all] = true }
+        opts.on("--export PATH", "write all steps to PATH") { |value| options[:export_path] = value }
+        opts.on("--max-digits N", Integer, "maximum input digits") { |value| options[:max_digits] = value }
+        opts.on("--max-steps N", Integer, "maximum generated steps") { |value| options[:max_steps] = value }
+        opts.on("--no-color", "disable ANSI color") { options[:color] = false }
+        opts.on("--version", "print version") { options[:version] = true }
+        opts.on("-h", "--help", "print help") { options[:help] = true }
+      end
+
+      parser.parse!(args)
+      [options, parser]
+    end
+
+    def build_config(options)
+      Config.new(
+        mode: options[:mode],
+        zero_mode: options[:zero_mode],
+        sign_mode: options[:sign_mode],
+        explain_mode: options[:explain_mode],
+        all: options[:all],
+        export_path: options[:export_path],
+        max_digits: options[:max_digits],
+        max_steps: options[:max_steps],
+        color: color_output_enabled?(options)
+      )
+    end
+
+    def color_output_enabled?(options)
+      options[:color] && $stdout.respond_to?(:tty?) && $stdout.tty?
+    end
+
+    def run_expression(source, config)
+      expression = Parser.new(config).parse(source)
+      steps = Engine.new(config).build_steps(expression)
+      renderer = Renderer::AsciiRenderer.new(config)
+
+      export_steps(config, steps) if config.export_path
+      print_all_steps(renderer, steps) if config.all
+      return if config.all || config.export_path
+
+      StepViewer.new(steps: steps, renderer: renderer).start
+    end
+
+    def print_all_steps(renderer, steps)
+      TerminalWidthWarning.new(output: $stdout).warn_once(steps, error_output: $stderr)
+      steps.each do |step|
+        puts SEPARATOR
+        puts "step #{step.index}/#{steps.size}"
+        print renderer.render(step, total_steps: steps.size)
+      end
+      puts SEPARATOR
+    end
+
+    def export_steps(config, steps)
+      export_config = config.with(color: false)
+      export_renderer = Renderer::AsciiRenderer.new(export_config)
+      Exporter::TextExporter.new(export_config, export_renderer).export(config.export_path, steps)
+    end
+  end
+end

data/lib/sangi/config.rb

@@ -0,0 +1,75 @@
+module Sangi
+  class Config
+    VALID_MODES = %i[edu hist].freeze
+    VALID_ZERO_MODES = %i[blank digit circle].freeze
+    VALID_SIGN_MODES = %i[modern slash color dual].freeze
+    VALID_EXPLAIN_MODES = %i[none brief learn].freeze
+
+    attr_reader :mode, :zero_mode, :sign_mode, :explain_mode
+    attr_reader :all, :export_path, :max_digits, :max_steps, :color
+
+    def initialize(
+      mode: :edu,
+      zero_mode: nil,
+      sign_mode: nil,
+      explain_mode: :brief,
+      all: false,
+      export_path: nil,
+      max_digits: 8,
+      max_steps: 10_000,
+      color: true
+    )
+      @mode = normalize_symbol(mode)
+      @zero_mode = normalize_symbol(zero_mode) || default_zero_mode(@mode)
+      @sign_mode = normalize_symbol(sign_mode) || default_sign_mode(@mode)
+      @explain_mode = normalize_symbol(explain_mode)
+      @all = all
+      @export_path = export_path
+      @max_digits = Integer(max_digits)
+      @max_steps = Integer(max_steps)
+      @color = color ? true : false
+      validate!
+    rescue ArgumentError
+      raise ValidationError, "数値オプションには整数を指定してください。"
+    end
+
+    def with(**overrides)
+      Config.new(
+        mode: overrides.fetch(:mode, mode),
+        zero_mode: overrides.fetch(:zero_mode, zero_mode),
+        sign_mode: overrides.fetch(:sign_mode, sign_mode),
+        explain_mode: overrides.fetch(:explain_mode, explain_mode),
+        all: overrides.fetch(:all, all),
+        export_path: overrides.fetch(:export_path, export_path),
+        max_digits: overrides.fetch(:max_digits, max_digits),
+        max_steps: overrides.fetch(:max_steps, max_steps),
+        color: overrides.fetch(:color, color)
+      )
+    end
+
+    private
+
+    def normalize_symbol(value)
+      return nil if value.nil?
+
+      value.to_sym
+    end
+
+    def default_zero_mode(mode)
+      mode == :hist ? :blank : :digit
+    end
+
+    def default_sign_mode(mode)
+      mode == :hist ? :slash : :modern
+    end
+
+    def validate!
+      raise ValidationError, "invalid mode" unless VALID_MODES.include?(mode)
+      raise ValidationError, "invalid zero mode" unless VALID_ZERO_MODES.include?(zero_mode)
+      raise ValidationError, "invalid sign mode" unless VALID_SIGN_MODES.include?(sign_mode)
+      raise ValidationError, "invalid explain mode" unless VALID_EXPLAIN_MODES.include?(explain_mode)
+      raise ValidationError, "max_digits must be positive" unless max_digits.positive?
+      raise ValidationError, "max_steps must be positive" unless max_steps.positive?
+    end
+  end
+end

data/lib/sangi/engine.rb

@@ -0,0 +1,75 @@
+module Sangi
+  class Engine
+    def initialize(config)
+      @config = config
+    end
+
+    def build_steps(expression)
+      left = expression.left
+      right = expression.effective_right
+
+      steps = build_steps_for_normalized(left, right, expression)
+      validate_step_count!(steps)
+      steps
+    end
+
+    private
+
+    def build_steps_for_normalized(left, right, expression)
+      return copy_steps(left, right, 0, expression) if left.zero? && right.zero?
+      return copy_steps(left, right, left, expression) if right.zero?
+      return copy_steps(left, right, right, expression) if left.zero?
+
+      if same_sign?(left, right)
+        result_sign = left.negative? ? -1 : 1
+        return AdditionEngine.new(@config).build(
+          abs_a: left.abs,
+          abs_b: right.abs,
+          result_sign: result_sign,
+          display_a: left,
+          display_b: right,
+          expression: expression
+        )
+      end
+
+      comparison = left.abs <=> right.abs
+      return copy_steps(left, right, 0, expression) if comparison.zero?
+
+      if comparison.positive?
+        SubtractionEngine.new(@config).build(
+          minuend_abs: left.abs,
+          subtrahend_abs: right.abs,
+          result_sign: left.negative? ? -1 : 1,
+          expression: expression
+        )
+      else
+        SubtractionEngine.new(@config).build(
+          minuend_abs: right.abs,
+          subtrahend_abs: left.abs,
+          result_sign: right.negative? ? -1 : 1,
+          expression: expression
+        )
+      end
+    end
+
+    def same_sign?(left, right)
+      (left.negative? && right.negative?) || (left.positive? && right.positive?)
+    end
+
+    def copy_steps(left, right, result, expression)
+      CopyEngine.new(@config).build(
+        display_a: left,
+        display_b: right,
+        result: result,
+        expression: expression
+      )
+    end
+
+    def validate_step_count!(steps)
+      return if steps.size <= @config.max_steps
+
+      raise StepLimitError,
+            "ステップ数が上限を超えました。現在の上限: #{@config.max_steps}。上限を変更するには --max-steps N を指定してください。"
+    end
+  end
+end