murex Shell Docs

API Reference: ReadArray() (type)

Read from a data type one array element at a time

Description

This is a function you would write when programming a murex data-type.

It's called by builtins to allow them to read data structures one array element at a time.

The purpose of this function is to allow builtins to support sequential reads (where possible) and also create a standard interface for builtins, thus allowing them to be data-type agnostic.

Usage

Registering your ReadArray()

// To avoid confusion, this should only happen inside func init()
stdio.RegisterReadArray(/* your type name */, /* your readArray func */)

Examples

Example ReadArray() function:

package string

import (
    "bufio"
    "bytes"

    "github.com/lmorg/murex/lang/stdio"
)

func readArray(read stdio.Io, callback func([]byte)) error {
    scanner := bufio.NewScanner(read)
    for scanner.Scan() {
        callback(bytes.TrimSpace(scanner.Bytes()))
    }

    return scanner.Err()
}

Detail

If your data type is not a stream-able array, it is then recommended that you pass your array to lang.ArrayTemplate() which is a handler to convert Go structures into murex arrays. This also makes writing ReadArray() handlers easier since you can just pass lang.ArrayTemplate() your marshaller. For example:

package json

import (
    "github.com/lmorg/murex/lang"
    "github.com/lmorg/murex/lang/stdio"
    "github.com/lmorg/murex/utils/json"
)

func readArray(read stdio.Io, callback func([]byte)) error {
    // Create a marshaller function to pass to ArrayTemplate
    marshaller := func(v interface{}) ([]byte, error) {
        return json.Marshal(v, read.IsTTY())
    }

    return lang.ArrayTemplate(marshaller, json.Unmarshal, read, callback)
}

The downside of this is that you're then unmarshalling the entire file, which could be slow on large files and also breaks the streaming nature of UNIX pipelines.

Parameters

  1. stdio.Io: stream to read from (eg STDIN)
  2. func([]byte): callback function. Each callback will be a []byte slice containing an array element

See Also

This site's content is rebuilt automatically from murex's source code after each merge to the master branch. Downloadable murex binaries are also built with the website.

Last built on Fri Sep 10 15:05:25 UTC 2021 against commit 437c274437c274fded54d82e99d70ea7d2917f332c095dd.

Current version is 2.2.1200 BETA which has been verified against tests.