@thomasfosterau/effect-rdf 0.0.0-stage → 0.1.0

package/src/n3/internal/writer.ts

@@ -0,0 +1,344 @@
+/**
+ * Pretty-printer for the N3 model.
+ *
+ * @internal
+ */
+import * as Arr from 'effect/Array';
+import * as MutableHashMap from 'effect/MutableHashMap';
+import * as MutableHashSet from 'effect/MutableHashSet';
+import * as Option from 'effect/Option';
+import * as Iri from '../../Iri.ts';
+import * as PrefixMap from '../../PrefixMap.ts';
+import * as Term from '../../Term.ts';
+import { rdf, xsd } from '../../Vocab.ts';
+import * as Model from '../Model.ts';
+import * as Guards from './guards.ts';
+import { loop } from './loop.ts';
+import { isPnChars, isPnCharsBase, isPnCharsU } from './parser.ts';
+import { i18n, log, sameAs } from '../Vocab.ts';
+
+/** @internal */
+export interface WriterOptions {
+  readonly prefixes: PrefixMap.PrefixMap;
+  readonly baseIri: Option.Option<string>;
+  /** Indentation unit. */
+  readonly indent: string;
+}
+
+/** Whether a string is a valid `PN_PREFIX` (or empty). */
+const isPnPrefix = (s: string): boolean => {
+  const cps = Array.from(s, codePoint);
+  if (!Arr.isReadonlyArrayNonEmpty(cps)) return true;
+  if (!isPnCharsBase(cps[0])) return false;
+  if (cps.length > 1 && cps[cps.length - 1] === 0x2e) return false;
+  return cps.slice(1).every((c) => c === 0x2e || isPnChars(c));
+};
+
+/** The code point of a character (as `Array.from` splits a string). */
+const codePoint = (ch: string): number => ch.codePointAt(0) ?? 0;
+
+/** Whether a string is a valid quick variable name (without `?`). */
+const isVarName = (s: string): boolean => {
+  const cps = Array.from(s, codePoint);
+  return Arr.isReadonlyArrayNonEmpty(cps) && isPnCharsU(cps[0]) && cps.slice(1).every(isPnChars);
+};
+
+const BLANK_LABEL = /^[A-Za-z0-9_](?:[\w.-]*[\w-])?$/;
+const INTEGER = /^[+-]?\d+$/;
+const DECIMAL = /^[+-]?\d*\.\d+$/;
+const DOUBLE = /^[+-]?(?:\d+\.\d*|\.\d+|\d+)[eE][+-]?\d+$/;
+
+interface BlankInfo {
+  refs: number;
+  predicate: boolean;
+  /** The first formula the blank node occurs in. */
+  readonly formula: Model.Formula;
+  /** Whether it occurs in another formula (object) too. */
+  shared: boolean;
+}
+
+/** The statements of one subject (or predicate), in order. */
+interface Group {
+  readonly first: Model.Statement;
+  readonly statements: Array<Model.Statement>;
+}
+
+/** @internal */
+export const write = (root: Model.Formula, options: WriterOptions): string =>
+  new Writer(root, options).run();
+
+class Writer {
+  private readonly prefixes: PrefixMap.PrefixMap;
+  private readonly base: Option.Option<string>;
+  private readonly unit: string;
+  private readonly usedPrefixes = MutableHashSet.empty<string>();
+  private readonly blanks = MutableHashMap.empty<string, BlankInfo>();
+  private readonly blankLabels = MutableHashMap.empty<string, string>();
+  private readonly usedLabels = MutableHashSet.empty<string>();
+  private readonly varNames = MutableHashMap.empty<string, string>();
+  /** Subject groups of inlinable blank nodes, per formula. */
+  private readonly inlineGroups = MutableHashMap.empty<string, Array<Model.Statement>>();
+  private readonly inlinable = MutableHashSet.empty<string>();
+  private readonly emitted = MutableHashSet.empty<string>();
+
+  private readonly root: Model.Formula;
+  constructor(root: Model.Formula, options: WriterOptions) {
+    this.root = root;
+    this.prefixes = options.prefixes;
+    this.base = options.baseIri;
+    this.unit = options.indent;
+  }
+
+  run(): string {
+    this.analyse(this.root);
+    MutableHashMap.forEach(this.blanks, (info, label) => {
+      if (!info.predicate && info.refs <= 1 && !info.shared) {
+        MutableHashSet.add(this.inlinable, label);
+      }
+    });
+    const body = this.formulaBody(this.root, 0);
+    const base = Option.match(this.base, {
+      onNone: () => '',
+      onSome: (iri) => `@base <${Term.escapeIri(iri)}> .\n`,
+    });
+    const header = Arr.reduce(
+      Arr.fromIterable(this.prefixes.prefixes),
+      base,
+      (acc, [prefix, ns]) =>
+        MutableHashSet.has(this.usedPrefixes, prefix)
+          ? `${acc}@prefix ${prefix}: <${Term.escapeIri(ns)}> .\n`
+          : acc,
+    );
+    return header === '' ? body : `${header}\n${body}`;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Analysis
+  // ---------------------------------------------------------------------------
+
+  /** The blank node's information, made (in `f`) on first sight. */
+  private info(label: string, f: Model.Formula): BlankInfo {
+    const known = this.blanks.backing.get(label);
+    if (known !== undefined) {
+      if (known.formula !== f) known.shared = true;
+      return known;
+    }
+    const info: BlankInfo = { refs: 0, predicate: false, formula: f, shared: false };
+    MutableHashMap.set(this.blanks, label, info);
+    return info;
+  }
+
+  private analyse(f: Model.Formula): void {
+    f.statements.forEach((s) => {
+      this.analyseTerm(s.subject, f, 'subject');
+      this.analyseTerm(s.predicate, f, 'predicate');
+      this.analyseTerm(s.object, f, 'object');
+    });
+  }
+
+  // Plain refinements rather than `Match`: `analyseTerm` runs for every term written.
+  private analyseTerm(t: Model.N3Term, f: Model.Formula, position: string): void {
+    if (Guards.isBlankNode(t)) {
+      const info = this.info(t.value, f);
+      if (position === 'predicate') info.predicate = true;
+      else if (position !== 'subject') info.refs++;
+    } else if (t instanceof Model.Collection) {
+      t.items.forEach((item) => this.analyseTerm(item, f, 'item'));
+    } else if (t instanceof Model.Formula) {
+      this.analyse(t);
+    }
+  }
+
+  /** Whether `subject` is an inlinable blank node. */
+  private isInlinable(subject: Model.N3Term): subject is Term.BlankNode {
+    return Guards.isBlankNode(subject) && MutableHashSet.has(this.inlinable, subject.value);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Statements
+  // ---------------------------------------------------------------------------
+
+  private formulaBody(f: Model.Formula, depth: number): string {
+    const groups = MutableHashMap.empty<string, Group>();
+    f.statements.forEach((s) => {
+      const k = s.subject.key;
+      let g = groups.backing.get(k);
+      if (g === undefined) {
+        g = { first: s, statements: [s] };
+        MutableHashMap.set(groups, k, g);
+      } else g.statements.push(s);
+      if (this.isInlinable(s.subject)) {
+        MutableHashMap.set(this.inlineGroups, s.subject.value, g.statements);
+      }
+    });
+    const pad = this.unit.repeat(depth);
+    const lines: Array<string> = [];
+    const render = (g: Group) => {
+      const subject = g.first.subject;
+      if (this.isInlinable(subject)) {
+        MutableHashSet.add(this.emitted, subject.value);
+        lines.push(
+          `${pad}[ ${this.predicateObjects(g.statements, depth + 1, ` ;\n${pad}${this.unit}`)} ] .`,
+        );
+        return;
+      }
+      const subj = this.term(subject, depth);
+      lines.push(
+        `${pad}${subj} ${this.predicateObjects(g.statements, depth, ` ;\n${pad}${this.unit}`)} .`,
+      );
+    };
+    const deferred: Array<Group> = [];
+    MutableHashMap.forEach(groups, (g) => {
+      const subject = g.first.subject;
+      if (this.isInlinable(subject) && this.blanks.backing.get(subject.value)?.refs === 1) {
+        deferred.push(g);
+        return;
+      }
+      render(g);
+    });
+    // Inlinable blank nodes that were never reached (reference cycles) are
+    // written with labels.
+    deferred.forEach((g) => {
+      const subject = g.first.subject;
+      if (!Guards.isBlankNode(subject) || MutableHashSet.has(this.emitted, subject.value)) return;
+      MutableHashSet.remove(this.inlinable, subject.value);
+      render(g);
+    });
+    return lines.join('\n') + (Arr.isReadonlyArrayNonEmpty(lines) ? '\n' : '');
+  }
+
+  private predicateObjects(
+    statements: ReadonlyArray<Model.Statement>,
+    depth: number,
+    separator: string,
+  ): string {
+    const byPredicate = MutableHashMap.empty<
+      string,
+      { predicate: Model.N3Term; objects: Array<Model.N3Term> }
+    >();
+    statements.forEach((s) => {
+      const k = s.predicate.key;
+      const e = byPredicate.backing.get(k);
+      if (e === undefined) {
+        MutableHashMap.set(byPredicate, k, { predicate: s.predicate, objects: [s.object] });
+      } else e.objects.push(s.object);
+    });
+    return Arr.map(
+      Arr.fromIterable(MutableHashMap.values(byPredicate)),
+      ({ predicate, objects }) =>
+        `${this.verb(predicate, depth)} ${objects.map((o) => this.term(o, depth)).join(', ')}`,
+    ).join(separator);
+  }
+
+  private verb(t: Model.N3Term, depth: number): string {
+    if (Guards.isNamedNode(t)) {
+      if (t.value === rdf.type.value) return 'a';
+      if (t.value === log.implies.value) return '=>';
+      if (t.value === log.isImpliedBy.value) return '<=';
+      if (t.value === sameAs.value) return '=';
+    }
+    return this.term(t, depth);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Terms
+  // ---------------------------------------------------------------------------
+
+  // Plain refinements rather than `Match`: `term` runs for every term written.
+  private term(t: Model.N3Term, depth: number): string {
+    if (Guards.isNamedNode(t)) return this.iri(t.value);
+    if (Guards.isBlankNode(t)) return this.blank(t, depth);
+    if (Guards.isLiteral(t)) return this.literal(t);
+    if (Guards.isVariable(t)) return this.variable(t);
+    if (t instanceof Model.Collection) {
+      return Arr.isReadonlyArrayEmpty(t.items)
+        ? '()'
+        : `( ${t.items.map((i) => this.term(i, depth)).join(' ')} )`;
+    }
+    return this.formula(t, depth);
+  }
+
+  private formula(f: Model.Formula, depth: number): string {
+    if (Arr.isReadonlyArrayEmpty(f.statements)) return '{}';
+    const inner = this.formulaBody(f, depth + 1);
+    if (f.statements.length === 1) {
+      const line = inner.trim();
+      if (!line.includes('\n') && line.length <= 80) return `{ ${line.replace(/ \.$/, '')} }`;
+    }
+    return `{\n${inner}${this.unit.repeat(depth)}}`;
+  }
+
+  private blank(b: Term.BlankNode, depth: number): string {
+    if (MutableHashSet.has(this.inlinable, b.value) && !MutableHashSet.has(this.emitted, b.value)) {
+      MutableHashSet.add(this.emitted, b.value);
+      const g = this.inlineGroups.backing.get(b.value);
+      if (g === undefined || Arr.isReadonlyArrayEmpty(g)) return '[]';
+      const pad = this.unit.repeat(depth + 1);
+      return `[ ${this.predicateObjects(g, depth + 1, ` ;\n${pad}`)} ]`;
+    }
+    const known = this.blankLabels.backing.get(b.value);
+    if (known !== undefined) return `_:${known}`;
+    let label = BLANK_LABEL.test(b.value) ? b.value : `b${MutableHashMap.size(this.blankLabels)}`;
+    loop(() => {
+      if (!MutableHashSet.has(this.usedLabels, label)) return false;
+      label = `${label}_`;
+      return true;
+    });
+    MutableHashSet.add(this.usedLabels, label);
+    MutableHashMap.set(this.blankLabels, b.value, label);
+    return `_:${label}`;
+  }
+
+  private variable(v: Term.Variable): string {
+    const known = this.varNames.backing.get(v.value);
+    if (known !== undefined) return `?${known}`;
+    const name = isVarName(v.value) ? v.value : `v${MutableHashMap.size(this.varNames)}`;
+    MutableHashMap.set(this.varNames, v.value, name);
+    return `?${name}`;
+  }
+
+  private iri(value: string): string {
+    const compact = PrefixMap.compact(this.prefixes, value);
+    if (Option.isSome(compact) && isPnPrefix(compact.value[0])) {
+      const [prefix, local] = compact.value;
+      if (!local.endsWith('.')) {
+        MutableHashSet.add(this.usedPrefixes, prefix);
+        return `${prefix}:${local}`;
+      }
+    }
+    if (Option.isSome(this.base)) {
+      const rel = Iri.relativize(value, this.base.value);
+      if (Option.isSome(rel)) return `<${Term.escapeIri(rel.value)}>`;
+    }
+    return `<${Term.escapeIri(value)}>`;
+  }
+
+  private literal(l: Term.Literal): string {
+    const dt = l.datatype.value;
+    if (l.language === '') {
+      if (dt === xsd.integer.value && INTEGER.test(l.value)) return l.value;
+      if (dt === xsd.decimal.value && DECIMAL.test(l.value)) return l.value;
+      if (dt === xsd.double.value && DOUBLE.test(l.value)) return l.value;
+      if (dt === xsd.boolean.value && (l.value === 'true' || l.value === 'false')) return l.value;
+    }
+    const quoted = this.quote(l.value);
+    if (l.language !== '') {
+      return l.direction === undefined
+        ? `${quoted}@${l.language}`
+        : `${quoted}^^${this.iri(`${i18n.base}${l.language}_${l.direction}`)}`;
+    }
+    if (dt === Term.XSD_STRING) return quoted;
+    return `${quoted}^^${this.iri(dt)}`;
+  }
+
+  private quote(value: string): string {
+    if (value.includes('\n') && !value.endsWith('"')) {
+      // eslint-disable-next-line no-control-regex
+      const body = value.replace(/[\\"\u0000-\u0009\u000b-\u001f\u007f]/g, (ch) =>
+        ch === '\\' || ch === '"' ? `\\${ch}` : Term.escapeString(ch),
+      );
+      return `"""${body}"""`;
+    }
+    return `"${Term.escapeString(value)}"`;
+  }
+}

package/src/ntriples/Grammar.ts

@@ -0,0 +1,317 @@
+/**
+ * The N-Triples grammar's terminals as `@thomasfosterau/effect-parse`
+ * parsers over strings, for the grammars that include them: N-Quads,
+ * Turtle and TriG (whose `Grammar` module re-exports these and adds its
+ * own), and through Turtle N3, SPARQL and ShExC. Names follow the grammar:
+ * `iriRef` is `IRIREF`, `blankNodeLabel` is `BLANK_NODE_LABEL`, and so on.
+ *
+ * The character classes are the token-set counterparts of the `Lexical`
+ * predicates (`pnCharsBase` and `Lexical.isPnCharsBase` accept the same
+ * code points). String-valued terminals return their *value*: escapes are
+ * decoded and delimiters removed; IRIs are not resolved.
+ *
+ * @since 0.1.0
+ */
+import * as Ascii from '@thomasfosterau/effect-parse/Ascii';
+import * as Parser from '@thomasfosterau/effect-parse/Parser';
+import * as Token from '@thomasfosterau/effect-parse/Token';
+import * as Option from 'effect/Option';
+
+// -----------------------------------------------------------------------------
+// Character classes
+// -----------------------------------------------------------------------------
+
+/**
+ * `[0-9]`
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const digit: Token.StringTokenSet = Token.range('0', '9');
+
+/**
+ * `HEX`: `[0-9A-Fa-f]`
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const hex: Token.StringTokenSet = [digit, Token.range('a', 'f'), Token.range('A', 'F')];
+
+/**
+ * `[A-Za-z]`
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const alpha: Token.StringTokenSet = [Token.range('a', 'z'), Token.range('A', 'Z')];
+
+/**
+ * `[A-Za-z0-9]`
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const alphanumeric: Token.StringTokenSet = [alpha, digit];
+
+/**
+ * `PN_CHARS_BASE`
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const pnCharsBase: Token.StringTokenSet = [
+  alpha,
+  Token.range('À', 'Ö'),
+  Token.range('Ø', 'ö'),
+  Token.range('ø', '˿'),
+  Token.range('Ͱ', 'ͽ'),
+  Token.range('Ϳ', '῿'),
+  Token.range('‌', '‍'),
+  Token.range('⁰', '↏'),
+  Token.range('Ⰰ', '⿯'),
+  Token.range('、', '퟿'),
+  Token.range('豈', '﷏'),
+  Token.range('ﷰ', '�'),
+  Token.range('\u{10000}', '\u{effff}'),
+];
+
+/**
+ * `PN_CHARS_U`: `PN_CHARS_BASE | '_'`
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const pnCharsU: Token.StringTokenSet = [pnCharsBase, '_'];
+
+/**
+ * `PN_CHARS`
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const pnChars: Token.StringTokenSet = [
+  pnCharsU,
+  '-·',
+  digit,
+  Token.range('̀', 'ͯ'),
+  Token.range('‿', '⁀'),
+];
+
+/**
+ * The characters `IRIREF` excludes (besides `\`, which starts a `UCHAR`):
+ * `[#x00-#x20<>"{}|^`]`.
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const iriExcluded: Token.StringTokenSet = [Token.range('\u0000', ' '), '<>"{}|^`'];
+
+/**
+ * Runs of `chars` in which dots may appear, but not at the end: the
+ * `((chars | '.')* chars)?` tail of `PN_PREFIX`, `PN_LOCAL` and
+ * `BLANK_NODE_LABEL`.
+ *
+ * @since 0.1.0
+ * @category combinators
+ */
+export const dottedTail = <E, R>(chars: Parser.Parser<unknown, E, R>): Parser.Parser<void, E, R> =>
+  Parser.asVoid(
+    Parser.repeat(
+      Parser.alt(
+        Parser.repeat(chars, { min: 1 }),
+        Parser.seq(Token.takeWhile('.', { min: 1 }), Parser.peek(chars)),
+      ),
+    ),
+  );
+
+/**
+ * The same language as `dottedTail(alt(oneOf(set), extra))`, written so that
+ * a compiled grammar scans each run of `set` in one tight loop: a name's
+ * characters, with dots allowed between them but not at the end. `extra`
+ * matches the other things a name may contain (`PLX` in `PN_LOCAL`).
+ *
+ * @since 0.1.0
+ * @category combinators
+ * @example
+ * ```ts
+ * import * as Parser from '@thomasfosterau/effect-parse/Parser';
+ * import * as Token from '@thomasfosterau/effect-parse/Token';
+ * import { dottedRun, pnChars } from './Grammar.ts';
+ *
+ * const name = Parser.taken(Parser.seq(Token.oneOf(pnChars), dottedRun(pnChars)));
+ * // `a.b.` reads as `a.b`, leaving the final dot
+ * ```
+ */
+export const dottedRun = <E = never, R = never>(
+  set: Token.StringTokenSet,
+  extra?: Parser.Parser<unknown, E, R>,
+): Parser.Parser<void, E, R> => {
+  const one = Token.oneOf(set);
+  const chars: Parser.Parser<unknown, E, R> = extra === undefined ? one : Parser.alt(one, extra);
+  const dots = Parser.seq(Token.takeWhile('.', { min: 1 }), Parser.peek(chars));
+  const run = Token.takeWhile(set, { min: 1 });
+  return Parser.asVoid(
+    Parser.repeat(extra === undefined ? Parser.alt(run, dots) : Parser.alt(run, extra, dots)),
+  );
+};
+
+// -----------------------------------------------------------------------------
+// Escapes
+// -----------------------------------------------------------------------------
+
+const codePoint = (digits: number): Parser.Parser<string> =>
+  Token.takeWhile(hex, digits).pipe(
+    Parser.expected(`${digits} hex digits`),
+    Parser.map((h) => parseInt(h, 16)),
+    Parser.filter((cp) => cp <= 0x10ffff),
+    Parser.map((cp) => String.fromCodePoint(cp)),
+  );
+
+/**
+ * What follows the backslash of a `UCHAR` (`uXXXX` or `UXXXXXXXX`),
+ * returning the character. For use as the escape of `Ascii.escaped`.
+ *
+ * @since 0.1.0
+ * @category escapes
+ */
+export const ucharEscape: Parser.Parser<string> = Parser.dispatch(Token.any, {
+  u: Parser.cut(codePoint(4)),
+  U: Parser.cut(codePoint(8)),
+}).pipe(Parser.expected('a unicode escape'));
+
+/**
+ * What follows the backslash of an `ECHAR` or a `UCHAR`, returning the
+ * character. For use as the escape of `Ascii.escaped`.
+ *
+ * @since 0.1.0
+ * @category escapes
+ */
+export const stringEscape: Parser.Parser<string> = Parser.dispatch(Token.any, {
+  t: Parser.succeed('\t'),
+  b: Parser.succeed('\b'),
+  n: Parser.succeed('\n'),
+  r: Parser.succeed('\r'),
+  f: Parser.succeed('\f'),
+  '"': Parser.succeed('"'),
+  "'": Parser.succeed("'"),
+  '\\': Parser.succeed('\\'),
+  u: Parser.cut(codePoint(4)),
+  U: Parser.cut(codePoint(8)),
+}).pipe(Parser.expected('an escape sequence'));
+
+/**
+ * `UCHAR`: `\uXXXX` or `\UXXXXXXXX`, returning the character.
+ *
+ * @since 0.1.0
+ * @category escapes
+ */
+export const uchar: Parser.Parser<string> = Parser.preceded(Token.literal('\\'), ucharEscape);
+
+/**
+ * `ECHAR`: `\` followed by one of `tbnrf"'\`, returning the character.
+ *
+ * @since 0.1.0
+ * @category escapes
+ */
+export const echar: Parser.Parser<string> = Parser.preceded(
+  Token.literal('\\'),
+  Parser.dispatch(Token.any, {
+    t: Parser.succeed('\t'),
+    b: Parser.succeed('\b'),
+    n: Parser.succeed('\n'),
+    r: Parser.succeed('\r'),
+    f: Parser.succeed('\f'),
+    '"': Parser.succeed('"'),
+    "'": Parser.succeed("'"),
+    '\\': Parser.succeed('\\'),
+  }),
+);
+
+// -----------------------------------------------------------------------------
+// IRIs and names
+// -----------------------------------------------------------------------------
+
+/**
+ * `IRIREF`, returning the IRI between the angle brackets with its `UCHAR`s
+ * decoded (not resolved against a base).
+ *
+ * @since 0.1.0
+ * @category terminals
+ */
+export const iriRef: Parser.Parser<string> = Parser.delimited(
+  Token.literal('<'),
+  Ascii.escaped(Token.takeTill([iriExcluded, '\\'], { min: 1 }), '\\', ucharEscape),
+  Token.literal('>'),
+);
+
+/**
+ * `BLANK_NODE_LABEL`, returning the label after `_:`.
+ *
+ * @since 0.1.0
+ * @category terminals
+ */
+export const blankNodeLabel: Parser.Parser<string> = Parser.preceded(
+  Token.literal('_:'),
+  Parser.taken(Parser.seq(Token.oneOf([pnCharsU, digit]), dottedRun(pnChars))),
+);
+
+// -----------------------------------------------------------------------------
+// Literals
+// -----------------------------------------------------------------------------
+
+/**
+ * `STRING_LITERAL_QUOTE`, returning the value.
+ *
+ * @since 0.1.0
+ * @category terminals
+ */
+export const stringLiteralQuote: Parser.Parser<string> = Parser.delimited(
+  Token.literal('"'),
+  Parser.cut(Ascii.escaped(Token.takeTill(['\\', '"', '\n\r'], { min: 1 }), '\\', stringEscape)),
+  Parser.cut(Token.literal('"')),
+);
+
+const languageTag = Parser.taken(
+  Parser.seq(
+    Token.takeWhile(alpha, { min: 1 }),
+    Parser.repeat(Parser.preceded(Token.literal('-'), Token.takeWhile(alphanumeric, { min: 1 }))),
+  ),
+);
+
+/**
+ * `LANGTAG` (RDF 1.1), returning the tag after `@`.
+ *
+ * @since 0.1.0
+ * @category terminals
+ */
+export const langTag: Parser.Parser<string> = Parser.preceded(Token.literal('@'), languageTag);
+
+/**
+ * A language tag with its base direction.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface LangDir {
+  readonly language: string;
+  readonly direction: 'ltr' | 'rtl' | undefined;
+}
+
+/**
+ * `LANG_DIR` (RDF 1.2): a language tag optionally followed by `--ltr` or
+ * `--rtl`.
+ *
+ * @since 0.1.0
+ * @category terminals
+ */
+export const langDir: Parser.Parser<LangDir> = Parser.seq(
+  langTag,
+  Parser.opt(
+    Parser.preceded(Token.literal('--'), Parser.alt(Token.literal('ltr'), Token.literal('rtl'))),
+  ),
+).pipe(
+  Parser.map(([language, direction]) => ({
+    language,
+    direction: Option.getOrUndefined(direction),
+  })),
+);