links-notation (languages: en • ru)

		JavaScript
		Rust
		C#
		Python
		Go
		Java
		PHP

Link Foundation's Links Notation Class Library.

This library gives you an ability to convert any string that contains links notation into a list of links and back to the string after modifications are made.

Links notation is based on two concepts references and links. Each reference references other link. The notation supports links with any number of references to other links.

Quick Start

C#

var parser = new Link.Foundation.Links.Notation.Parser();
var links = parser.Parse("papa (lovesMama: loves mama)");

JavaScript

import { Parser } from 'links-notation';
const parser = new Parser();
const links = parser.parse("papa (lovesMama: loves mama)");

Rust

use links_notation::parse_lino;
let links = parse_lino("papa (lovesMama: loves mama)").unwrap();

Python

from links_notation import Parser
parser = Parser()
links = parser.parse("papa (lovesMama: loves mama)")

Go

import lino "github.com/link-foundation/links-notation/go"
links, _ := lino.Parse("papa (lovesMama: loves mama)")

Java

import io.github.linkfoundation.linksnotation.Parser;
Parser parser = new Parser();
List<Link> links = parser.parse("papa (lovesMama: loves mama)");

PHP

use LinkFoundation\LinksNotation\Parser;
$parser = new Parser();
$links = $parser->parse("papa (lovesMama: loves mama)");

Examples

Links notation (lino)

Doublets (2-tuple)

papa (lovesMama: loves mama)
son lovesMama
daughter lovesMama
all (love mama)

Triplets (3-tuple)

papa has car
mama has house
(papa and mama) are happy

Sequences (N-tuple)

I'm a friendly AI.
(I'm a friendly AI too.)
(linksNotation: links notation)
(This is a linksNotation as well)
(linksNotation supports (unlimited number (of references) in each link))
(sequence (of references) surrounded by parentheses is a link)
parentheses may be ommitted if the whole line is a single link

Indented Syntax

Links can also use indented syntax for better readability:

3:
  papa
  loves
  mama

This is equivalent to:

(3: papa loves mama)

Multi-line Groups

A parenthesized group opens a nested context: its body starts fresh at indentation level zero and follows the same rules the root document does, so a line break inside parentheses is structure rather than decoration.

value (
  id "1"
  label "one"
)

This reads as (value ((id 1) (label one))) - two children, each a link of its own - and not as one flat list in which the boundary between id and label would be lost. Indentation works inside a group exactly as it does at the root, and a body that stays on a single line still collapses to a single link, so (a b c) is unchanged.

All seven implementations agree on this. experiments/issue-282/parity parses the document above with each of them and fails if any one reads it differently. The complete rules are in the grammar.

So that means that this text is also links notation. So most of the text in the world already may be parsed as links notation. That makes links notation the most easy an natural/intuitive/native one.

What is Links Notation?

Links Notation (Lino) is a simple, intuitive format for representing structured data as links between entities references to links. It's designed to be:

• Natural: Most text can already be parsed as links notation
• Flexible: Supports any number of references in each link
• Universal: Can represent doublets, triplets, and N-tuples
• Hierarchical: Supports nested structures with indentation

The notation uses two core concepts:

• References: Points to other links (like variables or identifiers)
• Links: Connect references together with optional identifiers

Documentation

For detailed implementation guides and API references, see the language-specific documentation:

• C# Documentation - Complete API reference
• PDF Documentation - Complete reference for offline reading
• C# README - Installation and usage guide
• JavaScript README - Modern web development guide
• Rust README - High-performance parsing guide
• Python README - Python package guide
• Go README - Go package guide
• Java README - Java/Maven package guide
• PHP README - PHP/Composer package guide

Additional resources:

• Grammar - The notation in EBNF, with the indentation and nested context rules spelled out (syntax diagrams)
• Test Case Comparison - Test-by-test coverage comparison across all seven language implementations
• Links Theory 0.0.2 - Theoretical foundation that Links Notation fully supports

Test Coverage & Implementation Parity

All seven language implementations (C#, JavaScript, Rust, Python, Go, Java, PHP) maintain equivalent core functionality, and the overlap is verified test by test rather than asserted:

Language	Tests	Test categories
Python	146	14
JavaScript	214	17
Rust	299	19
C#	207	18
Go	86	10
Java	133	9
PHP	183	16

The table is written by scripts/create-test-case-comparison.mjs, which reads the test files themselves and also produces TEST_CASE_COMPARISON.md - the full matrix of which implementation has which test, each cell linking to the test. The docs workflow runs that script with --check on every pull request, so a test added in one language and forgotten in the others shows up as a gap in the matrix instead of as a README that quietly went stale. It used to be a hand-written list, and had drifted to six languages and six wrong counts.

Known Implementation Differences

Some language-specific features are intentional:

• LinksGroup - a parsed group of links kept as one object - exists in JavaScript, C# and Java. Python, Rust, Go and PHP expose the same structure as nested Link values instead.
• Tuple conversion - building a link from a language tuple - is offered where the language has the syntax for it: C# via implicit operators and Rust via From implementations.

These differences are by design and do not affect core parsing/formatting functionality.