Module protocol 

LiNo substitution operations over TCP/IP (issue #105).

Two interchangeable protocols carry LiNo documents between a client and a server:

• TextLinoProtocol: UTF-8 LiNo text, each message ended by a line holding only . (SMTP-style dot-stuffing keeps the framing unambiguous).
• BinaryLinoProtocol: a self-delimiting LinksPacket made of sections of links that share one reference width (1, 2, 4 or 8 bytes) and one arity range. By default every link is a doublet and the whole packet uses the narrowest width that fits; the options external references, arity (for example 2..3 or 1..) and packed widths can be switched on one by one.

Both implement LinoProtocol, so a LinoConnection or a LinksClient switches protocol by swapping one value. A LinksServer detects the protocol of every message and answers in kind.

A request is a substitution query, so it covers create, read, update and delete; the reply lists the (before) (after) changes, exactly like clink --changes. The empty request reads the whole store.

use link_cli::protocol::{format_document, parse_document, BinaryLinoOptions, BinaryLinoProtocol};

let document = parse_document("() ((1 1))").unwrap();
let binary = BinaryLinoProtocol::with_options(
    BinaryLinoOptions::default().with_external_references(true),
);
let bytes = binary.encode(&document).unwrap();
assert_eq!(binary.decode(&bytes).unwrap(), document);
assert_eq!(format_document(&document), "() ((1 1))");

Re-exports

pub use archive::export_store;

pub use archive::export_store_file;

pub use archive::import_store;

pub use archive::import_store_file;

pub use links_operations::LinksOperation;

pub use packet::ArityRange;

pub use packet::DecodeLimits;

pub use packet::LinksPacket;

pub use packet::Reference;

pub use packet::Section;

Modules

archive

Store archive: a whole links store in binary links notation.

links_operations

The links interface (ILinks in C#, [doublets::Links] in Rust) as LiNo documents, so a store behind a LinksServer is used exactly like a local one through RemoteLinks.

packet

Binary links notation: a self-delimiting packet of links.

Structs

BinaryLinoOptions

Optional features of the binary LiNo protocol.

BinaryLinoProtocol

Binary links packets (see crate::protocol::packet); every message is self-delimiting, so no extra framing is needed.

LinksClient

Sends substitution queries to a LiNo server over any LinoProtocol.

LinksServer

A bound, not yet serving, LiNo server.

LinoConnection

A byte stream decorated with a LinoProtocol.

RemoteLinks

A links store served by a LinksServer, usable wherever a local store is.

ServerOptions

Server configuration.

ShutdownHandle

Stops a running LinksServer::serve from another thread.

TextLinoProtocol

UTF-8 LiNo text, one message per block of lines ended by a line holding only .. Lines starting with . get one extra . (SMTP dot-stuffing).

Enums

AcceptedProtocols

Which protocols a server accepts.

MessageFormat

The wire format a message arrived in, so a reply can use the same one.

ProtocolError

Everything that can go wrong while encoding, decoding or exchanging a LiNo message.

Traits

LinoProtocol

Reads and writes whole LiNo documents on a byte stream.

Functions

decode_document

Converts a packet back into a document.

encode_document

Converts a document into a packet.

error_document

The reply document for a failed request: (error: 'message').

error_message

Returns the message of an (error: 'message') reply.

execute_request

Executes one request against storage.

format_document

Formats a document as canonical LiNo text, one top-level link per line.

format_link

Formats one link as it appears nested inside another link.

format_reference

Quotes a reference when it would not survive parsing as a bare word.

is_binary_start

True when byte starts a binary message rather than a text one.

parse_document

Parses LiNo text into a canonical document. Blank input is the empty document.

read_any_document

Reads one message in whichever protocol the peer used.

Type Aliases

LinoDocument

A LiNo document: the list of top-level links of a message.

ProtocolResult

Result alias used throughout crate::protocol.