known_values/lib.rs
1//! Known Values: A compact, deterministic representation for ontological
2//! concepts.
3//!
4//! This crate implements the [Blockchain Commons Known Values
5//! specification][bcr], providing a compact way to represent ontological
6//! concepts using 64-bit unsigned integers with optional human-readable names.
7//!
8//! # Basic Usage
9//!
10//! ```rust
11//! use known_values::{IS_A, KnownValue, KnownValuesStore, NOTE};
12//!
13//! // Use predefined constants
14//! assert_eq!(IS_A.value(), 1);
15//! assert_eq!(IS_A.name(), "isA");
16//!
17//! // Create custom known values
18//! let custom =
19//! KnownValue::new_with_name(1000u64, "myCustomValue".to_string());
20//! assert_eq!(custom.value(), 1000);
21//!
22//! // Use a store for bidirectional lookup
23//! let store = KnownValuesStore::new([IS_A, NOTE]);
24//! assert_eq!(store.known_value_named("isA").unwrap().value(), 1);
25//! ```
26//!
27//! # Directory Loading Feature
28//!
29//! When the `directory-loading` feature is enabled (default), this crate can
30//! load additional known values from JSON registry files.
31//!
32//! ## Default Behavior
33//!
34//! On first access to [`KNOWN_VALUES`], the crate automatically:
35//! 1. Initializes hardcoded known values from the registry
36//! 2. Scans `~/.known-values/` for JSON files
37//! 3. Loads entries from any `*.json` files found
38//! 4. Overrides hardcoded values if codepoints collide
39//!
40//! ## JSON File Format
41//!
42//! Registry files should follow the BlockchainCommons format:
43//!
44//! ```json
45//! {
46//! "entries": [
47//! {"codepoint": 1000, "name": "myValue", "type": "property"}
48//! ]
49//! }
50//! ```
51//!
52//! ## Custom Configuration
53//!
54//! Configure search paths before first access (requires `directory-loading`
55//! feature):
56//!
57//! ```rust,ignore
58//! use known_values::{set_directory_config, DirectoryConfig};
59//!
60//! // Use only custom paths
61//! set_directory_config(DirectoryConfig::with_paths(vec![
62//! "/etc/known-values".into(),
63//! "/usr/share/known-values".into(),
64//! ])).unwrap();
65//! ```
66//!
67//! ## Disabling Directory Loading
68//!
69//! To disable at compile time:
70//!
71//! ```toml
72//! [dependencies]
73//! known-values = { version = "0.15", default-features = false }
74//! ```
75//!
76//! [bcr]: https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2023-002-known-value.md
77
78mod known_value;
79pub use known_value::KnownValue;
80
81mod known_value_store;
82pub use known_value_store::KnownValuesStore;
83
84mod known_values_registry;
85pub use known_values_registry::*;
86
87#[cfg(feature = "directory-loading")]
88mod directory_loader;
89
90#[cfg(feature = "directory-loading")]
91pub use directory_loader::{
92 ConfigError, DirectoryConfig, LoadError, LoadResult, RegistryEntry,
93 RegistryFile, add_search_paths, load_from_config, load_from_directory,
94 set_directory_config,
95};