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

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