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

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