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

     1  # `ReadMap()` (type)
     2  
     3  > Treat data type as a key/value structure and read its contents
     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 key/value
    10  pair 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 `ReadMap()`
    19  
    20  ```go
    21  // To avoid confusion, this should only happen inside func init()
    22  stdio.RegisterReadMap(/* your type name */, /* your readMap func */)
    23  ```
    24  
    25  ## Examples
    26  
    27  Example `ReadMap()` function:
    28  
    29  ```go
    30  package json
    31  
    32  import (
    33  	"github.com/lmorg/murex/config"
    34  	"github.com/lmorg/murex/lang"
    35  	"github.com/lmorg/murex/lang/stdio"
    36  	"github.com/lmorg/murex/lang/types"
    37  	"github.com/lmorg/murex/utils/json"
    38  )
    39  
    40  func readMap(read stdio.Io, _ *config.Config, callback func(*stdio.Map)) error {
    41  	// Create a marshaller function to pass to ArrayWithTypeTemplate
    42  	marshaller := func(v interface{}) ([]byte, error) {
    43  		return json.Marshal(v, read.IsTTY())
    44  	}
    45  
    46  	return lang.MapTemplate(types.Json, marshaller, json.Unmarshal, read, callback)
    47  }
    48  ```
    49  
    50  ## Detail
    51  
    52  There isn't (yet) a template read function for types to call. However that
    53  might follow in a future release of Murex.
    54  
    55  ## Parameters
    56  
    57  1. `stdio.Io`: stream to read from (eg STDIN)
    58  2. `*config.Config`: scoped config (eg your data type might have configurable parsing rules)
    59  3. `func(key, value string, last bool)`: callback function: key and value of map plus boolean which is true if last element in row (eg reading from tables rather than key/values)
    60  
    61  ## See Also
    62  
    63  * [apis/`ReadArray()` (type)](../apis/ReadArray.md):
    64    Read from a data type one array element at a time
    65  * [apis/`ReadArrayWithType()` (type)](../apis/ReadArrayWithType.md):
    66    Read from a data type one array element at a time and return the elements contents and data type
    67  * [apis/`ReadIndex()` (type)](../apis/ReadIndex.md):
    68    Data type handler for the index, `[`, builtin
    69  * [apis/`ReadNotIndex()` (type)](../apis/ReadNotIndex.md):
    70    Data type handler for the bang-prefixed index, `![`, builtin
    71  * [apis/`WriteArray()` (type)](../apis/WriteArray.md):
    72    Write a data type, one array element at a time
    73  
    74  <hr/>
    75  
    76  This document was generated from [lang/stdio/interface_doc.yaml](https://github.com/lmorg/murex/blob/master/lang/stdio/interface_doc.yaml).