Terrace/packages/js/docs/reader-api.inc.tce

Heading 2 Reader API
  class mt-12
Markdown
  The [Document API](#document-api) requires `Reader` functions to iterate through lines
  in a document. A reader function simply returns a string (or a promise resolving to a string).
  Each time it is called, it returns the next line from whichever source it is pulling them.

  Terrace provides a few built-in readers, but you are welcome to build your own instead.

Heading 3 Reader
  class mb-4 mt-12
Markdown
  Any function (async included) that returns the next line in a document when called and null when the end of the document has been reached.

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

Heading 3 createStringReader()
  class mb-4 mt-12
Markdown
  | Parameter      | Type                  | Description
  | -------------- | --------------------- | -----------------------------------------------------------------------
  | source         | string\|string[]      | The lines to iterate over, as a multiline string or an array of line strings.
  | index          | number                | Optional - which line to start from.
  | **@returns**   | [Reader](#reader)     | A reader function that returns each line from the source document when called sequentially.

  Get a simple [Reader](#reader) function that always returns the next line from a mutliline string or an array of line strings.
CodeBlock typescript
  // Type Definition
  function createStringReader(source: string|string[], index: number = 0): Reader

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

Markdown
  **Usage**
CodeBlock typescript
  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


Heading 3 createFileReader()
  class mb-4 mt-12
Markdown
  | Parameter      | Type                  | Description
  | -------------- | --------------------- | -----------------------------------------------------------------------
  | path         | string                  | A path to the file to read.
  | **@returns**   | [Reader](#reader)     | A reader function that returns each line from the file when called sequentially

  **Note:** Only available in Node.js environments.<br/>
  Get a [Reader](#reader) function that returns the next line from the specified file when called sequentially.


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

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

Markdown
  **Usage**
CodeExample
  summary-class mb-[300px]
  pre-class max-h-[300px]
  javascript main.js
    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

  terrace example.tce
    title Example Title
      line 2

Heading 3 createStdinReader()
  class mb-4 mt-12
Markdown
  | Parameter      | Type                  | Description
  | -------------- | --------------------- | -----------------------------------------------------------------------
  | **@returns**   | [Reader](#reader)     | A reader function that returns each line from `stdin` when called sequentially

  **Note:** Only available in Node.js environments.<br/>
  Get a [Reader](#reader) function that returns the next line from standard input when called sequentially. Does not block stdin to wait for input. If no input is present it returns null immediately.
CodeBlock typescript
  // Type Definition
  function createStdinReader(): Reader

  // Import Path
  import { createStdinReader } from '@terrace-lang/js/readers/node-readline'
Markdown
  **Usage**
CodeExample
  summary-class mb-[250px]
  pre-class max-h-[250px]
  javascript main.js
    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
    }

  terrace example.tce
    title Example Title
      line 2

  sh
    # 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

Heading 3 createStreamReader()
  class mb-4 mt-12
Markdown
  | Parameter      | Type                  | Description
  | -------------- | --------------------- | -----------------------------------------------------------------------
  | stream         | NodeJS.ReadStream|fs.ReadStream | A ReadStream compatible with Node.js `readline` APIs
  | **@returns**   | [Reader](#reader)     | A reader function that returns each line from `stdin` when called sequentially

  **Note:** Only available in Node.js environments.<br/>
  Get a [Reader](#reader) function that always returns the next line from a passed read stream when called sequentially.
CodeBlock typescript
  // Type Definition
  function createStreamReader(): Reader

  // Import Path
  import { createStreamReader } from '@terrace-lang/js/readers/node-readline'
Markdown
  **Usage**
CodeExample
  summary-class mb-[320px]
  pre-class max-h-[320px]
  javascript main.js
    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

  terrace example.tce
    title Example Title
      line 2