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

     1  # `WriteArray()` (type)
     2  
     3  > Write 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 write data structures one array
    10  element at a time.
    11  
    12  The purpose of this function is to allow builtins to support sequential writes
    13  (where possible) and also create a standard interface for builtins, thus
    14  allowing them to be data-type agnostic.
    15  
    16  ### A Collection of Functions
    17  
    18  `WriteArray()` should return a `struct` that satisfies the following
    19  `interface{}`:
    20  
    21  ```go
    22  package stdio
    23  
    24  // ArrayWriter is a simple interface types can adopt for buffered writes of formatted arrays in structured types (eg JSON)
    25  type ArrayWriter interface {
    26  	Write([]byte) error
    27  	WriteString(string) error
    28  	Close() error
    29  }
    30  ```
    31  
    32  ## Usage
    33  
    34  Registering your `WriteArray()`
    35  
    36  ```go
    37  // To avoid confusion, this should only happen inside func init()
    38  stdio.RegisterWriteArray(/* your type name */, /* your writeArray func */)
    39  ```
    40  
    41  ## Examples
    42  
    43  Example `WriteArray()` function:
    44  
    45  ```go
    46  package string
    47  
    48  import (
    49  	"github.com/lmorg/murex/lang/stdio"
    50  )
    51  
    52  type arrayWriter struct {
    53  	writer stdio.Io
    54  }
    55  
    56  func newArrayWriter(writer stdio.Io) (stdio.ArrayWriter, error) {
    57  	w := &arrayWriter{writer: writer}
    58  	return w, nil
    59  }
    60  
    61  func (w *arrayWriter) Write(b []byte) error {
    62  	_, err := w.writer.Writeln(b)
    63  	return err
    64  }
    65  
    66  func (w *arrayWriter) WriteString(s string) error {
    67  	_, err := w.writer.Writeln([]byte(s))
    68  	return err
    69  }
    70  
    71  func (w *arrayWriter) Close() error { return nil }
    72  ```
    73  
    74  ## Detail
    75  
    76  Since not all data types will be stream-able (for example `json`), some types
    77  may need to cache the array and then to write it once the array writer has been
    78  closed.
    79  
    80  ```go
    81  package json
    82  
    83  import (
    84  	"github.com/lmorg/murex/lang/stdio"
    85  	"github.com/lmorg/murex/utils/json"
    86  )
    87  
    88  type arrayWriter struct {
    89  	array  []string
    90  	writer stdio.Io
    91  }
    92  
    93  func newArrayWriter(writer stdio.Io) (stdio.ArrayWriter, error) {
    94  	w := &arrayWriter{writer: writer}
    95  	return w, nil
    96  }
    97  
    98  func (w *arrayWriter) Write(b []byte) error {
    99  	w.array = append(w.array, string(b))
   100  	return nil
   101  }
   102  
   103  func (w *arrayWriter) WriteString(s string) error {
   104  	w.array = append(w.array, s)
   105  	return nil
   106  }
   107  
   108  func (w *arrayWriter) Close() error {
   109  	b, err := json.Marshal(w.array, w.writer.IsTTY())
   110  	if err != nil {
   111  		return err
   112  	}
   113  
   114  	_, err = w.writer.Write(b)
   115  	return err
   116  }
   117  ```
   118  
   119  ## See Also
   120  
   121  * [apis/`ReadArray()` (type)](../apis/ReadArray.md):
   122    Read from a data type one array element at a time
   123  * [apis/`ReadArrayWithType()` (type)](../apis/ReadArrayWithType.md):
   124    Read from a data type one array element at a time and return the elements contents and data type
   125  * [apis/`ReadIndex()` (type)](../apis/ReadIndex.md):
   126    Data type handler for the index, `[`, builtin
   127  * [apis/`ReadMap()` (type)](../apis/ReadMap.md):
   128    Treat data type as a key/value structure and read its contents
   129  * [apis/`ReadNotIndex()` (type)](../apis/ReadNotIndex.md):
   130    Data type handler for the bang-prefixed index, `![`, builtin
   131  
   132  <hr/>
   133  
   134  This document was generated from [lang/stdio/interface_doc.yaml](https://github.com/lmorg/murex/blob/master/lang/stdio/interface_doc.yaml).