Terrace JavaScript Documentation

Getting Started

# NPM (https://npmjs.com)
$ npm install @terrace-lang/js

# PNPM (https://pnpm.io/)
$ pnpm install @terrace-lang/js

# Yarn (https://yarnpkg.com/)
$ yarn add @terrace-lang/js

Core API

LineData

// Type Definition
// Holds the parsed information from each line.
type LineData = {
  // Which character is being used for indentation. Avoids having to specify it on each parseLine call.
  indent: string;
  // How many indent characters are present in the current line before the first non-indent character.
  level: number;
  // The number of characters before the start of the line's "head" section.
  // (Normally the same as `level`)
  offsetHead: number;
  // The number of characters before the start of the line's "tail" section.
  offsetTail: number;
}

createLineData()

// Type Definition
function createLineData(indent: string = ' '): LineData

// Import Path
import { createLineData } from '@terrace-lang/js/parser'

// Usage
const lineData = createLineData(' ')
console.dir(lineData)
// { indent: ' ', level: 0, offsetHead: 0, offsetTail: 0 }
// Use the same lineData object for all calls to parseLine in the same document.

parseLine()

// Type Definition
function parseLine(lineData: LineData): LineData

// Import Path
import { createLineData, parseLine } from '@terrace-lang/js/parser'

// Usage
const lineData = createLineData(' ')
parseLine('title Example Title', lineData)
console.dir(lineData)
// { indent: ' ', level: 0, offsetHead: 0, offsetTail: 5 }

Document API

useDocument()

// Type Definition
function useDocument (reader: Reader, indent: string = ' '): Document

// Import Path
import { useDocument } from '@terrace-lang/js/document'

Document

// Type Definition
type Document = {
  next: (levelScope?: number) => Promise<boolean>
  level: () => number,
  line: (startOffset?: number) => string,
  head: () => string,
  tail: () => string,
  match: (matchHead: string) => boolean
}

Document.next()

// Type Definition
next: (levelScope?: number) => Promise<boolean>

// Import Path
import { useDocument } from '@terrace-lang/js/document'

// Usage
const { next } = useDocument(...)
while (await next()) {
  // Do something with each line.
}

Document.level()

block
  block
  block
      block

// Type Definition
level: () => number

// Usage
import { useDocument } from '@terrace-lang/js/document'
const { level } = useDocument(...)

Document.line()

root
    sub-line

// Type Definition
line: (startOffset?: number) => string

// Usage
import { useDocument } from '@terrace-lang/js/document'
const { line } = useDocument(...)

Document.head()

title An Important Document

// Type Definition
head: () => string

// Usage
import { useDocument } from '@terrace-lang/js/document'
const { head } = useDocument(...)

Document.tail()

title An Important Document

// Type Definition
tail: () => string

// Usage
import { useDocument } from '@terrace-lang/js/document'
const { tail } = useDocument(...)

Document.match()

title An Important Document

// Type Definition
match: (matchValue: string) => boolean

// Usage
import { useDocument } from '@terrace-lang/js/document'
const { match } = useDocument(...)

Reader API

Reader

// Type Definition
type Reader = () => string|null|Promise<string|null>

createStringReader()

// Type Definition
function createStringReader(source: string|string[], index: number = 0): Reader

// Import Path
import { createStringReader } from '@terrace-lang/js/readers/js-string'

import { createStringReader, useDocument } from '@terrace-lang/js'

// Create a string reader with two lines
const reader = createStringReader('title Example Title\n line2')
// Also permitted:
// const reader = createStringReader(['title Example Title', ' line 2'])

const { next, level, line } = useDocument(reader)
await next()
console.log(level(), line())
// 0 title Example Title
await next()
console.log(level(), line())
// 1 line 2

createFileReader()

// Type Definition
function createFileReader(path: string): Reader

// Import Path
import { createFileReader } from '@terrace-lang/js/readers/node-readline'

import { createFileReader, useDocument } from '@terrace-lang/js'

// Read the file ./example.tce
const { next, level, line } = useDocument(createFileReader('./example.tce'))
await next()
console.log(level(), line())
// 0 title Example Title
await next()
console.log(level(), line())
// 1 line 2

title Example Title
  line 2

createStdinReader()

// Type Definition
function createStdinReader(): Reader

// Import Path
import { createStdinReader } from '@terrace-lang/js/readers/node-readline'

import { createStdinReader, useDocument } from '@terrace-lang/js'

// Read the contents of standard input
const { next, level, line } = useDocument(createStdinReader())

while(await next()) {
  console.log(level(), line())
  // See `shell` panel above for output
}

title Example Title
  line 2

# Run main.js with the contents of example.tce piped to stdin
$ cat example.tce > node ./main.js
0 title Example Title
1 line 2

createStreamReader()

// Type Definition
function createStreamReader(): Reader

// Import Path
import { createStreamReader } from '@terrace-lang/js/readers/node-readline'

import fs from 'node:fs'
import { createStreamReader, useDocument } from '@terrace-lang/js'

// Read the file ./example.tce - equivalent to the `createFileReader` example above.
const reader = createStreamReader(fs.createReadStream('./example.tce'))
const { next, level, line } = useDocument(reader)
await next()
console.log(level(), line())
// 0 title Example Title
await next()
console.log(level(), line())
// 1 line 2

title Example Title
  line 2

Recipes

Read object properties

// Provides simple convenience functions over the core parser
// CommonJS: const { useDocument } = require('@terrace-lang/js/document')
import { useDocument } from '@terrace-lang/js/document'
// A helper for iterating over a string line-by-line
// CommonJS: const { createStringReader } = require('@terrace-lang/js/readers/js-string')
import { createStringReader } from '@terrace-lang/js/readers/js-string'

const input = `
object
  string_property An example string
  numeric_property 4
`

const output = {
  string_property: null,
  numeric_property: null
}

// useDocument returns convenience functions
const { next, level, head, tail, match } = useDocument(createStringReader(input))

// next() parses the next line in the document
while (await next()) {
  // match('object') is equivalent to head() === 'object'
  // Essentially: "If the current line starts with 'object'"
  if (match('object')) {
    const objectLevel = level()
    // When we call next with a parent level it,
    // only iterates over lines inside the parent block
    while (await next(objectLevel)) {
      // tail() returns the part of the current line after the first space
      if (match('string_property')) output.string_property = tail()
      // parseFloat() here the string tail() to a numeric float value
      if (match('numeric_property')) output.numeric_property = parseFloat(tail())
    }
  }
}

console.dir(output)
// { string_property: 'An example string', numeric_property: 4 }

// Provides simple convenience functions over the core parser
// CommonJS: const { useDocument } = require('@terrace-lang/js/document')
import { useDocument } from '@terrace-lang/js/document'
// A helper for iterating over a string line-by-line
// CommonJS: const { createStringReader } = require('@terrace-lang/js/readers/js-string')
import { createStringReader } from '@terrace-lang/js/readers/js-string'

const input = `
object
  property1 Value 1
  property2 Value 2
  random_property igazi3ii4quaC5OdoB5quohnah1beeNg
`

const output = {}

// useDocument returns convenience functions
const { next, level, head, tail, match } = useDocument(createStringReader(input))

// next() parses the next line in the document
while (await next()) {
  // match('object') is equivalent to head() === 'object'
  // Essentially: "If the current line starts with 'object'"
  if (match('object')) {
    const objectLevel = level()
    // When we call next with a parent level,
    // it only iterates over lines inside the parent block
    while (await next(objectLevel)) {
      // Skip empty lines
      if (!line()) continue
      // Add any properties to the object as strings using the
      // line head() as the key and tail() as the value
      output[head()] = tail()
    }
  }
}

console.dir(output)
// { property1: 'Value 1', property2: 'Value 2', random_property: 'igazi3ii4quaC5OdoB5quohnah1beeNg' }

Contributing