liblouis-rb 0.1.0

data/ext/liblouis/extconf.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+ROOT = File.expand_path("../..", __dir__)
+VENDOR_ROOT = File.join(ROOT, "vendor", "liblouis")
+VENDOR_SOURCE = File.join(VENDOR_ROOT, "liblouis")
+TABLES_PATH = File.join(VENDOR_ROOT, "tables").tr("\\", "/")
+DATA_PATH = File.dirname(VENDOR_ROOT).tr("\\", "/")
+
+header_template = File.join(VENDOR_SOURCE, "liblouis.h.in")
+configure_source = File.join(VENDOR_ROOT, "configure.ac")
+unless File.file?(header_template) && File.file?(configure_source) && Dir.exist?(TABLES_PATH)
+  abort "Liblouis sources are missing. Run: git submodule update --init --recursive"
+end
+liblouis_version = File.binread(configure_source)[/AC_INIT\(\[Liblouis\],\s*\[([0-9]+\.[0-9]+\.[0-9]+)\]/, 1]
+abort "Could not read the Liblouis version from configure.ac" unless liblouis_version
+
+# Encode paths as C strings in the header so the shell never splits them.
+def c_string(value)
+  '"' + value.b.bytes.map { |byte| format("\\%03o", byte) }.join + '"'
+end
+
+# This extension deliberately builds Liblouis in UCS-4 mode. Ruby strings are
+# Unicode, and a four-byte widechar avoids surrogate handling at the boundary.
+File.write(
+  File.join(__dir__, "liblouis.h"),
+  File.binread(header_template).sub("@WIDECHAR_TYPE@", "unsigned int")
+)
+
+File.write(
+  File.join(__dir__, "config.h"),
+  <<~CONFIG
+    #ifndef LIBLOUIS_RB_CONFIG_H
+    #define LIBLOUIS_RB_CONFIG_H
+    #define PACKAGE_VERSION "#{liblouis_version}"
+    #define WIDECHARS_ARE_UCS4 1
+    #define TABLESDIR #{c_string(TABLES_PATH)}
+    #define LIBLOUIS_RB_TABLES_DIR #{c_string(TABLES_PATH)}
+    #define LIBLOUIS_RB_DATA_DIR #{c_string(DATA_PATH)}
+    #include <stdbool.h>
+    #endif
+  CONFIG
+)
+
+liblouis_sources = %w[
+  compileTranslationTable.c
+  lou_translateString.c
+  lou_backTranslateString.c
+  commonTranslationFunctions.c
+  metadata.c
+  pattern.c
+  logging.c
+  utils.c
+  maketable.c
+]
+
+extension_sources = %w[
+  liblouis.c
+  braille_character.c
+  braille_text.c
+  braille_table.c
+  translation.c
+  table_source.c
+]
+
+$VPATH << "$(srcdir)/../../vendor/liblouis/liblouis"
+$srcs = extension_sources + liblouis_sources
+$INCFLAGS = "-I$(srcdir) -I$(srcdir)/../../vendor/liblouis/liblouis #{$INCFLAGS}"
+$defs << "-DWIDECHARS_ARE_UCS4=1"
+
+append_cflags("-std=c11")
+create_makefile("liblouis")

data/ext/liblouis/liblouis.c

@@ -0,0 +1,168 @@
+#include "liblouis_ext.h"
+
+#include <stddef.h>
+#include <stdlib.h>
+
+VALUE ll_mLibLouis;
+VALUE ll_cBrailleTable;
+VALUE ll_cBrailleCharacter;
+VALUE ll_cBrailleText;
+VALUE ll_eError;
+VALUE ll_eTranslationError;
+logLevels ll_log_level = LOU_LOG_OFF;
+
+VALUE
+ll_binary_storage(size_t bytes)
+{
+    VALUE storage;
+
+    if (bytes > (size_t)LONG_MAX)
+        rb_raise(rb_eNoMemError, "native buffer is too large");
+    storage = rb_str_new(NULL, (long)bytes);
+    if (bytes > 0)
+        memset(RSTRING_PTR(storage), 0, bytes);
+    return storage;
+}
+
+VALUE
+ll_wide_storage_from_string(VALUE input, int *length)
+{
+    VALUE string = StringValue(input);
+    VALUE utf8 = rb_str_export_to_enc(string, rb_utf8_encoding());
+    rb_encoding *encoding = rb_utf8_encoding();
+    const char *cursor = RSTRING_PTR(utf8);
+    const char *end = cursor + RSTRING_LEN(utf8);
+    long character_count = rb_enc_strlen(cursor, end, encoding);
+    VALUE storage;
+    int index = 0;
+
+    if (character_count > INT_MAX)
+        rb_raise(rb_eArgError, "input contains too many characters");
+
+    storage = ll_binary_storage((size_t)character_count * sizeof(widechar));
+    cursor = RSTRING_PTR(utf8);
+    end = cursor + RSTRING_LEN(utf8);
+    while (cursor < end) {
+        int bytes = 0;
+        unsigned int codepoint = rb_enc_codepoint_len(cursor, end, &bytes, encoding);
+        LL_PTR(widechar, storage)[index++] = (widechar)codepoint;
+        cursor += bytes;
+    }
+
+    *length = (int)character_count;
+    return storage;
+}
+
+VALUE
+ll_string_from_wide_storage(VALUE storage, int length)
+{
+    VALUE result = rb_enc_str_new(NULL, 0, rb_utf8_encoding());
+    int index;
+
+    for (index = 0; index < length; index++) {
+        unsigned int codepoint = (unsigned int)LL_PTR(widechar, storage)[index];
+        if (codepoint > 0x10ffff || (codepoint >= 0xd800 && codepoint <= 0xdfff))
+            rb_raise(ll_eTranslationError, "Liblouis returned invalid Unicode codepoint U+%04X", codepoint);
+        rb_str_buf_append(result, rb_enc_uint_chr(codepoint, rb_utf8_encoding()));
+    }
+    return result;
+}
+
+static VALUE
+ll_version(VALUE module)
+{
+    (void)module;
+    return rb_usascii_str_new_cstr(lou_version());
+}
+
+static VALUE
+ll_table_path(VALUE module)
+{
+    const char *path = getenv("LOUIS_TABLEPATH");
+
+    (void)module;
+    return rb_utf8_str_new_cstr(path && path[0] ? path : LIBLOUIS_RB_TABLES_DIR);
+}
+
+static VALUE
+ll_set_table_path(VALUE module, VALUE path)
+{
+    VALUE string = StringValue(path);
+    VALUE environment = rb_const_get(rb_cObject, rb_intern("ENV"));
+
+    (void)module;
+    StringValueCStr(string);
+    rb_funcall(environment, rb_intern("[]="), 2,
+               rb_str_new_cstr("LOUIS_TABLEPATH"), string);
+    lou_free();
+    return path;
+}
+
+static void
+ll_restore_native_state(void)
+{
+    lou_setLogLevel(LOU_LOG_OFF);
+    lou_setDataPath(LIBLOUIS_RB_DATA_DIR);
+    lou_setLogLevel(ll_log_level);
+}
+
+static VALUE
+ll_free_native(VALUE module)
+{
+    (void)module;
+    lou_free();
+    ll_restore_native_state();
+    return Qnil;
+}
+
+static VALUE
+ll_debug_p(VALUE module)
+{
+    (void)module;
+    return ll_log_level == LOU_LOG_DEBUG ? Qtrue : Qfalse;
+}
+
+static VALUE
+ll_set_debug(VALUE module, VALUE enabled)
+{
+    (void)module;
+    if (enabled != Qtrue && enabled != Qfalse)
+        rb_raise(rb_eTypeError, "debug must be true or false");
+    ll_log_level = enabled == Qtrue ? LOU_LOG_DEBUG : LOU_LOG_OFF;
+    lou_setLogLevel(ll_log_level);
+    return enabled;
+}
+
+static void
+ll_end_proc(VALUE ignored)
+{
+    (void)ignored;
+    lou_free();
+    ll_cleanup_table_sources();
+}
+
+void
+Init_liblouis(void)
+{
+    ll_mLibLouis = rb_define_module("LibLouis");
+    ll_eError = rb_define_class_under(ll_mLibLouis, "Error", rb_eStandardError);
+    ll_eTranslationError = rb_define_class_under(ll_mLibLouis, "TranslationError", ll_eError);
+
+    rb_define_const(ll_mLibLouis, "VERSION", rb_obj_freeze(rb_usascii_str_new_cstr("0.1.0")));
+
+    rb_define_module_function(ll_mLibLouis, "version", ll_version, 0);
+    rb_define_module_function(ll_mLibLouis, "table_path", ll_table_path, 0);
+    rb_define_module_function(ll_mLibLouis, "table_path=", ll_set_table_path, 1);
+    rb_define_module_function(ll_mLibLouis, "debug?", ll_debug_p, 0);
+    rb_define_module_function(ll_mLibLouis, "debug=", ll_set_debug, 1);
+    rb_define_module_function(ll_mLibLouis, "free", ll_free_native, 0);
+
+    rb_define_const(ll_mLibLouis, "TABLES_PATH", rb_obj_freeze(rb_utf8_str_new_cstr(LIBLOUIS_RB_TABLES_DIR)));
+
+    ll_restore_native_state();
+    ll_init_table_source();
+    ll_init_braille_character();
+    ll_init_braille_text();
+    ll_init_braille_table();
+    rb_set_end_proc(ll_end_proc, Qnil);
+}

data/ext/liblouis/liblouis_ext.h

@@ -0,0 +1,49 @@
+#ifndef LIBLOUIS_RB_EXT_H
+#define LIBLOUIS_RB_EXT_H
+
+#include "config.h"
+#include "ruby.h"
+#include "ruby/encoding.h"
+#include "liblouis.h"
+
+#include <stdint.h>
+#include <string.h>
+#include <limits.h>
+
+extern VALUE ll_mLibLouis;
+extern VALUE ll_cBrailleTable;
+extern VALUE ll_cBrailleCharacter;
+extern VALUE ll_cBrailleText;
+extern VALUE ll_eError;
+extern VALUE ll_eTranslationError;
+extern logLevels ll_log_level;
+
+void ll_init_braille_character(void);
+void ll_init_braille_text(void);
+void ll_init_braille_table(void);
+void ll_init_translation(void);
+void ll_init_table_source(void);
+void ll_cleanup_table_sources(void);
+
+VALUE ll_table_source_normalize(VALUE input);
+const char *ll_table_name(VALUE table);
+
+VALUE ll_binary_storage(size_t bytes);
+VALUE ll_wide_storage_from_string(VALUE input, int *length);
+VALUE ll_string_from_wide_storage(VALUE storage, int length);
+
+VALUE ll_character_new(uint8_t mask);
+uint8_t ll_character_mask(VALUE character);
+
+VALUE ll_braille_text_from_dot_storage(VALUE storage, int length);
+VALUE ll_braille_text_from_translation(VALUE storage, int length,
+                                       VALUE input_positions_storage,
+                                       VALUE output_positions_storage,
+                                       int input_length, int cursor_given,
+                                       int cursor_position);
+VALUE ll_braille_text_to_dot_storage(VALUE text, int *length);
+int ll_braille_text_p(VALUE value);
+
+#define LL_PTR(type, storage) ((type *)RSTRING_PTR(storage))
+
+#endif

data/ext/liblouis/table_source.c

@@ -0,0 +1,161 @@
+#include "liblouis_ext.h"
+
+#include "ruby/io.h"
+
+#include <errno.h>
+#include <fcntl.h>
+
+#ifdef _WIN32
+#include <process.h>
+#define ll_process_id _getpid
+#else
+#include <unistd.h>
+#define ll_process_id getpid
+#endif
+
+#ifndef O_BINARY
+#define O_BINARY 0
+#endif
+
+static ID id_read;
+static ID id_to_path;
+static ID id_join;
+static ID id_aref;
+static ID id_delete;
+static unsigned long long ll_temporary_sequence;
+static VALUE ll_temporary_paths;
+
+static VALUE
+ll_table_path_string(VALUE value)
+{
+    VALUE string = rb_str_dup(StringValue(value));
+
+    StringValueCStr(string);
+    rb_enc_associate(string, rb_utf8_encoding());
+    return rb_obj_freeze(string);
+}
+
+static VALUE
+ll_temporary_directory(void)
+{
+    static const char *names[] = {"TMPDIR", "TMP", "TEMP"};
+    VALUE environment = rb_const_get(rb_cObject, rb_intern("ENV"));
+    size_t index;
+
+    for (index = 0; index < sizeof(names) / sizeof(names[0]); index++) {
+        VALUE value = rb_funcall(environment, id_aref, 1, rb_str_new_cstr(names[index]));
+        if (RB_TYPE_P(value, T_STRING) && RSTRING_LEN(value) > 0)
+            return value;
+    }
+#ifdef _WIN32
+    return rb_dir_getwd();
+#else
+    return rb_filesystem_str_new_cstr("/tmp");
+#endif
+}
+
+static VALUE
+ll_materialize_table_io(VALUE source)
+{
+    VALUE contents = rb_funcall(source, id_read, 0);
+    VALUE directory;
+    VALUE basename;
+    VALUE path = Qnil;
+    VALUE output;
+    int descriptor = -1;
+    int attempt;
+
+    if (NIL_P(contents))
+        contents = rb_str_new(NULL, 0);
+    else
+        StringValue(contents);
+
+    directory = ll_temporary_directory();
+
+    for (attempt = 0; attempt < 100; attempt++) {
+        basename = rb_sprintf("liblouis-rb-%ld-%llu.tbl",
+                              (long)ll_process_id(), ++ll_temporary_sequence);
+        path = rb_funcall(rb_cFile, id_join, 2, directory, basename);
+        descriptor = rb_cloexec_open(StringValueCStr(path),
+                                     O_WRONLY | O_CREAT | O_EXCL | O_BINARY, 0600);
+        if (descriptor >= 0)
+            break;
+        if (errno != EEXIST)
+            rb_sys_fail_str(path);
+    }
+    if (descriptor < 0)
+        rb_raise(rb_eIOError, "could not allocate a temporary Liblouis table file");
+
+    rb_ary_push(ll_temporary_paths, path);
+    output = rb_io_fdopen(descriptor, O_WRONLY | O_BINARY, StringValueCStr(path));
+    rb_io_write(output, contents);
+    rb_io_close(output);
+    return ll_table_path_string(path);
+}
+
+static VALUE
+ll_normalize_table_source(VALUE source)
+{
+    if (RB_TYPE_P(source, T_STRING))
+        return ll_table_path_string(source);
+    if (rb_obj_is_kind_of(source, rb_cIO))
+        return ll_materialize_table_io(source);
+    if (rb_respond_to(source, id_to_path))
+        return ll_table_path_string(rb_funcall(source, id_to_path, 0));
+    if (rb_respond_to(source, id_read))
+        return ll_materialize_table_io(source);
+    return ll_table_path_string(source);
+}
+
+VALUE
+ll_table_source_normalize(VALUE input)
+{
+    VALUE string;
+
+    if (RB_TYPE_P(input, T_ARRAY)) {
+        long index;
+        VALUE normalized = rb_ary_new_capa(RARRAY_LEN(input));
+
+        for (index = 0; index < RARRAY_LEN(input); index++)
+            rb_ary_push(normalized, ll_normalize_table_source(rb_ary_entry(input, index)));
+        string = rb_ary_join(normalized, rb_str_new_cstr(","));
+    } else {
+        string = ll_normalize_table_source(input);
+    }
+
+    StringValueCStr(string);
+    return rb_obj_freeze(string);
+}
+
+static VALUE
+ll_delete_temporary_path(VALUE path)
+{
+    rb_funcall(rb_cFile, id_delete, 1, path);
+    return Qnil;
+}
+
+void
+ll_cleanup_table_sources(void)
+{
+    long index;
+
+    for (index = 0; index < RARRAY_LEN(ll_temporary_paths); index++) {
+        int state = 0;
+        rb_protect(ll_delete_temporary_path, rb_ary_entry(ll_temporary_paths, index), &state);
+        if (state)
+            rb_set_errinfo(Qnil);
+    }
+    rb_ary_clear(ll_temporary_paths);
+}
+
+void
+ll_init_table_source(void)
+{
+    id_read = rb_intern("read");
+    id_to_path = rb_intern("to_path");
+    id_join = rb_intern("join");
+    id_aref = rb_intern("[]");
+    id_delete = rb_intern("delete");
+    ll_temporary_paths = rb_ary_new();
+    rb_global_variable(&ll_temporary_paths);
+}