csan 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bff45dc4e1ef8a3625bc4d045b099fcd6b34b800fda8845b5c353bd6a3a0012f
-  data.tar.gz: 0add5aeddb5955fd080a744c4dd06f5e2fc21d3eb0e45fcd7998352867afc1ea
+  metadata.gz: 4d3f833779c060221fc8d413bf0897ccebc862e2cb381329aabdba91abcfc4f3
+  data.tar.gz: 6d9ec7c4dc9d4e7b87ddebf1bd4fae83a081b3f148ab3c95e8fe4c51845b8f43
 SHA512:
-  metadata.gz: b58f02e859fb6a0dfa38f06560773440463f7093cc759d9229fcb964e0cf6fbf3ee6b6f798853c273849a58de28fb59b57e2b752ffe7a99c41bb0e0f691c93cf
-  data.tar.gz: a868b1fa3f498113763c757f03a997d06256d795a9b63f76d08d6ad6470e4bcc71702285c5fcf0d5a476c957715f02f831649741c1e272ece6f030863d692608
+  metadata.gz: 9454f8bc0d9ea568c8aae12af1a0e6e4fd342acc15381b9ced4de0f8835738c0e481cfe0e8be0c0007ce363b05d1da9689f34cf92a32053386f0f94d78d5dd88
+  data.tar.gz: 840755e651cbbb86a5b64ecb4ad8aec5f87e1acaa6128d1f729374e08b72d48b18bfc6be30ea3106bfb9b995c6cf7abcb98a4d0e8a86646753614b8741fc536d

data/README.md

@@ -37,6 +37,22 @@ raises `ArgumentError`; a length that is not an Integer raises `TypeError`,
 and a negative one `RangeError`. [`sig/csan.rbs`](https://github.com/veralvx/csan/blob/main/crates/csan-rb/sig/csan.rbs)
 holds the type signatures.
 
+Every function also takes `lang` and `strip_article`: with a truthy
+`strip_article`, the title is filed without its initial article in the
+language `lang` names (an ISO 639 code, a BCP 47 tag or a POSIX locale,
+case-insensitive; `csan --help` lists them all). `lang` alone changes
+nothing, a blank `lang` counts as absent, and author names are never
+stripped. An unknown `lang` (even with `strip_article` off), or
+`strip_article` without `lang`, raises `ArgumentError`, and a `lang` that
+is not a String `TypeError`.
+
+```ruby
+Csan.cutter_sanborn(surname: "Dickens", title: "A Christmas Carol", lang: "en", strip_article: true)
+# => "D548c"
+Csan.cutter_loc(title: "The Bear", lang: "en", strip_article: true)
+# => "B437"
+```
+
 The executable is the same interface as the standalone Rust binary
 (options, help, messages, and exit codes):
 

data/ext/csan/Cargo.lock

@@ -168,9 +168,9 @@ dependencies = [
 
 [[package]]
 name = "csan"
-version = "0.8.0"
+version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cb15b7a24bcce5da647fb7edeb5af6ccc1cc3a6fe50f2ccf93d6fed32ec060a3"
+checksum = "faf7f4236511169f63c8b2db962c8d0dd472fcfac9ea347ae96e43d18689e8ec"
 dependencies = [
  "clap",
  "csan-core",
@@ -179,9 +179,9 @@ dependencies = [
 
 [[package]]
 name = "csan-core"
-version = "0.8.0"
+version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c05481502522d9e78dc91a5af3dedafc0c94f106e2f550c938144c8c6ffc36f2"
+checksum = "56070a56f6dfc10c0367cfcd36886b6f4787b0ae0420d5e80c455146447f1570"
 dependencies = [
  "derive_more",
  "serde",
@@ -190,7 +190,7 @@ dependencies = [
 
 [[package]]
 name = "csan-rb"
-version = "0.8.0"
+version = "0.9.0"
 dependencies = [
  "csan",
  "csan-core",

data/ext/csan/Cargo.toml

@@ -13,7 +13,7 @@
 edition = "2024"
 rust-version = "1.97"
 name = "csan-rb"
-version = "0.8.0"
+version = "0.9.0"
 authors = ["VERALVX <veralvx@veralvx.com>"]
 build = false
 publish = false
@@ -38,10 +38,10 @@ test = false
 doctest = false
 
 [dependencies.csan]
-version = "=0.8.0"
+version = "=0.9.0"
 
 [dependencies.csan-core]
-version = "0.8.0"
+version = "0.9.0"
 
 [dependencies.magnus]
 version = "0.9.3"

data/ext/csan/src/lib.rs

@@ -16,26 +16,47 @@ use core::fmt;
 use core::iter;
 use csan_core::{
     Attribution, CutterConfig, CutterGenerator as _, CutterLoc, CutterLocMethod, CutterSanborn,
-    CutterSanbornMethod, detailed_json,
+    CutterSanbornMethod, Language, MissingLanguage, 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`.
+/// The language the title is filed in, from the `lang` and
+/// `strip_article` arguments: `None` when the switch is off.
+///
+/// `lang` is parsed even with the switch off, so a bad code is always an
+/// `ArgumentError`; a blank `lang` counts as absent. The exported functions
+/// call it before checking their inputs, so a language error comes first,
+/// as in the CLI.
+fn article_language(
+    ruby: &Ruby,
+    lang: Option<&str>,
+    strip_article: bool,
+) -> Result<Option<Language>, Error> {
+    let language = Language::from_optional(lang)
+        .map_err(|error| Error::new(ruby.exception_arg_error(), error.to_string()))?;
+    Language::for_rule(language, strip_article).map_err(|MissingLanguage| {
+        Error::new(ruby.exception_arg_error(), "strip_article requires lang")
+    })
+}
+
+/// Builds the [`Attribution`] for a set of optional inputs, with its title
+/// filed in `article_language`, or Ruby's `ArgumentError`.
 fn attribution(
     ruby: &Ruby,
     forename: Option<&str>,
     surname: Option<&str>,
     title: Option<&str>,
+    article_language: Option<Language>,
 ) -> Result<Attribution, Error> {
-    Attribution::from_parts(forename, surname, title).ok_or_else(|| {
+    let entry = 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",
         )
-    })
+    })?;
+    Ok(entry.with_article_language(article_language))
 }
 
 /// Maps a failure to Ruby's `ArgumentError`, prefixed with `context`.
@@ -52,8 +73,9 @@ fn sanborn(
     title: Option<&str>,
     prefix_len: Option<usize>,
     suffix_len: Option<usize>,
+    article_language: Option<Language>,
 ) -> Result<CutterSanborn, Error> {
-    let entry = attribution(ruby, forename, surname, title)?;
+    let entry = attribution(ruby, forename, surname, title, article_language)?;
     let config = CutterConfig::from_overrides(prefix_len, suffix_len, None);
     CutterSanbornMethod::generate(&entry, config)
         .map_err(|error| argument_error(ruby, "cutter generation failed", &error))
@@ -66,8 +88,9 @@ fn loc(
     surname: Option<&str>,
     title: Option<&str>,
     max_len: Option<usize>,
+    article_language: Option<Language>,
 ) -> Result<CutterLoc, Error> {
-    let entry = attribution(ruby, forename, surname, title)?;
+    let entry = attribution(ruby, forename, surname, title, article_language)?;
     let config = CutterConfig::from_overrides(None, None, max_len);
     CutterLocMethod::generate(&entry, config)
         .map_err(|error| argument_error(ruby, "cutter generation failed", &error))
@@ -133,6 +156,10 @@ fn detailed_hash(ruby: &Ruby, value: &Json) -> Result<RHash, Error> {
     clippy::needless_pass_by_value,
     reason = "magnus passes Ruby's arguments as owned values"
 )]
+#[expect(
+    clippy::too_many_arguments,
+    reason = "one parameter per Ruby argument, plus the interpreter handle"
+)]
 fn cutter_sanborn(
     ruby: &Ruby,
     forename: Option<String>,
@@ -140,7 +167,10 @@ fn cutter_sanborn(
     title: Option<String>,
     prefix_len: Option<usize>,
     suffix_len: Option<usize>,
+    lang: Option<String>,
+    strip_article: bool,
 ) -> Result<String, Error> {
+    let language = article_language(ruby, lang.as_deref(), strip_article)?;
     let cutter = sanborn(
         ruby,
         forename.as_deref(),
@@ -148,6 +178,7 @@ fn cutter_sanborn(
         title.as_deref(),
         prefix_len,
         suffix_len,
+        language,
     )?;
     Ok(cutter.to_string())
 }
@@ -158,6 +189,10 @@ fn cutter_sanborn(
     clippy::needless_pass_by_value,
     reason = "magnus passes Ruby's arguments as owned values"
 )]
+#[expect(
+    clippy::too_many_arguments,
+    reason = "one parameter per Ruby argument, plus the interpreter handle"
+)]
 fn cutter_sanborn_detailed(
     ruby: &Ruby,
     forename: Option<String>,
@@ -165,7 +200,10 @@ fn cutter_sanborn_detailed(
     title: Option<String>,
     prefix_len: Option<usize>,
     suffix_len: Option<usize>,
+    lang: Option<String>,
+    strip_article: bool,
 ) -> Result<RHash, Error> {
+    let language = article_language(ruby, lang.as_deref(), strip_article)?;
     let cutter = sanborn(
         ruby,
         forename.as_deref(),
@@ -173,6 +211,7 @@ fn cutter_sanborn_detailed(
         title.as_deref(),
         prefix_len,
         suffix_len,
+        language,
     )?;
     let value = detailed_json(&cutter)
         .map_err(|error| argument_error(ruby, "detailed cutter value failed", &error))?;
@@ -190,13 +229,17 @@ fn cutter_loc(
     surname: Option<String>,
     title: Option<String>,
     max_len: Option<usize>,
+    lang: Option<String>,
+    strip_article: bool,
 ) -> Result<String, Error> {
+    let language = article_language(ruby, lang.as_deref(), strip_article)?;
     let cutter = loc(
         ruby,
         forename.as_deref(),
         surname.as_deref(),
         title.as_deref(),
         max_len,
+        language,
     )?;
     Ok(cutter.to_string())
 }
@@ -213,13 +256,17 @@ fn cutter_loc_detailed(
     surname: Option<String>,
     title: Option<String>,
     max_len: Option<usize>,
+    lang: Option<String>,
+    strip_article: bool,
 ) -> Result<RHash, Error> {
+    let language = article_language(ruby, lang.as_deref(), strip_article)?;
     let cutter = loc(
         ruby,
         forename.as_deref(),
         surname.as_deref(),
         title.as_deref(),
         max_len,
+        language,
     )?;
     let value = detailed_json(&cutter)
         .map_err(|error| argument_error(ruby, "detailed cutter value failed", &error))?;
@@ -249,13 +296,13 @@ mod entry {
     #[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", function!(cutter_sanborn, 7))?;
         native.define_module_function(
             "cutter_sanborn_detailed",
-            function!(cutter_sanborn_detailed, 5),
+            function!(cutter_sanborn_detailed, 7),
         )?;
-        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("cutter_loc", function!(cutter_loc, 6))?;
+        native.define_module_function("cutter_loc_detailed", function!(cutter_loc_detailed, 6))?;
         native.define_module_function("run_cli", function!(run_cli, 1))?;
         native.const_set("VERSION", env!("CARGO_PKG_VERSION"))?;
         Ok(())

data/lib/csan/version.rb

@@ -3,5 +3,5 @@
 module Csan
   # 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"
+  VERSION = "0.9.0"
 end

data/lib/csan.rb

@@ -23,10 +23,21 @@ end
 # that is not an Integer raises `TypeError` (a Float is truncated), and a
 # negative one `RangeError`.
 #
+# Every function also takes `lang` and `strip_article`: with a truthy
+# `strip_article`, the title is filed without its initial article in the
+# language `lang` names, an ISO 639 code, a BCP 47 tag or a POSIX locale
+# (`"en"`, `"pt-BR"`), case-insensitive; `csan --help` lists them all.
+# `lang` alone changes nothing, a blank `lang` counts as absent, and author
+# names are never stripped. An unknown `lang` (even with `strip_article`
+# off), or `strip_article` without `lang`, raises `ArgumentError`, and a
+# `lang` that is not a String `TypeError`.
+#
 # @example
 #   Csan.cutter_sanborn(forename: "Charles", surname: "Dickens", title: "Oliver Twist")
 #   # => "D548o"
 #   Csan.cutter_loc(surname: "Carter") # => "C378"
+#   Csan.cutter_sanborn(surname: "Dickens", title: "A Christmas Carol", lang: "en", strip_article: true)
+#   # => "D548c"
 module Csan
   # The Cutter-Sanborn three-figure number.
   #
@@ -38,10 +49,15 @@ module Csan
   #   number (default 1)
   # @param suffix_len [Integer, nil] letters of the title in the work mark
   #   (default 1)
+  # @param lang [String, nil] the work's language, for `strip_article`
+  # @param strip_article [Boolean, nil] file the title without its initial
+  #   article in `lang` when truthy (default false)
   # @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)
+  # @raise [ArgumentError] on unusable input, an unknown `lang`, or
+  #   `strip_article` without `lang`
+  def self.cutter_sanborn(forename: nil, surname: nil, title: nil, prefix_len: nil, suffix_len: nil,
+    lang: nil, strip_article: false)
+    Native.cutter_sanborn(forename, surname, title, prefix_len, suffix_len, lang, strip_article)
   end
 
   # The Cutter-Sanborn number's parts.
@@ -51,9 +67,10 @@ module Csan
   # @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)
+  # @raise [ArgumentError] as {cutter_sanborn} does
+  def self.cutter_sanborn_detailed(forename: nil, surname: nil, title: nil, prefix_len: nil, suffix_len: nil,
+    lang: nil, strip_article: false)
+    Native.cutter_sanborn_detailed(forename, surname, title, prefix_len, suffix_len, lang, strip_article)
   end
 
   # The Library of Congress cutter number.
@@ -63,10 +80,15 @@ module Csan
   # @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)
+  # @param lang [String, nil] the work's language, for `strip_article`
+  # @param strip_article [Boolean, nil] file the title without its initial
+  #   article in `lang` when truthy (default false)
   # @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)
+  # @raise [ArgumentError] on unusable input, an unknown `lang`, or
+  #   `strip_article` without `lang`
+  def self.cutter_loc(forename: nil, surname: nil, title: nil, max_len: nil,
+    lang: nil, strip_article: false)
+    Native.cutter_loc(forename, surname, title, max_len, lang, strip_article)
   end
 
   # The Library of Congress number's parts.
@@ -75,9 +97,10 @@ module Csan
   #
   # @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)
+  # @raise [ArgumentError] as {cutter_loc} does
+  def self.cutter_loc_detailed(forename: nil, surname: nil, title: nil, max_len: nil,
+    lang: nil, strip_article: false)
+    Native.cutter_loc_detailed(forename, surname, title, max_len, lang, strip_article)
   end
 
   # Runs the `csan` command-line interface, the engine of the gem's `csan`

data/sig/csan.rbs

@@ -17,7 +17,9 @@ module Csan
     ?surname: String?,
     ?title: String?,
     ?prefix_len: Integer?,
-    ?suffix_len: Integer?
+    ?suffix_len: Integer?,
+    ?lang: String?,
+    ?strip_article: boolish
   ) -> String
 
   def self.cutter_sanborn_detailed: (
@@ -25,33 +27,40 @@ module Csan
     ?surname: String?,
     ?title: String?,
     ?prefix_len: Integer?,
-    ?suffix_len: Integer?
+    ?suffix_len: Integer?,
+    ?lang: String?,
+    ?strip_article: boolish
   ) -> sanborn_parts
 
   def self.cutter_loc: (
     ?forename: String?,
     ?surname: String?,
     ?title: String?,
-    ?max_len: Integer?
+    ?max_len: Integer?,
+    ?lang: String?,
+    ?strip_article: boolish
   ) -> String
 
   def self.cutter_loc_detailed: (
     ?forename: String?,
     ?surname: String?,
     ?title: String?,
-    ?max_len: Integer?
+    ?max_len: Integer?,
+    ?lang: String?,
+    ?strip_article: boolish
   ) -> loc_parts
 
   def self.run_cli: (Array[String] args) -> Integer
 
-  # The extension: positional arguments, in the order of the keywords above.
+  # The extension, internal to the gem (lib/csan.rb is its only caller):
+  # 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.cutter_sanborn: (String?, String?, String?, Integer?, Integer?, String?, boolish) -> String
+    def self.cutter_sanborn_detailed: (String?, String?, String?, Integer?, Integer?, String?, boolish) -> sanborn_parts
+    def self.cutter_loc: (String?, String?, String?, Integer?, String?, boolish) -> String
+    def self.cutter_loc_detailed: (String?, String?, String?, Integer?, String?, boolish) -> loc_parts
     def self.run_cli: (Array[String]) -> Integer
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: csan
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - VERALVX