link_cli/protocol/
mod.rs

1//! LiNo substitution operations over TCP/IP (issue #105).
2//!
3//! Two interchangeable protocols carry LiNo documents between a client and a
4//! server:
5//!
6//! - [`TextLinoProtocol`]: UTF-8 LiNo text, each message ended by a line
7//!   holding only `.` (SMTP-style dot-stuffing keeps the framing unambiguous).
8//! - [`BinaryLinoProtocol`]: a self-delimiting [`LinksPacket`] made of
9//!   sections of links that share one reference width (1, 2, 4 or 8 bytes)
10//!   and one [arity range](ArityRange). By default every link is a doublet
11//!   and the whole packet uses the narrowest width that fits; the options
12//!   [external references](BinaryLinoOptions::external_references),
13//!   [arity](BinaryLinoOptions::arity) (for example `2..3` or `1..`) and
14//!   [packed widths](BinaryLinoOptions::packed_widths) can be switched on
15//!   one by one.
16//!
17//! Both implement [`LinoProtocol`], so a [`LinoConnection`] or a
18//! [`LinksClient`] switches protocol by swapping one value. A
19//! [`LinksServer`] detects the protocol of every message and answers in kind.
20//!
21//! A request is a substitution query, so it covers create, read, update and
22//! delete; the reply lists the `(before) (after)` changes, exactly like
23//! `clink --changes`. The empty request reads the whole store.
24//!
25//! ```
26//! use link_cli::protocol::{format_document, parse_document, BinaryLinoOptions, BinaryLinoProtocol};
27//!
28//! let document = parse_document("() ((1 1))").unwrap();
29//! let binary = BinaryLinoProtocol::with_options(
30//!     BinaryLinoOptions::default().with_external_references(true),
31//! );
32//! let bytes = binary.encode(&document).unwrap();
33//! assert_eq!(binary.decode(&bytes).unwrap(), document);
34//! assert_eq!(format_document(&document), "() ((1 1))");
35//! ```
36
37pub mod archive;
38mod client;
39mod error;
40mod format;
41pub mod links_operations;
42mod mapping;
43pub mod packet;
44mod protocols;
45mod remote_links;
46mod server;
47
48pub use archive::{export_store, export_store_file, import_store, import_store_file};
49pub use client::LinksClient;
50pub use error::{ProtocolError, ProtocolResult};
51pub use format::{format_document, format_link, format_reference, parse_document};
52pub use links_operations::LinksOperation;
53pub use mapping::{decode_document, encode_document, BinaryLinoOptions, LinoDocument};
54pub use packet::{ArityRange, DecodeLimits, LinksPacket, Reference, Section};
55pub use protocols::{
56    is_binary_start, read_any_document, BinaryLinoProtocol, LinoConnection, LinoProtocol,
57    MessageFormat, TextLinoProtocol,
58};
59pub use remote_links::RemoteLinks;
60pub use server::{
61    error_document, error_message, execute_request, AcceptedProtocols, LinksServer, ServerOptions,
62    ShutdownHandle,
63};
link_cli/protocol/mod.rs

link_cli/protocol/
mod.rs
