csan 0.0.0 → 0.8.0

data/ext/csan/src/lib.rs

@@ -0,0 +1,263 @@
+// The magnus macro expansions contain `unsafe`, so
+// `#![forbid(unsafe_code)]` (which cannot be overridden) is not usable
+// here. `deny` still rejects any hand-written `unsafe` in this crate
+// while allowing the macro-generated blocks through.
+#![deny(unsafe_code)]
+
+//! The `csan` gem's native extension, `Csan::Native`.
+//!
+//! Exposes [`csan_core`]'s Cutter call number generation to Ruby, plus the
+//! `run_cli` entry point behind the gem's `csan` executable (the same
+//! `clap` interface as the standalone binary, provided by [`csan`]).
+//! The user-facing API (keyword arguments, documentation) lives in
+//! `lib/csan.rb`, which calls these with positional arguments.
+
+use core::fmt;
+use core::iter;
+use csan_core::{
+    Attribution, CutterConfig, CutterGenerator as _, CutterLoc, CutterLocMethod, CutterSanborn,
+    CutterSanbornMethod, detailed_json,
+};
+use magnus::value::ReprValue as _;
+use magnus::{Error, IntoValue as _, RHash, Ruby, Value};
+use serde_json::Value as Json;
+
+/// Builds the [`Attribution`] for a set of optional inputs, or Ruby's
+/// `ArgumentError`.
+fn attribution(
+    ruby: &Ruby,
+    forename: Option<&str>,
+    surname: Option<&str>,
+    title: Option<&str>,
+) -> Result<Attribution, Error> {
+    Attribution::from_parts(forename, surname, title).ok_or_else(|| {
+        Error::new(
+            ruby.exception_arg_error(),
+            "provide at least one non-blank input: forename, surname, or title",
+        )
+    })
+}
+
+/// Maps a failure to Ruby's `ArgumentError`, prefixed with `context`.
+fn argument_error(ruby: &Ruby, context: &str, error: &impl fmt::Display) -> Error {
+    Error::new(ruby.exception_arg_error(), format!("{context}: {error}"))
+}
+
+/// Generates the Cutter-Sanborn value shared by both `cutter_sanborn`
+/// variants.
+fn sanborn(
+    ruby: &Ruby,
+    forename: Option<&str>,
+    surname: Option<&str>,
+    title: Option<&str>,
+    prefix_len: Option<usize>,
+    suffix_len: Option<usize>,
+) -> Result<CutterSanborn, Error> {
+    let entry = attribution(ruby, forename, surname, title)?;
+    let config = CutterConfig::from_overrides(prefix_len, suffix_len, None);
+    CutterSanbornMethod::generate(&entry, config)
+        .map_err(|error| argument_error(ruby, "cutter generation failed", &error))
+}
+
+/// Generates the `LoC` value shared by both `cutter_loc` variants.
+fn loc(
+    ruby: &Ruby,
+    forename: Option<&str>,
+    surname: Option<&str>,
+    title: Option<&str>,
+    max_len: Option<usize>,
+) -> Result<CutterLoc, Error> {
+    let entry = attribution(ruby, forename, surname, title)?;
+    let config = CutterConfig::from_overrides(None, None, max_len);
+    CutterLocMethod::generate(&entry, config)
+        .map_err(|error| argument_error(ruby, "cutter generation failed", &error))
+}
+
+/// Converts a JSON value produced by [`detailed_json`] into the equivalent
+/// Ruby object: objects become hashes with symbol keys.
+///
+/// The detailed objects only ever contain strings, integers, nested objects,
+/// and JSON null (for an absent work mark), so those are the cases that
+/// matter; other shapes are mapped on a best-effort basis to keep the
+/// function total.
+fn json_to_ruby(ruby: &Ruby, value: &Json) -> Result<Value, Error> {
+    Ok(match value {
+        Json::Null => ruby.qnil().as_value(),
+        Json::Bool(boolean) => boolean.into_value_with(ruby),
+        Json::String(string) => string.as_str().into_value_with(ruby),
+        Json::Number(number) => {
+            if let Some(unsigned) = number.as_u64() {
+                unsigned.into_value_with(ruby)
+            } else if let Some(signed) = number.as_i64() {
+                signed.into_value_with(ruby)
+            } else if let Some(float) = number.as_f64() {
+                float.into_value_with(ruby)
+            } else {
+                // No numeric representation fits; fall back to the text form.
+                number.to_string().into_value_with(ruby)
+            }
+        }
+        Json::Array(items) => {
+            let array = ruby.ary_new_capa(items.len());
+            for item in items {
+                array.push(json_to_ruby(ruby, item)?)?;
+            }
+            array.as_value()
+        }
+        Json::Object(_) => detailed_hash(ruby, value)?.as_value(),
+    })
+}
+
+/// Builds the detailed hash from a cutter's [`detailed_json`] object, so
+/// every frontend agrees on the shape.
+///
+/// The value is always a JSON object (the cutter models are structs); a
+/// non-object is treated as a programming error and surfaced as
+/// `ArgumentError`.
+fn detailed_hash(ruby: &Ruby, value: &Json) -> Result<RHash, Error> {
+    let Json::Object(fields) = value else {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "detailed cutter value did not serialize as an object",
+        ));
+    };
+    let hash = ruby.hash_new();
+    for (key, field) in fields {
+        hash.aset(ruby.to_symbol(key), json_to_ruby(ruby, field)?)?;
+    }
+    Ok(hash)
+}
+
+/// The Cutter-Sanborn call number as a string (e.g. `"D548o"`).
+#[expect(
+    clippy::needless_pass_by_value,
+    reason = "magnus passes Ruby's arguments as owned values"
+)]
+fn cutter_sanborn(
+    ruby: &Ruby,
+    forename: Option<String>,
+    surname: Option<String>,
+    title: Option<String>,
+    prefix_len: Option<usize>,
+    suffix_len: Option<usize>,
+) -> Result<String, Error> {
+    let cutter = sanborn(
+        ruby,
+        forename.as_deref(),
+        surname.as_deref(),
+        title.as_deref(),
+        prefix_len,
+        suffix_len,
+    )?;
+    Ok(cutter.to_string())
+}
+
+/// The Cutter-Sanborn number's parts: `alpha_prefix`, `numeric`,
+/// `alpha_suffix` (nil without a work mark), `entry`, and `formatted`.
+#[expect(
+    clippy::needless_pass_by_value,
+    reason = "magnus passes Ruby's arguments as owned values"
+)]
+fn cutter_sanborn_detailed(
+    ruby: &Ruby,
+    forename: Option<String>,
+    surname: Option<String>,
+    title: Option<String>,
+    prefix_len: Option<usize>,
+    suffix_len: Option<usize>,
+) -> Result<RHash, Error> {
+    let cutter = sanborn(
+        ruby,
+        forename.as_deref(),
+        surname.as_deref(),
+        title.as_deref(),
+        prefix_len,
+        suffix_len,
+    )?;
+    let value = detailed_json(&cutter)
+        .map_err(|error| argument_error(ruby, "detailed cutter value failed", &error))?;
+    detailed_hash(ruby, &value)
+}
+
+/// The Library of Congress cutter number as a string (e.g. `"C378"`).
+#[expect(
+    clippy::needless_pass_by_value,
+    reason = "magnus passes Ruby's arguments as owned values"
+)]
+fn cutter_loc(
+    ruby: &Ruby,
+    forename: Option<String>,
+    surname: Option<String>,
+    title: Option<String>,
+    max_len: Option<usize>,
+) -> Result<String, Error> {
+    let cutter = loc(
+        ruby,
+        forename.as_deref(),
+        surname.as_deref(),
+        title.as_deref(),
+        max_len,
+    )?;
+    Ok(cutter.to_string())
+}
+
+/// The Library of Congress number's parts: `alpha_prefix`, `numeric`, and
+/// `formatted`.
+#[expect(
+    clippy::needless_pass_by_value,
+    reason = "magnus passes Ruby's arguments as owned values"
+)]
+fn cutter_loc_detailed(
+    ruby: &Ruby,
+    forename: Option<String>,
+    surname: Option<String>,
+    title: Option<String>,
+    max_len: Option<usize>,
+) -> Result<RHash, Error> {
+    let cutter = loc(
+        ruby,
+        forename.as_deref(),
+        surname.as_deref(),
+        title.as_deref(),
+        max_len,
+    )?;
+    let value = detailed_json(&cutter)
+        .map_err(|error| argument_error(ruby, "detailed cutter value failed", &error))?;
+    detailed_hash(ruby, &value)
+}
+
+/// Runs the `csan` command-line interface on `args` (without the program
+/// name) and returns the process exit code: the engine behind the gem's
+/// `csan` executable.
+fn run_cli(args: Vec<String>) -> u8 {
+    csan::run_from_args(iter::once(String::from("csan")).chain(args))
+}
+
+/// The extension's entry point, `Init_csan_rb`, which Ruby calls when
+/// `lib/csan.rb` requires the extension. In a private module:
+/// `#[magnus::init]` exports it whatever its visibility, and it is no public
+/// API to document.
+mod entry {
+    use magnus::{Error, Ruby, function, prelude::*};
+
+    use super::{
+        cutter_loc, cutter_loc_detailed, cutter_sanborn, cutter_sanborn_detailed, run_cli,
+    };
+
+    /// Defines `Csan::Native` and its module functions, and
+    /// `Csan::Native::VERSION`, the crate's version.
+    #[magnus::init]
+    fn init(ruby: &Ruby) -> Result<(), Error> {
+        let native = ruby.define_module("Csan")?.define_module("Native")?;
+        native.define_module_function("cutter_sanborn", function!(cutter_sanborn, 5))?;
+        native.define_module_function(
+            "cutter_sanborn_detailed",
+            function!(cutter_sanborn_detailed, 5),
+        )?;
+        native.define_module_function("cutter_loc", function!(cutter_loc, 4))?;
+        native.define_module_function("cutter_loc_detailed", function!(cutter_loc_detailed, 4))?;
+        native.define_module_function("run_cli", function!(run_cli, 1))?;
+        native.const_set("VERSION", env!("CARGO_PKG_VERSION"))?;
+        Ok(())
+    }
+}

data/lib/csan/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module Csan
-  VERSION = "0.0.0"
+  # The gem's version: the csan workspace's, which `just release` sets here
+  # too (and the extension reports as Csan::Native::VERSION).
+  VERSION = "0.8.0"
 end

data/lib/csan.rb

@@ -1,8 +1,96 @@
 # frozen_string_literal: true
 
+require "rbconfig"
 require_relative "csan/version"
 
+# A precompiled (platform) gem carries one extension per Ruby minor version,
+# in lib/csan/<major.minor>/; the source gem, and a local `rake compile`,
+# build one in lib/csan/. (Chosen by file, so that an extension that fails to
+# load reports its own error.)
+versioned = File.join(__dir__, "csan", RUBY_VERSION[/\A\d+\.\d+/], "csan_rb.#{RbConfig::CONFIG["DLEXT"]}")
+if File.exist?(versioned)
+  require versioned
+else
+  require_relative "csan/csan_rb"
+end
+
+# Cutter-Sanborn three-figure and Library of Congress cutter numbers for
+# library cataloging, from author names and titles.
+#
+# Every function takes the author's `forename` and `surname` and the work's
+# `title` as keyword arguments, at least one of them non-blank (blank strings
+# count as absent), and raises `ArgumentError` on unusable input. A length
+# that is not an Integer raises `TypeError` (a Float is truncated), and a
+# negative one `RangeError`.
+#
+# @example
+#   Csan.cutter_sanborn(forename: "Charles", surname: "Dickens", title: "Oliver Twist")
+#   # => "D548o"
+#   Csan.cutter_loc(surname: "Carter") # => "C378"
 module Csan
-  class Error < StandardError; end
-  # Your code goes here...
+  # The Cutter-Sanborn three-figure number.
+  #
+  # @param forename [String, nil] the author's forename
+  # @param surname [String, nil] the author's surname
+  # @param title [String, nil] the work's title: the work mark, or the whole
+  #   number when there is no author
+  # @param prefix_len [Integer, nil] letters of the name kept before the
+  #   number (default 1)
+  # @param suffix_len [Integer, nil] letters of the title in the work mark
+  #   (default 1)
+  # @return [String] the number, e.g. "D548o"
+  # @raise [ArgumentError] on unusable input
+  def self.cutter_sanborn(forename: nil, surname: nil, title: nil, prefix_len: nil, suffix_len: nil)
+    Native.cutter_sanborn(forename, surname, title, prefix_len, suffix_len)
+  end
+
+  # The Cutter-Sanborn number's parts.
+  #
+  # Takes the arguments of {cutter_sanborn}.
+  #
+  # @return [Hash{Symbol => String, Integer, nil}] `:alpha_prefix`,
+  #   `:numeric`, `:alpha_suffix` (nil without a work mark), `:entry` (the
+  #   table entry that matched), and `:formatted`
+  # @raise [ArgumentError] on unusable input
+  def self.cutter_sanborn_detailed(forename: nil, surname: nil, title: nil, prefix_len: nil, suffix_len: nil)
+    Native.cutter_sanborn_detailed(forename, surname, title, prefix_len, suffix_len)
+  end
+
+  # The Library of Congress cutter number.
+  #
+  # @param forename [String, nil] the author's forename
+  # @param surname [String, nil] the author's surname
+  # @param title [String, nil] the work's title, cuttered when there is no
+  #   author
+  # @param max_len [Integer, nil] digits in the number (default 3, at most 4)
+  # @return [String] the number, e.g. "C378"
+  # @raise [ArgumentError] on unusable input
+  def self.cutter_loc(forename: nil, surname: nil, title: nil, max_len: nil)
+    Native.cutter_loc(forename, surname, title, max_len)
+  end
+
+  # The Library of Congress number's parts.
+  #
+  # Takes the arguments of {cutter_loc}.
+  #
+  # @return [Hash{Symbol => String, Integer}] `:alpha_prefix`, `:numeric`,
+  #   and `:formatted`
+  # @raise [ArgumentError] on unusable input
+  def self.cutter_loc_detailed(forename: nil, surname: nil, title: nil, max_len: nil)
+    Native.cutter_loc_detailed(forename, surname, title, max_len)
+  end
+
+  # Runs the `csan` command-line interface, the engine of the gem's `csan`
+  # executable: its options, help, messages, and exit codes are the
+  # standalone binary's. It writes to the process's standard output and
+  # error directly, after flushing `$stdout` and `$stderr`.
+  #
+  # @param args [Array<String>] the arguments, without the program name
+  # @return [Integer] the exit code: 0, 1 for an unusable input, 2 for a
+  #   usage error
+  def self.run_cli(args)
+    $stdout.flush
+    $stderr.flush
+    Native.run_cli(args)
+  end
 end

data/sig/csan.rbs

@@ -1,4 +1,57 @@
+# Type signatures for the csan gem.
 module Csan
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  type sanborn_parts = {
+    alpha_prefix: String,
+    numeric: Integer,
+    alpha_suffix: String?,
+    entry: String,
+    formatted: String
+  }
+
+  type loc_parts = { alpha_prefix: String, numeric: Integer, formatted: String }
+
+  def self.cutter_sanborn: (
+    ?forename: String?,
+    ?surname: String?,
+    ?title: String?,
+    ?prefix_len: Integer?,
+    ?suffix_len: Integer?
+  ) -> String
+
+  def self.cutter_sanborn_detailed: (
+    ?forename: String?,
+    ?surname: String?,
+    ?title: String?,
+    ?prefix_len: Integer?,
+    ?suffix_len: Integer?
+  ) -> sanborn_parts
+
+  def self.cutter_loc: (
+    ?forename: String?,
+    ?surname: String?,
+    ?title: String?,
+    ?max_len: Integer?
+  ) -> String
+
+  def self.cutter_loc_detailed: (
+    ?forename: String?,
+    ?surname: String?,
+    ?title: String?,
+    ?max_len: Integer?
+  ) -> loc_parts
+
+  def self.run_cli: (Array[String] args) -> Integer
+
+  # The extension: positional arguments, in the order of the keywords above.
+  module Native
+    VERSION: String
+
+    def self.cutter_sanborn: (String?, String?, String?, Integer?, Integer?) -> String
+    def self.cutter_sanborn_detailed: (String?, String?, String?, Integer?, Integer?) -> sanborn_parts
+    def self.cutter_loc: (String?, String?, String?, Integer?) -> String
+    def self.cutter_loc_detailed: (String?, String?, String?, Integer?) -> loc_parts
+    def self.run_cli: (Array[String]) -> Integer
+  end
 end

metadata

@@ -1,31 +1,61 @@
 --- !ruby/object:Gem::Specification
 name: csan
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.8.0
 platform: ruby
 authors:
 - VERALVX
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+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: |
+  Generate Cutter-Sanborn three-figure and Library of Congress cutter
+  numbers from author names and titles, with the csan command-line tool.
+  The numbers come from the csan Rust library (a native extension), so they
+  match the csan CLI and its Python, JavaScript, and Typst packages.
 email:
 - veralvx@veralvx.com
-executables: []
-extensions: []
+executables:
+- csan
+extensions:
+- ext/csan/extconf.rb
 extra_rdoc_files: []
 files:
-- LICENSE.txt
+- LICENSE-APACHE
+- LICENSE-MIT
 - README.md
-- Rakefile
+- exe/csan
+- ext/csan/Cargo.lock
+- ext/csan/Cargo.toml
+- ext/csan/extconf.rb
+- ext/csan/src/lib.rs
 - lib/csan.rb
 - lib/csan/version.rb
 - sig/csan.rbs
 homepage: https://github.com/veralvx/csan
 licenses:
 - MIT
+- Apache-2.0
 metadata:
   homepage_uri: https://github.com/veralvx/csan
+  source_code_uri: https://github.com/veralvx/csan/tree/main/crates/csan-rb
+  changelog_uri: https://github.com/veralvx/csan/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/veralvx/csan/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -33,14 +63,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Write a short summary, because RubyGems requires one.
+summary: Cutter-Sanborn and Library of Congress cutter numbers for library cataloging
 test_files: []

data/LICENSE.txt

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2026 VERALVX
-
-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/Rakefile

@@ -1,4 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-task default: %i[]