github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/lang/define_unmarshal_doc.yaml (about)

     1  - DocumentID: Unmarshal
     2    Title: >-
     3      `Unmarshal()` (type)
     4    CategoryID: apis
     5    Summary: >-
     6      Converts a structured file format into structured memory
     7    Description: |-
     8      This is a function you would write when programming a Murex data-type.
     9      The unmarshal function takes in a byte slice and returns a Go (golang)
    10      `type` or `struct` or an error.
    11  
    12      This unmarshaller is then registered to Murex inside an `init()` function
    13      and Murex builtins can use that unmarshaller via the `UnmarshalData()`
    14      API.
    15    Usage: |-
    16      Registering `Unmarshal()` (for writing builtin data-types)
    17      
    18      ```go
    19      // To avoid data races, this should only happen inside func init()
    20      lang.Unmarshallers[ /* your type name */ ] = /* your readIndex func */
    21      ```
    22  
    23      Using an existing unmarshaller (eg inside a builtin command)
    24  
    25      ```go
    26      // See documentation on lang.UnmarshalData for more details
    27      v, err := lang.UnmarshalData(p *lang.Process, dataType string)
    28      ```
    29    Examples: |-
    30      Defining a marshaller for a murex data-type
    31  
    32      ```go
    33      {{ include "builtins/types/example/unmarshal.go" }}
    34      ```
    35    Detail: |-
    36    Parameters:
    37    - "`*lang.Process`: Process's runtime state. Typically expressed as the variable `p` "
    38    Related:
    39    - lang.MarshalData
    40    - lang.UnmarshalData
    41    - Marshal
    42  
    43  
    44  - DocumentID: lang.UnmarshalData
    45    Title: >-
    46      `lang.UnmarshalData()` (system API)
    47    CategoryID: apis
    48    Summary: >-
    49      Converts a Murex data-type into structured memory
    50    Description: |-
    51    Usage: |-
    52      ```go
    53      data, err := lang.UnmarshalData(p, dataType)
    54      ```
    55    Examples: |-
    56      ```go
    57      func exampleCommand(p *lang.Process) error {
    58          data := string `{ "foo": "hello foo", "bar": "hello bar" }`
    59  
    60          dataType := "json"
    61  
    62          v, err := lang.UnmarshalData(p, dataType)
    63          if err != nil {
    64              return err
    65          }
    66  
    67          s := fmt.Sprint(v)
    68          _, err := p.Stdout.Write([]byte(s))
    69          return err
    70      }
    71      ```
    72    Detail: |-
    73      Go source file:
    74      
    75      ```go
    76      {{ include "lang/define_unmarshal.go" }}
    77      ```
    78    Parameters:
    79    - "`*lang.Process`: Process's runtime state. Typically expressed as the variable `p` "
    80    - "`string`: Murex data type" 
    81    Related:
    82    - Marshal
    83    - lang.MarshalData
    84    - Unmarshal