denoland-deno/std/encoding/README.md

encoding

Helper module for dealing with external data structures.

• base32
• binary
• csv
• toml
• yaml

Binary

Implements equivalent methods to Go's encoding/binary package.

Available Functions:

sizeof(dataType: RawTypes): number
getNBytes(r: Deno.Reader, n: number): Promise<Uint8Array>
varnum(b: Uint8Array, o: VarnumOptions = {}): number | Deno.EOF
varbig(b: Uint8Array, o: VarbigOptions = {}): bigint | Deno.EOF
putVarnum(b: Uint8Array, x: number, o: VarnumOptions = {}): number
putVarbig(b: Uint8Array, x: bigint, o: VarbigOptions = {}): number
readVarnum(r: Deno.Reader, o: VarnumOptions = {}): Promise<number>
readVarbig(r: Deno.Reader, o: VarbigOptions = {}): Promise<bigint>
writeVarnum(w: Deno.Writer, x: number, o: VarnumOptions = {}): Promise<number>
writeVarbig(w: Deno.Writer, x: bigint, o: VarbigOptions = {}): Promise<number>

CSV

• parseCsv(input: string | BufReader, opt: ParseCsvOptions): Promise<unknown[]>: Read the string/buffer into an

Usage

const string = "a,b,c\nd,e,f";

console.log(
  await parseCsv(string, {
    header: false
  })
);
// output:
// [["a", "b", "c"], ["d", "e", "f"]]

TOML

This module parse TOML files. It follows as much as possible the TOML specs. Be sure to read the supported types as not every specs is supported at the moment and the handling in TypeScript side is a bit different.

Supported types and handling

• ✔️ Keys
• ❗ String
• ✔️ Multiline String
• ✔️ Literal String
• ❗ Integer
• ✔️ Float
• ✔️ Boolean
• ✔️ Offset Date-time
• ✔️ Local Date-time
• ✔️ Local Date
• ❗ Local Time
• ✔️ Table
• ✔️ Inline Table
• ❗ Array of Tables

❗ Supported with warnings see Warning.

⚠️ Warning

String

• Regex : Due to the spec, there is no flag to detect regex properly in a TOML declaration. So the regex is stored as string.

Integer

For Binary / Octal / Hexadecimal numbers, they are stored as string to be not interpreted as Decimal.

Local Time

Because local time does not exist in JavaScript, the local time is stored as a string.

Inline Table

Inline tables are supported. See below:

animal = { type = { name = "pug" } }
## Output
animal = { type.name = "pug" }
## Output { animal : { type : { name : "pug" } }
animal.as.leaders = "tosin"
## Output { animal: { as: { leaders: "tosin" } } }
"tosin.abasi" = "guitarist"
## Output
"tosin.abasi" : "guitarist"

Array of Tables

At the moment only simple declarations like below are supported:

[[bin]]
name = "deno"
path = "cli/main.rs"

[[bin]]
name = "deno_core"
path = "src/foo.rs"

[[nib]]
name = "node"
path = "not_found"

will output:

{
  "bin": [
    { "name": "deno", "path": "cli/main.rs" },
    { "name": "deno_core", "path": "src/foo.rs" }
  ],
  "nib": [{ "name": "node", "path": "not_found" }]
}

Usage

Parse

import { parse } from "./parser.ts";
import { readFileStrSync } from "../fs/read_file_str.ts";

const tomlObject = parse(readFileStrSync("file.toml"));

const tomlString = 'foo.bar = "Deno"';
const tomlObject22 = parse(tomlString);

Stringify

import { stringify } from "./parser.ts";
const obj = {
  bin: [
    { name: "deno", path: "cli/main.rs" },
    { name: "deno_core", path: "src/foo.rs" }
  ],
  nib: [{ name: "node", path: "not_found" }]
};
const tomlString = stringify(obj);

YAML

YAML parser / dumper for Deno

Heavily inspired from js-yaml

Basic usage

parse parses the yaml string, and stringify dumps the given object to YAML string.

import { parse, stringify } from "https://deno.land/std/encoding/yaml.ts";

const data = parse(`
foo: bar
baz:
  - qux
  - quux
`);
console.log(data);
// => { foo: "bar", baz: [ "qux", "quux" ] }

const yaml = stringify({ foo: "bar", baz: ["qux", "quux"] });
console.log(yaml);
// =>
// foo: bar
// baz:
//   - qux
//   - quux

If your YAML contains multiple documents in it, you can use parseAll for handling it.

import { parseAll } from "https://deno.land/std/encoding/yaml.ts";

const data = parseAll(`
---
id: 1
name: Alice
---
id: 2
name: Bob
---
id: 3
name: Eve
`);
console.log(data);
// => [ { id: 1, name: "Alice" }, { id: 2, name: "Bob" }, { id: 3, name: "Eve" } ]

API

parse(str: string, opts?: ParserOption): unknown

Parses the YAML string with a single document.

parseAll(str: string, iterator?: Function, opts?: ParserOption): unknown

Parses the YAML string with multiple documents. If the iterator is given, it's applied to every document instead of returning the array of parsed objects.

stringify(obj: object, opts?: DumpOption): string

Serializes object as a YAML document.

⚠️ Limitations

• binary type is currently not stable
• function, regexp, and undefined type are currently not supported

More example

See ./yaml/example folder and js-yaml repository.

base32

RFC4648 base32 encoder/decoder for Deno

Basic usage

encode encodes a Uint8Array to RFC4648 base32 representation, and decode decodes the given RFC4648 base32 representation to a Uint8Array.

import { encode, decode } from "https://deno.land/std/encoding/base32.ts";

const b32Repr = "RC2E6GA=";

const binaryData = decode(b32Repr);
console.log(binaryData);
// => Uint8Array [ 136, 180, 79, 24 ]

console.log(encode(binaryData));
// => RC2E6GA=