arena_terms/
lib.rs

1//! # Arena Terms
2//!
3//! A lightweight, arena-backed representation of Prolog–like terms.
4//!
5//! This crate provides a compact [`Term`] type for representing Prolog-like
6//! data structures, along with a typed arena [`Arena`] used to
7//! intern atoms, variables, strings, binaries and compound terms.  The
8//! underlying representation is designed around a fixed‐width 16
9//! byte handle which carries both the tag and value of a term.
10//!
11//! The primary entry points are [`Arena`] (for allocating
12//! interned data) and [`Term`] (the user visible term handle).  Terms
13//! can be matched using the [`Term::view`] method which yields a
14//! [`View`] that borrows from the underlying arena.  Equality and
15//! ordering are well defined according to Prolog's standard order of
16//! terms.  Users may construct lists and tuples conveniently via
17//! macros exported from this crate.
18//!
19//! ## Example
20//! ```rust
21//! # use arena_terms::{Arena, func, IntoTerm, list, tuple, var, View};
22//! // create an arena
23//! let mut arena = Arena::new();
24//!
25//! // build some primitive terms
26//! let a = arena.atom("hello");
27//! let b = arena.real(3.14);
28//! let c = arena.date(1_640_995_200_000i64);  // 2022-01-01T00:00:00Z
29//!
30//! // build a long list from an iterator
31//! let xs = arena.list((0..1_000_000).map(|x| x as f64));
32//!
33//! // build a compound term using the func! macro
34//! let term = func![
35//!     "example";
36//!     123,                // IntoTerm: integer
37//!     "abc",              // IntoTerm: &str
38//!     list![a, b, c, xs], // nested list (xs is shared)
39//!     tuple!(b, a, xs),   // nested tuple (xs is shared)
40//!     var!("X"),          // variable (implicit arena)
41//!     => &mut arena
42//! ];
43//!
44//! // inspect the resulting term
45//! if let Ok(View::Func(ar, functor, args)) = term.view(&arena) {
46//!     assert_eq!(functor.name(ar).unwrap(), "example");
47//!     assert_eq!(args.len(), 5);
48//!     // view nested terms recursively
49//!     match args[2].view(ar).unwrap() {
50//!         View::List(_, elems, _) => assert_eq!(elems.len(), 4),
51//!         _ => unreachable!(),
52//!     }
53//! }
54//! ```
55//!
56//! ## License
57//!
58//! Copyright (c) 2005–2025 IKH Software, Inc.
59//!
60//! Released under the terms of the GNU Lesser General Public License, version 3.0 or
61//! (at your option) any later version (LGPL-3.0-or-later).
62
63mod arena;
64mod display;
65mod error;
66mod oper;
67mod term;
68mod view;
69
70pub use arena::{Arena, ArenaID, ArenaStats, EpochID, MAX_LIVE_EPOCHS};
71pub use display::TermDisplay;
72pub(crate) use error::InternalTermError;
73pub use error::TermError;
74pub use oper::{
75    Assoc, Fixity, MAX_OPER_PREC, MIN_OPER_PREC, NON_OPER_PREC, OperArg, OperDef, OperDefTab,
76    OperDefs,
77};
78pub(crate) use term::{Handle, Slice, TinyArray};
79pub use term::{IntoTerm, Term};
80pub use view::View;
arena_terms/lib.rs

arena_terms/
lib.rs
