Rename LinkBuilder to LiNoBuilder for consistent naming

konard · claude · konard · commit 26bfad9af06e · 2026-01-18T03:00:59.000+01:00
- Rename LinkBuilder struct to LiNoBuilder for naming consistency
- Add deprecated type alias for backward compatibility
- Update documentation to use LiNoBuilder
- Add comprehensive API documentation for alternative approaches:
  - LiNoBuilder (fluent API for arbitrary-length links)
  - Vec-based conversions
  - LiNo::new() static method

All 275 tests pass.

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/rust/links-notation/README.md b/rust/links-notation/README.md
@@ -324,6 +324,117 @@ let link: LiNo<String> = (refs[0].clone(), refs[1].clone(), refs[2].clone(),
 
 This macro-generated implementation reduces code duplication while providing compile-time type safety for all tuple sizes.
 
+## Alternative APIs for Arbitrary-Length Links
+
+Since Rust doesn't support variadic generics, tuples are limited to 12 elements (following Rust's standard library convention). For links with more than 12 values or when the number of values is determined at runtime, use one of these alternative APIs:
+
+### Vec-based Conversions
+
+Convert vectors directly to links:
+
+```rust
+use links_notation::LiNo;
+
+// Anonymous link from Vec<&str>
+let values: Vec<&str> = vec!["a", "b", "c", "d", "e"];
+let link: LiNo<String> = values.into();
+println!("{}", link); // (a b c d e)
+
+// Named link from (id, Vec) tuple
+let values: Vec<&str> = vec!["v1", "v2", "v3", "v4", "v5"];
+let link: LiNo<String> = ("myLink", values).into();
+println!("{}", link); // (myLink: v1 v2 v3 v4 v5)
+
+// Large links with more than 12 values
+let values: Vec<&str> = (1..=100).map(|_| "val").collect();
+let link: LiNo<String> = ("big", values).into();
+```
+
+### LiNoBuilder (Fluent API)
+
+Build links using a fluent API for maximum flexibility:
+
+```rust
+use links_notation::{LiNo, LiNoBuilder};
+
+// Build a link with chained method calls
+let link: LiNo<String> = LiNoBuilder::new()
+    .id("myLink")
+    .value("v1")
+    .value("v2")
+    .value("v3")
+    .build();
+println!("{}", link); // (myLink: v1 v2 v3)
+
+// Build anonymous link (no ID)
+let link: LiNo<String> = LiNoBuilder::new()
+    .value("a")
+    .value("b")
+    .value("c")
+    .build();
+println!("{}", link); // (a b c)
+
+// Mix values and nested LiNo elements
+let nested: LiNo<String> = ("inner", "a", "b").into();
+let link: LiNo<String> = LiNoBuilder::new()
+    .id("outer")
+    .lino(nested)
+    .value("c")
+    .build();
+println!("{}", link); // (outer: (inner: a b) c)
+
+// Add multiple values at once
+let link: LiNo<String> = LiNoBuilder::new()
+    .id("batch")
+    .values(vec!["a", "b", "c", "d"])
+    .build();
+println!("{}", link); // (batch: a b c d)
+```
+
+### LiNo Static Methods
+
+Create links directly using static methods:
+
+```rust
+use links_notation::LiNo;
+
+// Create a named link with LiNo::new()
+let values: Vec<LiNo<String>> = vec![
+    LiNo::Ref("a".to_string()),
+    LiNo::Ref("b".to_string()),
+];
+let link = LiNo::new(Some("myId".to_string()), values);
+println!("{}", link); // (myId: a b)
+
+// Create an anonymous link with LiNo::anonymous()
+let values: Vec<LiNo<String>> = vec![
+    LiNo::Ref("x".to_string()),
+    LiNo::Ref("y".to_string()),
+    LiNo::Ref("z".to_string()),
+];
+let link = LiNo::anonymous(values);
+println!("{}", link); // (x y z)
+
+// Create a reference with LiNo::reference()
+let r: LiNo<String> = LiNo::reference("hello".to_string());
+println!("{}", r); // hello
+
+// Create links with arbitrary number of values
+let values: Vec<LiNo<String>> = (1..=100)
+    .map(|i| LiNo::Ref(format!("item{}", i)))
+    .collect();
+let link = LiNo::new(Some("hundred".to_string()), values);
+```
+
+### API Summary
+
+| API | Max Length | Use Case |
+|-----|-----------|----------|
+| Tuple conversion | 12 | Most common cases, ergonomic syntax |
+| Vec conversion | Unlimited | Runtime-determined or large fixed sets |
+| LiNoBuilder | Unlimited | Fluent construction, mixing types |
+| LiNo::new() | Unlimited | Direct construction with Vec |
+
 ## Syntax Examples
 
 ### Doublets (2-tuple)
diff --git a/rust/links-notation/src/lib.rs b/rust/links-notation/src/lib.rs
@@ -102,10 +102,10 @@ impl<T> LiNo<T> {
 ///
 /// # Examples
 /// ```
-/// use links_notation::{LiNo, LinkBuilder};
+/// use links_notation::{LiNo, LiNoBuilder};
 ///
 /// // Build a link with many string values
-/// let link: LiNo<String> = LinkBuilder::new()
+/// let link: LiNo<String> = LiNoBuilder::new()
 ///     .id("myLink")
 ///     .value("v1")
 ///     .value("v2")
@@ -115,28 +115,28 @@ impl<T> LiNo<T> {
 ///
 /// // Build a link with LiNo values
 /// let nested: LiNo<String> = ("inner", "a", "b").into();
-/// let link: LiNo<String> = LinkBuilder::new()
+/// let link: LiNo<String> = LiNoBuilder::new()
 ///     .id("outer")
 ///     .lino(nested)
 ///     .value("c")
 ///     .build();
 /// assert_eq!(format!("{}", link), "(outer: (inner: a b) c)");
 ///
 /// // Build anonymous link
-/// let link: LiNo<String> = LinkBuilder::new()
+/// let link: LiNo<String> = LiNoBuilder::new()
 ///     .value("a")
 ///     .value("b")
 ///     .build();
 /// assert_eq!(format!("{}", link), "(a b)");
 /// ```
 #[derive(Debug, Clone, Default)]
-pub struct LinkBuilder {
+pub struct LiNoBuilder {
     id: Option<String>,
     values: Vec<LiNo<String>>,
 }
 
-impl LinkBuilder {
-    /// Creates a new empty LinkBuilder.
+impl LiNoBuilder {
+    /// Creates a new empty LiNoBuilder.
     pub fn new() -> Self {
         Self::default()
     }
@@ -191,6 +191,10 @@ impl LinkBuilder {
     }
 }
 
+/// Type alias for backward compatibility (deprecated).
+#[deprecated(since = "0.3.0", note = "Use LiNoBuilder instead")]
+pub type LinkBuilder = LiNoBuilder;
+
 impl<T: ToString + Clone> LiNo<T> {
     /// Format the link using FormatConfig configuration.
     ///
@@ -1517,7 +1521,7 @@ impl_tuple_from!(12);
 // - https://github.com/rust-lang/rust/issues/10124 (RFC: variadic generics)
 //
 // Alternative approaches for arbitrary-length links:
-// 1. Use the `LinkBuilder` API for fluent construction
+// 1. Use the `LiNoBuilder` API for fluent construction
 // 2. Use `LiNo::new()` or `LiNo::anonymous()` with a `Vec`
 // 3. Use the `From<Vec<_>>` implementations below
 
diff --git a/rust/links-notation/tests/tuple_tests.rs b/rust/links-notation/tests/tuple_tests.rs
@@ -1,4 +1,4 @@
-use links_notation::{format_links, LiNo, LinkBuilder};
+use links_notation::{format_links, LiNo, LiNoBuilder};
 
 #[test]
 fn test_tuple_to_link_basic() {
@@ -400,13 +400,13 @@ fn test_vec_large_arbitrary_size() {
 }
 
 // ============================================================================
-// Tests for LinkBuilder API (fluent arbitrary-length construction)
+// Tests for LiNoBuilder API (fluent arbitrary-length construction)
 // ============================================================================
 
 #[test]
-fn test_link_builder_basic() {
+fn test_lino_builder_basic() {
     // Test basic builder usage
-    let link: LiNo<String> = LinkBuilder::new()
+    let link: LiNo<String> = LiNoBuilder::new()
         .id("myId")
         .value("v1")
         .value("v2")
@@ -415,17 +415,17 @@ fn test_link_builder_basic() {
 }
 
 #[test]
-fn test_link_builder_anonymous() {
+fn test_lino_builder_anonymous() {
     // Test building anonymous link (no ID)
-    let link: LiNo<String> = LinkBuilder::new().value("a").value("b").value("c").build();
+    let link: LiNo<String> = LiNoBuilder::new().value("a").value("b").value("c").build();
     assert_eq!(format!("{}", link), "(a b c)");
 }
 
 #[test]
-fn test_link_builder_with_lino() {
+fn test_lino_builder_with_lino() {
     // Test builder with LiNo values
     let nested: LiNo<String> = ("inner", "x", "y").into();
-    let link: LiNo<String> = LinkBuilder::new()
+    let link: LiNo<String> = LiNoBuilder::new()
         .id("outer")
         .lino(nested)
         .value("z")
@@ -434,30 +434,30 @@ fn test_link_builder_with_lino() {
 }
 
 #[test]
-fn test_link_builder_values_batch() {
+fn test_lino_builder_values_batch() {
     // Test builder with multiple values at once
-    let link: LiNo<String> = LinkBuilder::new()
+    let link: LiNo<String> = LiNoBuilder::new()
         .id("batch")
         .values(vec!["a", "b", "c", "d"])
         .build();
     assert_eq!(format!("{}", link), "(batch: a b c d)");
 }
 
 #[test]
-fn test_link_builder_linos_batch() {
+fn test_lino_builder_linos_batch() {
     // Test builder with multiple LiNo values at once
     let linos: Vec<LiNo<String>> = vec![("child1", "val1").into(), ("child2", "val2").into()];
-    let link: LiNo<String> = LinkBuilder::new().id("parent").linos(linos).build();
+    let link: LiNo<String> = LiNoBuilder::new().id("parent").linos(linos).build();
     assert_eq!(
         format!("{}", link),
         "(parent: (child1: val1) (child2: val2))"
     );
 }
 
 #[test]
-fn test_link_builder_large_link() {
+fn test_lino_builder_large_link() {
     // Test building a link with many values (more than 12)
-    let mut builder = LinkBuilder::new().id("large");
+    let mut builder = LiNoBuilder::new().id("large");
     for i in 1..=50 {
         builder = builder.value(&format!("v{}", i));
     }
@@ -469,11 +469,11 @@ fn test_link_builder_large_link() {
 }
 
 #[test]
-fn test_link_builder_chaining() {
+fn test_lino_builder_chaining() {
     // Test complex chaining
     let nested1: LiNo<String> = ("n1", "a").into();
     let nested2: LiNo<String> = ("n2", "b").into();
-    let link: LiNo<String> = LinkBuilder::new()
+    let link: LiNo<String> = LiNoBuilder::new()
         .id("root")
         .value("first")
         .lino(nested1)
