github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/docs/apis/ReadArray.md (about)

     1  # `ReadArray()` (type)
     2  
     3  > Read from a data type one array element at a time
     4  
     5  ## Description
     6  
     7  This is a function you would write when programming a Murex data-type.
     8  
     9  It's called by builtins to allow them to read data structures one array element
    10  at a time.
    11  
    12  The purpose of this function is to allow builtins to support sequential reads
    13  (where possible) and also create a standard interface for builtins, thus
    14  allowing them to be data-type agnostic.
    15  
    16  ## Usage
    17  
    18  Registering your `ReadArray()`
    19  
    20  ```go
    21  // To avoid confusion, this should only happen inside func init()
    22  stdio.RegisterReadArray(/* your type name */, /* your readArray func */)
    23  ```
    24  
    25  ## Examples
    26  
    27  Example `ReadArray()` function:
    28  
    29  ```go
    30  package string
    31  
    32  import (
    33  	"bufio"
    34  	"bytes"
    35  	"context"
    36  	"fmt"
    37  
    38  	"github.com/lmorg/murex/lang/stdio"
    39  	"github.com/lmorg/murex/lang/types"
    40  )
    41  
    42  func readArray(ctx context.Context, read stdio.Io, callback func([]byte)) error {
    43  	scanner := bufio.NewScanner(read)
    44  	for scanner.Scan() {
    45  		select {
    46  		case <-ctx.Done():
    47  			return scanner.Err()
    48  
    49  		default:
    50  			callback(bytes.TrimSpace(scanner.Bytes()))
    51  		}
    52  	}
    53  
    54  	err := scanner.Err()
    55  	if err != nil {
    56  		return fmt.Errorf("error while reading a %s array: %s", types.String, err.Error())
    57  	}
    58  
    59  	return nil
    60  }
    61  ```
    62  
    63  ## Detail
    64  
    65  If your data type is not a stream-able array, it is then recommended that
    66  you pass your array to  `lang.ArrayTemplate()` which is a handler to convert Go
    67  structures into Murex arrays. This also makes writing `ReadArray()` handlers
    68  easier since you can just pass `lang.ArrayTemplate()` your marshaller.
    69  For example:
    70  
    71  ```go
    72  package json
    73  
    74  import (
    75  	"context"
    76  
    77  	"github.com/lmorg/murex/lang"
    78  	"github.com/lmorg/murex/lang/stdio"
    79  	"github.com/lmorg/murex/utils/json"
    80  )
    81  
    82  func readArray(ctx context.Context, read stdio.Io, callback func([]byte)) error {
    83  	// Create a marshaller function to pass to ArrayTemplate
    84  	marshaller := func(v interface{}) ([]byte, error) {
    85  		return json.Marshal(v, read.IsTTY())
    86  	}
    87  
    88  	return lang.ArrayTemplate(ctx, marshaller, json.Unmarshal, read, callback)
    89  }
    90  ```
    91  
    92  The downside of this is that you're then unmarshalling the entire file, which
    93  could be slow on large files and also breaks the streaming nature of UNIX
    94  pipelines.
    95  
    96  ## Parameters
    97  
    98  1. `stdio.Io`: stream to read from (eg STDIN)
    99  2. `func([]byte)`: callback function. Each callback will be a []byte slice containing an array element
   100  
   101  ## See Also
   102  
   103  * [apis/`ReadIndex()` (type)](../apis/ReadIndex.md):
   104    Data type handler for the index, `[`, builtin
   105  * [apis/`ReadMap()` (type)](../apis/ReadMap.md):
   106    Treat data type as a key/value structure and read its contents
   107  * [apis/`ReadNotIndex()` (type)](../apis/ReadNotIndex.md):
   108    Data type handler for the bang-prefixed index, `![`, builtin
   109  * [apis/`WriteArray()` (type)](../apis/WriteArray.md):
   110    Write a data type, one array element at a time
   111  * [apis/`lang.ArrayTemplate()` (template API)](../apis/lang.ArrayTemplate.md):
   112    Unmarshals a data type into a Go struct and returns the results as an array
   113  * [apis/`lang.ArrayWithTypeTemplate()` (template API)](../apis/lang.ArrayWithTypeTemplate.md):
   114    Unmarshals a data type into a Go struct and returns the results as an array with data type included
   115  
   116  <hr/>
   117  
   118  This document was generated from [lang/stdio/interface_doc.yaml](https://github.com/lmorg/murex/blob/master/lang/stdio/interface_doc.yaml).