named-item

named-item provides a set of traits for handling named items in Rust. It includes functionality for name management, validation, aliases, history tracking, and more. The crate is designed to help developers manage named entities flexibly and consistently in applications requiring robust name-handling capabilities.

Features

• Name Management: Manage names with traits like Named, SetName, ResetName, and more.
• Alias Support: Track alternate names or aliases for an item.
• Name History: Maintain a history of name changes for audit or tracking purposes.
• Name Validation: Validate names using regular expressions or custom rules.
• Serialization Support: Optional support for serde to serialize and deserialize names.
• Custom Names: Use the Other(String) variant for names not included in the predefined list.

Installation

To use the named-item crate, add it to your Cargo.toml:

[dependencies]
named-item = "0.1"

If you want to enable serde support for serialization and deserialization, include the feature:

[dependencies]
named-item = { version = "0.1", features = ["serde"] }

Usage

Basic Usage

You can define and manage names using the provided traits. Here is an example of how to create an item with a name, set a new name, and reset it to the default:

use named_item::{Named, SetName, ResetName, DefaultName};

struct Item {
    name: String,
}

impl Named for Item {
    fn name(&self) -> Cow<'_, str> {
        Cow::Borrowed(&self.name)
    }
}

impl SetName for Item {
    fn set_name(&mut self, name: &str) -> Result<(), ()> {
        self.name = name.to_string();
        Ok(())
    }
}

impl DefaultName for Item {
    fn default_name() -> Cow<'static, str> {
        Cow::Borrowed("Unnamed Item")
    }
}

impl ResetName for Item {}

fn main() {
    let mut item = Item { name: "Initial".to_string() };
    println!("Item name: {}", item.name());

    // Set a new name
    item.set_name("New Name").unwrap();
    println!("Updated name: {}", item.name());

    // Reset to default name
    item.reset_name().unwrap();
    println!("Reset name: {}", item.name());
}

Aliases and Name History

The crate also provides functionality for tracking aliases and maintaining name histories:

use named_item::{Named, SetNameWithHistory, NameHistory};

struct TrackableItem {
    name: String,
    name_history: Vec<String>,
}

impl Named for TrackableItem {
    fn name(&self) -> Cow<'_, str> {
        Cow::Borrowed(&self.name)
    }
}

impl SetNameWithHistory for TrackableItem {
    fn set_name_with_history(&mut self, name: &str) -> Result<(), ()> {
        self.add_name_to_history(name);
        self.name = name.to_string();
        Ok(())
    }
}

impl NameHistory for TrackableItem {
    fn add_name_to_history(&mut self, name: &str) {
        self.name_history.push(name.to_string());
    }

    fn name_history(&self) -> Vec<Cow<'_, str>> {
        self.name_history.iter().map(|s| Cow::Borrowed(s.as_str())).collect()
    }
}

fn main() {
    let mut item = TrackableItem { name: "Initial".to_string(), name_history: vec![] };

    // Change name and track history
    item.set_name_with_history("New Name").unwrap();
    item.set_name_with_history("Another Name").unwrap();

    // Print name history
    println!("Name history: {:?}", item.name_history());
}

Name Validation

You can validate names using custom logic or regular expressions with the ValidateName trait.

use named_item::{ValidateName, NameValidator};

fn main() {
    let validator = NameValidator::new(r"^[a-zA-Z]+$").unwrap();

    assert!(validator.validate_name("ValidName").is_ok());
    assert!(validator.validate_name("Invalid Name!").is_err());
}

Traits

Named

Returns the current name of an item.

pub trait Named {
    fn name(&self) -> Cow<'_, str>;
}

SetName

Sets a new name for an item.

pub trait SetName {
    fn set_name(&mut self, name: &str) -> Result<(), ()>;
}

ResetName

Resets the name of an item to a default value.

pub trait ResetName: SetName + DefaultName {
    fn reset_name(&mut self) -> Result<(), ()> {
        self.set_name(&Self::default_name())
    }
}

DefaultName

Returns the default name of an item.

pub trait DefaultName {
    fn default_name() -> Cow<'static, str>;
}

NameHistory

Tracks the history of names an item has had.

pub trait NameHistory {
    fn add_name_to_history(&mut self, name: &str);
    fn name_history(&self) -> Vec<Cow<'_, str>>;
}

SetNameWithHistory

Extends SetName by adding name changes to the history.

pub trait SetNameWithHistory: SetName + NameHistory {
    fn set_name_with_history(&mut self, name: &str) -> Result<(), ()>;
}

ValidateName

Validates a name using custom logic or regular expressions.

pub trait ValidateName {
    fn validate_name(name: &str) -> Result<(), ()>;
}

License

This crate is licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

Contribution

Contributions are welcome! Feel free to submit a pull request or open an issue on GitHub.