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

     1  # `ReadNotIndex()` (type)
     2  
     3  > Data type handler for the bang-prefixed index, `![`, builtin
     4  
     5  ## Description
     6  
     7  This is a function you would write when programming a Murex data-type.
     8  
     9  It's called by the index, `![`, builtin.
    10  
    11  The purpose of this function is to allow builtins to support sequential reads
    12  (where possible) and also create a standard interface for `![` (index), thus
    13  allowing it to be data-type agnostic.
    14  
    15  ## Usage
    16  
    17  Registering your `ReadNotIndex()`
    18  
    19  ```go
    20  // To avoid data races, this should only happen inside func init()
    21  lang.ReadNotIndexes[ /* your type name */ ] = /* your readIndex func */
    22  ```
    23  
    24  ## Examples
    25  
    26  Example `ReadIndex()` function (the code structure is the same for `ReadIndex`
    27  and `ReadNotIndex`):
    28  
    29  ```go
    30  package json
    31  
    32  import (
    33  	"github.com/lmorg/murex/lang"
    34  	"github.com/lmorg/murex/utils/json"
    35  )
    36  
    37  func index(p *lang.Process, params []string) error {
    38  	var jInterface interface{}
    39  
    40  	b, err := p.Stdin.ReadAll()
    41  	if err != nil {
    42  		return err
    43  	}
    44  
    45  	err = json.Unmarshal(b, &jInterface)
    46  	if err != nil {
    47  		return err
    48  	}
    49  
    50  	marshaller := func(iface interface{}) ([]byte, error) {
    51  		return json.Marshal(iface, p.Stdout.IsTTY())
    52  	}
    53  
    54  	return lang.IndexTemplateObject(p, params, &jInterface, marshaller)
    55  }
    56  ```
    57  
    58  ## Detail
    59  
    60  While there is support for a dedicated `ReadNotIndex()` for instances of `![`,
    61  the template APIs `lang.IndexTemplateObject` and `lang.IndexTemplateTable` are
    62  both agnostic to the bang prefix.
    63  
    64  ## Parameters
    65  
    66  1. `*lang.Process`: Process's runtime state. Typically expressed as the variable `p` 
    67  2. `[]string`: slice of parameters used in `![` 
    68  
    69  ## See Also
    70  
    71  * [user-guide/Bang Prefix](../user-guide/bang-prefix.md):
    72    Bang prefixing to reverse default actions
    73  * [apis/`ReadArray()` (type)](../apis/ReadArray.md):
    74    Read from a data type one array element at a time
    75  * [apis/`ReadArrayWithType()` (type)](../apis/ReadArrayWithType.md):
    76    Read from a data type one array element at a time and return the elements contents and data type
    77  * [apis/`ReadIndex()` (type)](../apis/ReadIndex.md):
    78    Data type handler for the index, `[`, builtin
    79  * [apis/`WriteArray()` (type)](../apis/WriteArray.md):
    80    Write a data type, one array element at a time
    81  * [parser/`[[ Element ]]`](../parser/element.md):
    82    Outputs an element from a nested structure
    83  * [apis/`lang.IndexTemplateObject()` (template API)](../apis/lang.IndexTemplateObject.md):
    84    Returns element(s) from a data structure
    85  * [apis/`lang.IndexTemplateTable()` (template API)](../apis/lang.IndexTemplateTable.md):
    86    Returns element(s) from a table
    87  * [parser/index](../parser/item-index.md):
    88    Outputs an element from an array, map or table
    89  
    90  <hr/>
    91  
    92  This document was generated from [lang/stdio/interface_doc.yaml](https://github.com/lmorg/murex/blob/master/lang/stdio/interface_doc.yaml).