liblouis-rb 0.1.0

data/test/test_braille_character.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class BrailleCharacterTest < Minitest::Test
+  def test_builds_from_mask_dots_and_unicode
+    from_mask = LibLouis::BrailleCharacter.new(137)
+    from_dots = LibLouis::BrailleCharacter.new([1, 4, 8])
+    from_unicode = LibLouis::BrailleCharacter.new("⢉")
+
+    assert_equal [1, 4, 8], from_mask.dots
+    assert_equal from_mask, from_dots
+    assert_equal from_mask, from_unicode
+    assert_equal 137, from_mask.to_i
+    assert_equal "⢉", from_mask.unicode_character
+  end
+
+  def test_dot_predicates_cover_all_eight_bits
+    character = LibLouis::BrailleCharacter.new(0b1010_0101)
+
+    assert character.dot1?
+    refute character.dot2?
+    assert character.dot3?
+    refute character.dot4?
+    refute character.dot5?
+    assert character.dot6?
+    refute character.dot7?
+    assert character.dot8?
+  end
+
+  def test_copies_preserve_all_dot_masks_and_ruby_freeze_semantics
+    (0..255).each do |mask|
+      original = LibLouis::BrailleCharacter.new(mask)
+      copies = [original.dup, original.clone, original.clone(freeze: false)]
+      copies.each do |copy|
+        refute_same original, copy
+        assert_equal original, copy
+        assert_equal original.hash, copy.hash
+        assert_equal mask, copy.mask
+      end
+      refute copies[0].frozen?
+      assert copies[1].frozen?
+      refute copies[2].frozen?
+    end
+  end
+
+  def test_frozen_cells_cannot_be_reinitialised_or_overwritten
+    cell = LibLouis::BrailleCharacter.new(137)
+    replacement = LibLouis::BrailleCharacter.new(1)
+
+    assert_raises(FrozenError) { cell.send(:initialize, 1) }
+    assert_raises(FrozenError) { cell.send(:initialize_copy, replacement) }
+    assert_equal 137, cell.mask
+  end
+
+  def test_rejects_invalid_values
+    assert_raises(RangeError) { LibLouis::BrailleCharacter.new(256) }
+    assert_raises(RangeError) { LibLouis::BrailleCharacter.new([9]) }
+    assert_raises(ArgumentError) { LibLouis::BrailleCharacter.new("a") }
+  end
+end
+

data/test/test_braille_table.rb

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+require_relative "translation_cases"
+require_relative "table_source_cases"
+require "pathname"
+require "stringio"
+require "tmpdir"
+
+class BrailleTableTest < Minitest::Test
+  def setup
+    @polish_case = TranslationCases.fetch("Pl-Pl-g1.utb")
+    @table = LibLouis::BrailleTable.new(@polish_case[:table])
+  end
+
+  def test_reports_native_version_and_table
+    expected_version = File.read(File.expand_path("../vendor/liblouis/configure.ac", __dir__))[
+      /AC_INIT\(\[Liblouis\],\s*\[([0-9.]+)\]/, 1
+    ]
+    assert_equal expected_version, LibLouis.version
+    assert @table.valid?
+    assert_equal "Pl-Pl-g1.utb", @table.file
+  end
+
+  def test_hides_native_representation_details
+    refute_respond_to LibLouis, :char_size
+    refute LibLouis.const_defined?(:DOTS_IO, false)
+    refute LibLouis.const_defined?(:UC_BRL, false)
+    %i[
+      PLAIN_TEXT ITALIC UNDERLINE BOLD
+      COMPUTER_BRAILLE NO_TRANSLATE NO_CONTRACT
+      NO_CONTRACTIONS COMPBRL_AT_CURSOR COMPBRL_LEFT_CURSOR
+      NO_UNDEFINED PARTIAL_TRANSLATION
+    ].each do |name|
+      refute LibLouis.const_defined?(name, false)
+    end
+  end
+
+  def test_native_logging_is_enabled_only_in_debug_mode
+    LibLouis.debug = false
+    refute LibLouis.debug?
+
+    stdout, stderr = capture_subprocess_io do
+      refute LibLouis::BrailleTable.new("definitely-missing-silent.ctb").valid?
+    end
+    assert_empty stdout
+    assert_empty stderr
+
+    LibLouis.debug = true
+    assert LibLouis.debug?
+    _stdout, stderr = capture_subprocess_io do
+      refute LibLouis::BrailleTable.new("definitely-missing-debug.ctb").valid?
+    end
+    assert_match(/definitely-missing-debug\.ctb/, stderr)
+    assert_raises(TypeError) { LibLouis.debug = 1 }
+  ensure
+    LibLouis.debug = false
+  end
+
+  def test_prefers_the_current_directory_before_bundled_tables
+    Dir.mktmpdir("liblouis-rb-cwd") do |directory|
+      File.binwrite(File.join(directory, "en-gb-g1.utb"), TableSourceCases::CUSTOM_TABLE)
+
+      with_cleared_native_cache do
+        Dir.chdir(directory) do
+          table = LibLouis::BrailleTable.new("en-gb-g1.utb")
+
+          assert_equal "Custom table source", table.display_name
+          assert_equal "⠿", table.get_braille("a").to_s
+        end
+      end
+    end
+  end
+
+  def test_falls_back_to_the_bundled_table_repository
+    test_case = TranslationCases.fetch("en-gb-comp8.ctb")
+
+    Dir.mktmpdir("liblouis-rb-empty") do |directory|
+      with_cleared_native_cache do
+        Dir.chdir(directory) do
+          table = LibLouis::BrailleTable.new(test_case[:table])
+
+          assert table.valid?
+          assert_equal test_case[:braille], table.get_braille(test_case[:source]).to_s
+        end
+      end
+    end
+  end
+
+  def test_accepts_an_exact_file_path_and_path_like_object
+    Dir.mktmpdir("liblouis-rb-path") do |directory|
+      path = File.join(directory, "custom-table.ctb")
+      File.binwrite(path, TableSourceCases::CUSTOM_TABLE)
+
+      table = LibLouis::BrailleTable.new(path)
+      path_table = LibLouis::BrailleTable.new(Pathname.new(path))
+
+      assert_equal path, table.file
+      assert_equal path, path_table.file
+      assert_equal "⠿", table.get_braille("a").to_s
+      assert_equal "⠿", path_table.get_braille("a").to_s
+    end
+  end
+
+  def test_accepts_a_table_directly_from_io
+    source = StringIO.new(TableSourceCases::CUSTOM_TABLE)
+    table = LibLouis::BrailleTable.new(source)
+
+    assert_equal TableSourceCases::CUSTOM_TABLE.bytesize, source.pos
+    assert File.file?(table.file)
+    assert_equal "Custom table source", table.display_name
+    assert_equal "⠿", table.get_braille("a").to_s
+
+    LibLouis.free
+    assert table.valid?
+    assert_equal "⠿", table.get_braille("a").to_s
+  end
+
+  def test_accepts_an_open_file_as_io
+    Dir.mktmpdir("liblouis-rb-file-io") do |directory|
+      path = File.join(directory, "file-io.ctb")
+      File.binwrite(path, TableSourceCases::CUSTOM_TABLE)
+
+      File.open(path, "rb") do |source|
+        table = LibLouis::BrailleTable.new(source)
+
+        assert_equal source.size, source.pos
+        refute_equal path, table.file
+        assert File.file?(table.file)
+        assert_equal "⠿", table.get_braille("a").to_s
+      end
+    end
+  end
+
+  def test_translates_the_requested_corpus
+    TranslationCases::CASES.each do |test_case|
+      table = LibLouis::BrailleTable.new(test_case[:table])
+      braille = table.get_braille(test_case[:source])
+
+      assert table.valid?, test_case[:table]
+      assert_instance_of LibLouis::BrailleText, braille, test_case[:table]
+      assert_equal test_case[:braille], braille.to_s, test_case[:table]
+      assert_equal braille.length, braille.input_positions.length, test_case[:table]
+      assert_equal test_case[:source].length, braille.output_positions.length, test_case[:table]
+    end
+  end
+
+  def test_back_translates_bidirectional_corpus_cases
+    TranslationCases::CASES.each do |test_case|
+      next unless test_case.key?(:back_translation)
+
+      table = LibLouis::BrailleTable.new(test_case[:table])
+      braille = table.get_braille(test_case[:source])
+
+      assert_equal test_case[:back_translation], table.get_text(braille), test_case[:table]
+      assert_equal test_case[:back_translation], table.get_text(test_case[:braille]), test_case[:table]
+    end
+  end
+
+  def test_forward_translation_grows_output_and_preserves_positions_and_typeforms
+    source = "space \\s 0\nlowercase a 1\nalways a #{Array.new(40, '1').join('-')}\n"
+    table = LibLouis::BrailleTable.new(StringIO.new(source))
+
+    [1, 10].each do |length|
+      forms = Array.new(length, :plain_text).freeze
+      cursor = length == 1 ? 0 : 1
+      braille = table.translate("a" * length, cursor_position: cursor, typeform: forms)
+
+      assert_equal "\u2801" * (40 * length), braille.to_s
+      assert_equal Array.new(length) { |index| index * 40 }, braille.output_positions
+      assert_equal (0...length).flat_map { |index| [index] * 40 }, braille.input_positions
+      assert_equal cursor * 40, braille.cursor_position
+      assert_equal Array.new(length, :plain_text), forms
+    end
+  end
+
+  def test_back_translation_grows_output_without_losing_input
+    source = "space \\s 0\nlowercase a 1\nnofor always #{'a' * 40} 1\n"
+    table = LibLouis::BrailleTable.new(StringIO.new(source))
+
+    [1, 10].each do |length|
+      assert_equal "a" * (40 * length), table.back_translate("\u2801" * length)
+    end
+  end
+
+  def test_translation_rejects_embedded_nul_instead_of_returning_a_prefix
+    assert_raises(ArgumentError) { @table.translate("a\0a") }
+    assert_raises(ArgumentError) { @table.back_translate("a\0a") }
+  end
+
+  def test_handles_empty_input
+    braille = @table.translate("")
+
+    assert braille.empty?
+    assert_equal "", @table.back_translate(braille)
+  end
+
+  def test_translation_metadata_is_part_of_braille_text
+    source = "ala"
+    braille = @table.translate(source, cursor_position: 1)
+
+    assert_equal [0, 1, 2], braille.input_positions
+    assert_equal [0, 1, 2], braille.output_positions
+    assert_equal 1, braille.cursor_position
+    assert braille.input_positions.frozen?
+    assert braille.output_positions.frozen?
+
+    without_cursor = @table.translate(source)
+    assert_nil without_cursor.cursor_position
+    assert_equal [0, 1, 2], without_cursor.input_positions
+    assert_equal [0, 1, 2], without_cursor.output_positions
+  end
+
+  def test_table_and_translation_survive_gc_compaction
+    source = @polish_case[:source]
+    braille = @table.translate(source, cursor_position: 1)
+    cursor_position = braille.cursor_position
+
+    GC.start
+    GC.compact if GC.respond_to?(:compact)
+
+    assert_equal @polish_case[:braille], braille.to_s
+    assert_equal cursor_position, braille.cursor_position
+    assert_equal @polish_case[:table], @table.file
+    assert @table.valid?
+  end
+
+  def test_character_and_dot_conversion
+    test_case = TranslationCases.fetch("en-gb-comp8.ctb")
+    table = LibLouis::BrailleTable.new(test_case[:table])
+    dots = table.characters_to_dots(test_case[:source])
+
+    assert_equal test_case[:braille], dots.to_s
+    assert_equal test_case[:source], table.dots_to_characters(dots)
+    assert_nil dots.input_positions
+    assert_nil dots.output_positions
+    assert_nil dots.cursor_position
+  end
+
+  def test_table_metadata_search_and_listing
+    english = LibLouis::BrailleTable.new("en-gb-g1.utb")
+
+    assert_match(/English uncontracted braille/, english.display_name)
+    assert_equal "en", english.metadata("language")
+    assert_equal "en-GB", english.metadata("region")
+    refute_empty LibLouis.tables
+    assert_instance_of LibLouis::BrailleTable,
+                       LibLouis.find_table("language:en grade:1")
+  end
+
+  def test_typeforms_use_symbols_and_table_emphasis_classes
+    test_case = TranslationCases.fetch("en-GB-g2.ctb")
+    table = LibLouis::BrailleTable.new(test_case[:table])
+    plain = Array.new(test_case[:source].length, :plain_text)
+
+    assert_equal %i[italic underline bold], table.emphasis_classes
+    refute_respond_to table, :typeform_for
+    assert_equal test_case[:braille], table.translate(test_case[:source], typeform: plain).to_s
+
+    styled = Array.new(test_case[:source].length, :plain_text)
+    styled[0] = %i[italic bold]
+    refute_equal test_case[:braille], table.translate(test_case[:source], typeform: styled).to_s
+
+    word = "the"
+    %i[computer_braille no_translate no_contract].each do |form|
+      assert_instance_of LibLouis::BrailleText,
+                         table.translate(word, typeform: Array.new(word.length, form))
+    end
+    assert_equal "⠞⠓⠑",
+                 table.translate(word, typeform: Array.new(word.length, :no_contract)).to_s
+  end
+
+  def test_translation_modes_use_symbols
+    table = LibLouis::BrailleTable.new("en-GB-g2.ctb")
+    word = "the"
+
+    assert_equal "⠮", table.translate(word).to_s
+    assert_equal "⠞⠓⠑", table.translate(word, mode: :no_contractions).to_s
+    assert_equal "⠞⠓⠑",
+                 table.translate(word, mode: %i[no_contractions suppress_undefined]).to_s
+
+    at_cursor = table.translate(word, mode: :computer_braille_at_cursor,
+                                cursor_position: 1)
+    before_cursor = table.translate(word, mode: :computer_braille_before_cursor,
+                                    cursor_position: 1)
+    assert_instance_of LibLouis::BrailleText, at_cursor
+    assert_instance_of LibLouis::BrailleText, before_cursor
+
+    braille = table.translate(word)
+    assert_instance_of String,
+                       table.back_translate(braille, mode: :partial_translation)
+  end
+
+  def test_hyphenation_with_a_dictionary_table
+    table = LibLouis::BrailleTable.new(["en-gb-g1.utb", "hyph_en_US.dic"])
+    word = "friend"
+    hyphens = table.hyphenate(word)
+
+    assert_equal word.length, hyphens.length
+    assert_match(/\A[01]+\z/, hyphens)
+    assert_equal hyphens, table.hyphenate(word, translated: false)
+    assert_raises(ArgumentError) { table.hyphenate(word, mode: :suppress_undefined) }
+    assert_raises(TypeError) { table.hyphenate(word, translated: 1) }
+  end
+
+  def test_validates_translation_arguments
+    source = @polish_case[:source]
+    assert_raises(ArgumentError) do
+      @table.translate(source, typeform: [:plain_text])
+    end
+    assert_raises(RangeError) do
+      @table.translate(source, cursor_position: source.length + 1)
+    end
+    assert_raises(TypeError) do
+      @table.translate(source, typeform: Array.new(source.length, 0))
+    end
+    assert_raises(TypeError) do
+      typeform = Array.new(source.length, :plain_text)
+      typeform[0] = [:plain_text, 4]
+      @table.translate(source, typeform: typeform)
+    end
+    assert_raises(ArgumentError) do
+      @table.translate(source, typeform: Array.new(source.length, :unknown_emphasis))
+    end
+    assert_raises(TypeError) do
+      @table.translate(source, typeform: true)
+    end
+  end
+
+  def test_rejects_options_that_do_not_affect_the_returned_value
+    source = @polish_case[:source]
+    braille = @table.translate(source)
+
+    assert_raises(ArgumentError) do
+      @table.translate(source, spacing: "0" * source.length)
+    end
+    assert_raises(ArgumentError) do
+      @table.translate(source, input_hyphens: "0" * source.length)
+    end
+    assert_raises(ArgumentError) do
+      @table.back_translate(braille, cursor_position: 0)
+    end
+    assert_raises(ArgumentError) do
+      @table.characters_to_dots(source, mode: :suppress_undefined)
+    end
+    assert_raises(ArgumentError) do
+      LibLouis::BrailleTable.new(@polish_case[:table], unknown: true)
+    end
+    refute_respond_to @table, :translate_full
+    refute_respond_to @table, :back_translate_full
+  end
+
+  def test_validates_modes_by_translation_direction
+    source = @polish_case[:source]
+    braille = @table.translate(source)
+
+    assert_raises(ArgumentError) do
+      @table.translate(source, mode: :partial_translation)
+    end
+    assert_raises(ArgumentError) do
+      @table.back_translate(braille, mode: :no_contractions)
+    end
+    assert_raises(ArgumentError) do
+      @table.translate(source, mode: :computer_braille_at_cursor)
+    end
+    assert_raises(TypeError) { @table.translate(source, mode: 0) }
+    assert_raises(TypeError) { @table.translate(source, mode: [:suppress_undefined, 1]) }
+    assert_raises(ArgumentError) { @table.translate(source, mode: :unknown_mode) }
+  end
+
+  private
+
+  def with_cleared_native_cache
+    LibLouis.free
+    yield
+  ensure
+    LibLouis.free
+  end
+end

data/test/test_braille_text.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class BrailleTextTest < Minitest::Test
+  def test_is_an_immutable_native_collection
+    text = LibLouis::BrailleText.new([1, [1, 2], 255])
+
+    assert_equal "⠁⠃⣿", text.unicode_text
+    assert_equal [1, 3, 255], text.map(&:mask)
+    assert_equal 3, text.length
+    assert_equal 3, text[1].mask
+    assert text.frozen?
+    assert text.characters.frozen?
+    assert_nil text.input_positions
+    assert_nil text.output_positions
+    assert_nil text.cursor_position
+  end
+
+  def test_builds_from_unicode_braille
+    text = LibLouis::BrailleText.new("⠀⠁⣿")
+
+    assert_equal [0, 1, 255], text.characters.map(&:mask)
+    assert_equal "⠀⠁⣿", text.to_s
+  end
+
+  def test_rejects_non_braille_text
+    assert_raises(ArgumentError) { LibLouis::BrailleText.new("abc") }
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+
+$LOAD_PATH.unshift(File.expand_path("../ext/liblouis", __dir__))
+require "liblouis"
+

data/test/translation_cases.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module TranslationCases
+  CASES = [
+    {
+      table: "en-gb-g1.utb",
+      source: "Speak, friend, and enter",
+      braille: "⠠⠎⠏⠑⠁⠅⠂⠀⠋⠗⠊⠑⠝⠙⠂⠀⠁⠝⠙⠀⠑⠝⠞⠑⠗"
+    },
+    {
+      table: "en-gb-comp8.ctb",
+      source: "Shall I compare thee to a summer's day?",
+      braille: "⡎⠓⠁⠇⠇⠀⡊⠀⠉⠕⠍⠏⠁⠗⠑⠀⠞⠓⠑⠑⠀⠞⠕⠀⠁⠀⠎⠥⠍⠍⠑⠗⠄⠎⠀⠙⠁⠽⠢",
+      back_translation: "Shall I compare thee to a summer's day?"
+    },
+    {
+      table: "en-GB-g2.ctb",
+      source: "To be, or not to be, that is the question.",
+      braille: "⠠⠖⠃⠑⠂⠀⠕⠗⠀⠝⠀⠖⠃⠑⠂⠀⠞⠀⠊⠎⠀⠮⠀⠐⠟⠲"
+    },
+    {
+      table: "Pl-Pl-g1.utb",
+      source: "Zażółć gęślą jaźń.",
+      braille: "⠨⠵⠁⠯⠬⠣⠩⠀⠛⠱⠪⠇⠡⠀⠚⠁⠮⠹⠄",
+      back_translation: "Zażółć gęślą jaźń."
+    }
+  ].map(&:freeze).freeze
+
+  def self.fetch(table)
+    CASES.fetch(CASES.index { |test_case| test_case[:table] == table })
+  end
+end
+