Options
All
  • Public
  • Public/Protected
  • All
Menu

Library @swim/codec

@swim/codec

package documentation chat

@swim/codec is an incremental I/O library, providing: functional parsers and writers; display, debug, and diagnostic formatters; and Unicode and binary codecs. @swim/codec is written in TypeScript, but can be used from either TypeScript or JavaScript. @swim/codec is part of the @swim/core framework.

Overview

Inputs and Outputs

An Input reader abstracts over a non-blocking token input stream, with single token lookahead. An Output writer abstracts over a non-blocking token output stream.

Parsers and Writers

A Parser incrementally reads from a sequence of Input chunks to produce a parsed result. A Writer incrementally writes to a sequence of Output chunks.

Binary codecs

The Binary factory has methods to create Input readers that read bytes out of byte buffers, and methods to create Output writers that write bytes into byte buffers.

Text codecs

The Unicode factory has methods to create Input readers that read Unicode code points out of strings, and methods to create Output writers that write Unicode code points into strings.

The Utf8 factory has methods to create Input readers that decode Unicode code points out of UTF-8 encoded byte buffers, and methods to create Output writers that encode Unicode code points into UTF-8 encoded byte buffers.

Binary-Text codecs

The Base10 factory has methods to create Parsers that incrementally parse decimal formatted integers, and methods to create Writers that incrementally write decimal formatted integers.

The Base16 factory has methods to create Parsers that incrementally decode hexadecimal encoded text input into byte buffers, and methods to create Writers that incrementally encode byte buffers to hexadecimal encoded text output.

The Base64 factory has methods to create Parsers that incrementally decode base-64 encoded text input into byte buffers, and methods to create Writers that incrementally encode byte buffers to base-64 encoded text output.

Formatters

The Display interface provides a standard way for implementing classes to directly output human readable display strings. Similarly, the Debug interface provides a standard way for implementing classes to directly output developer readable debug strings.

Format provides extension methods to output display and debug strings for all types, including builtin JavaScript types. OutputStyle provides helper functions to conditionally emit ASCII escape codes to stylize text for console output.

Diagnostics

A Tag abstracts over a source input location. A Mark describes a source input position, and a Span describes a source input range. A Diagnostic attaches an informational message to a source input location, and supports displaying the diagnostic as an annotated snippet of the relevant source input.

Installation

npm

For an npm-managed project, npm install @swim/codec to make it a dependency. TypeScript sources will be installed into node_modules/@swim/codec/main. Transpiled JavaScript and TypeScript definition files install into node_modules/@swim/codec/lib/main. And a pre-built UMD script can be found in node_modules/@swim/codec/dist/main/swim-codec.js.

Browser

Browser applications can load swim-core.js, which comes bundled with the swim/codec library, directly from the SwimOS CDN.

<!-- Development -->
<script src="https://cdn.swimos.org/js/latest/swim-core.js"></script>

<!-- Production -->
<script src="https://cdn.swimos.org/js/latest/swim-core.min.js"></script>

Alternatively, the standalone swim-system.js script may be loaded from the SwimOS CDN, which bundles @swim/codec together with all other @swim/system libraries.

<!-- Development -->
<script src="https://cdn.swimos.org/js/latest/swim-system.js"></script>

<!-- Production -->
<script src="https://cdn.swimos.org/js/latest/swim-system.min.js"></script>

Usage

ES6/TypeScript

@swim/codec can be imported as an ES6 module from TypeScript and other ES6-compatible environments.

import * as codec from "@swim/codec";

CommonJS/Node.js

@swim/codec can also be used as a CommonJS module in Node.js applications.

var codec = require("@swim/codec");

Browser

When loaded by a web browser, the swim-core.js script adds all @swim/codec library exports to the global swim namespace.

The swim-system.js script also adds all @swim/codec library exports to the global swim namespace, making it a drop-in replacement for swim-core.js when additional @swim/system libraries are needed.

Index

Type aliases

AnyInputSettings

AnyInputSettings: InputSettings | InputSettingsInit

AnyOutputSettings

AnyOutputSettings: OutputSettings | OutputSettingsInit

Variables

Const Base10

Base10: { countDigits: any; decimalParser: any; decodeDigit: any; encodeDigit: any; integerParser: any; integerWriter: any; isDigit: any; numberParser: any; parseDecimal: any; parseInteger: any; parseNumber: any; writeInteger: any }

Type declaration

  • countDigits: function
    • countDigits(value: number): number
    • Parameters

      • value: number

      Returns number

  • decimalParser: function
    • decimalParser(): Parser<number>
    • Returns Parser<number>

  • decodeDigit: function
    • decodeDigit(c: number): number
    • Parameters

      • c: number

      Returns number

  • encodeDigit: function
    • encodeDigit(b: number): number
    • Parameters

      • b: number

      Returns number

  • integerParser: function
    • integerParser(): Parser<number>
    • Returns Parser<number>

  • integerWriter: function
    • integerWriter(): Writer<number, unknown>
    • integerWriter(input: number): Writer<unknown, number>
    • Returns Writer<number, unknown>

    • Parameters

      • input: number

      Returns Writer<unknown, number>

  • isDigit: function
    • isDigit(c: number): boolean
    • Parameters

      • c: number

      Returns boolean

  • numberParser: function
    • numberParser(): Parser<number>
    • Returns Parser<number>

  • parseDecimal: function
    • Parameters

      Returns Parser<number>

  • parseInteger: function
    • Parameters

      Returns Parser<number>

  • parseNumber: function
    • Parameters

      Returns Parser<number>

  • writeInteger: function
    • writeInteger(input: number, output: Output<unknown>): Writer<unknown, unknown>
    • Parameters

      • input: number
      • output: Output<unknown>

      Returns Writer<unknown, unknown>

Const Binary

Binary: { output: any; outputBuffer: any }

Type declaration

  • output: function
    • Parameters

      Returns Output<Uint8Array>

    • Parameters

      Returns Output<Uint8Array>

  • outputBuffer: function
    • outputBuffer(array: Uint8Array, offset?: number, length?: number): OutputBuffer<Uint8Array>
    • Parameters

      • array: Uint8Array
      • Optional offset: number
      • Optional length: number

      Returns OutputBuffer<Uint8Array>

Const Format

Format: { lineSeparator: string; debug: any; debugChar: any; debugNumber: any; debugString: any; decimal: any; display: any; displayNumber: any; duration: any; encodeHex: any; prefix: any; trimTrailingZeros: any }

Type declaration

  • Readonly lineSeparator: string
  • debug: function
    • debug(object: unknown, output: Output<unknown>): void
    • debug(object: unknown, settings?: AnyOutputSettings): string
    • Parameters

      • object: unknown
      • output: Output<unknown>

      Returns void

    • Parameters

      Returns string

  • debugChar: function
    • debugChar(character: number, output: Output<unknown>): void
    • Parameters

      • character: number
      • output: Output<unknown>

      Returns void

  • debugNumber: function
    • debugNumber(value: number, output: Output<unknown>): void
    • Parameters

      • value: number
      • output: Output<unknown>

      Returns void

  • debugString: function
    • debugString(string: string, output: Output<unknown>): void
    • Parameters

      • string: string
      • output: Output<unknown>

      Returns void

  • decimal: function
    • decimal(value: number, precision?: number): string
    • Parameters

      • value: number
      • Optional precision: number

      Returns string

  • display: function
    • display(object: unknown, output: Output<unknown>): void
    • display(object: unknown, settings?: AnyOutputSettings): string
    • Parameters

      • object: unknown
      • output: Output<unknown>

      Returns void

    • Parameters

      Returns string

  • displayNumber: function
    • displayNumber(value: number, output: Output<unknown>): void
    • Parameters

      • value: number
      • output: Output<unknown>

      Returns void

  • duration: function
    • duration(millis: number, separator?: string): string
    • Parameters

      • millis: number
      • Optional separator: string

      Returns string

  • encodeHex: function
    • encodeHex(x: number): number
    • Parameters

      • x: number

      Returns number

  • prefix: function
    • prefix(value: number, precision?: number): string
    • Parameters

      • value: number
      • Optional precision: number

      Returns string

  • trimTrailingZeros: function
    • trimTrailingZeros(s: string): string
    • Parameters

      • s: string

      Returns string

Const OutputStyle

OutputStyle: { black: any; blackBold: any; blue: any; blueBold: any; bold: any; cyan: any; cyanBold: any; faint: any; gray: any; grayBold: any; green: any; greenBold: any; magenta: any; magentaBold: any; red: any; redBold: any; reset: any; yellow: any; yellowBold: any }

Type declaration

  • black: function
    • black(output: Output<unknown>): void
    • Parameters

      Returns void

  • blackBold: function
    • blackBold(output: Output<unknown>): void
    • Parameters

      Returns void

  • blue: function
    • blue(output: Output<unknown>): void
    • Parameters

      Returns void

  • blueBold: function
    • blueBold(output: Output<unknown>): void
    • Parameters

      Returns void

  • bold: function
    • bold(output: Output<unknown>): void
    • Parameters

      Returns void

  • cyan: function
    • cyan(output: Output<unknown>): void
    • Parameters

      Returns void

  • cyanBold: function
    • cyanBold(output: Output<unknown>): void
    • Parameters

      Returns void

  • faint: function
    • faint(output: Output<unknown>): void
    • Parameters

      Returns void

  • gray: function
    • gray(output: Output<unknown>): void
    • Parameters

      Returns void

  • grayBold: function
    • grayBold(output: Output<unknown>): void
    • Parameters

      Returns void

  • green: function
    • green(output: Output<unknown>): void
    • Parameters

      Returns void

  • greenBold: function
    • greenBold(output: Output<unknown>): void
    • Parameters

      Returns void

  • magenta: function
    • magenta(output: Output<unknown>): void
    • Parameters

      Returns void

  • magentaBold: function
    • magentaBold(output: Output<unknown>): void
    • Parameters

      Returns void

  • red: function
    • red(output: Output<unknown>): void
    • Parameters

      Returns void

  • redBold: function
    • redBold(output: Output<unknown>): void
    • Parameters

      Returns void

  • reset: function
    • reset(output: Output<unknown>): void
    • Parameters

      Returns void

  • yellow: function
    • yellow(output: Output<unknown>): void
    • Parameters

      Returns void

  • yellowBold: function
    • yellowBold(output: Output<unknown>): void
    • Parameters

      Returns void

Const Unicode

Unicode: { isAlpha: any; isDigit: any; isNewline: any; isSpace: any; isWhitespace: any; stringInput: any; stringOutput: any; stringWriter: any; writeString: any }

Type declaration

  • isAlpha: function
    • isAlpha(c: number): boolean
    • Parameters

      • c: number

      Returns boolean

  • isDigit: function
    • isDigit(c: number): boolean
    • Parameters

      • c: number

      Returns boolean

  • isNewline: function
    • isNewline(c: number): boolean
    • Parameters

      • c: number

      Returns boolean

  • isSpace: function
    • isSpace(c: number): boolean
    • Parameters

      • c: number

      Returns boolean

  • isWhitespace: function
    • isWhitespace(c: number): boolean
    • Parameters

      • c: number

      Returns boolean

  • stringInput: function
    • stringInput(string: string): Input
    • Parameters

      • string: string

      Returns Input

  • stringOutput: function
    • Parameters

      Returns Output<string>

    • Parameters

      Returns Output<string>

  • stringWriter: function
    • stringWriter<I>(): Writer<I, unknown>
    • stringWriter<I_1, O>(input: O): Writer<I_1, O>
    • Type parameters

      • I

      Returns Writer<I, unknown>

    • Type parameters

      • I_1

      • O

      Parameters

      • input: O

      Returns Writer<I_1, O>

  • writeString: function
    • writeString<I_2>(input: unknown, output: Output<unknown>): Writer<I_2, unknown>
    • Type parameters

      • I_2

      Parameters

      • input: unknown
      • output: Output<unknown>

      Returns Writer<I_2, unknown>

Const Utf8

Utf8: { decodedOutput: any; decodedString: any; encodedOutput: any; sizeOf: any }

Type declaration

  • decodedOutput: function
    • Type parameters

      • T

      Parameters

      Returns Output<T>

  • decodedString: function
    • decodedString(): Output<string>
    • Returns Output<string>

  • encodedOutput: function
    • Type parameters

      • T_1

      Parameters

      Returns Output<T_1>

  • sizeOf: function
    • sizeOf(c: undefined | number, errorMode?: UtfErrorMode): number
    • sizeOf(c: undefined | number): number
    • sizeOf(string: string, errorMode?: UtfErrorMode): number
    • sizeOf(string: string): number
    • Parameters

      Returns number

    • Parameters

      • c: undefined | number

      Returns number

    • Parameters

      Returns number

    • Parameters

      • string: string

      Returns number

Generated using TypeDoc