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

     1  # `lang.MarshalData()` (system API)
     2  
     3  > Converts structured memory into a Murex data-type (eg for stdio)
     4  
     5  ## Description
     6  
     7  
     8  
     9  ## Usage
    10  
    11  ```go
    12  b, err := lang.MarshalData(p, dataType, data)
    13  ```
    14  
    15  ## Examples
    16  
    17  ```go
    18  func exampleCommand(p *lang.Process) error {
    19      data := map[string]string {
    20          "foo": "hello foo",
    21          "bar": "hello bar",
    22      }
    23  
    24      dataType := "json"
    25  
    26      b, err := lang.MarshalData(p, dataType, data)
    27      if err != nil {
    28          return err
    29      }
    30  
    31      _, err := p.Stdout.Write(b)
    32      return err
    33  }
    34  ```
    35  
    36  ## Detail
    37  
    38  Go source file:
    39  
    40  ```go
    41  package lang
    42  
    43  import (
    44  	"errors"
    45  )
    46  
    47  // MarshalData is a global marshaller which should be called from within murex
    48  // builtin commands (etc).
    49  // See docs/apis/marshaldata.md for more details
    50  func MarshalData(p *Process, dataType string, data interface{}) (b []byte, err error) {
    51  	// This is one of the very few maps in Murex which isn't hidden behind a sync
    52  	// lock of one description or other. The rational is that even mutexes can
    53  	// add a noticeable overhead on the performance of tight loops and I expect
    54  	// this function to be called _a lot_ while also only needing to be written
    55  	// to via code residing in within builtin types init() function (ie while
    56  	// murex is effectively single threaded). So there shouldn't be any data-
    57  	// races -- PROVIDING developers strictly follow the pattern of only writing
    58  	// to this map within init() func's.
    59  	if Marshallers[dataType] == nil {
    60  		return nil, errors.New("I don't know how to marshal `" + dataType + "`.")
    61  	}
    62  
    63  	b, err = Marshallers[dataType](p, data)
    64  	if err != nil {
    65  		return nil, errors.New("[" + dataType + " marshaller] " + err.Error())
    66  	}
    67  
    68  	return
    69  }
    70  ```
    71  
    72  ## Parameters
    73  
    74  1. `*lang.Process`: Process's runtime state. Typically expressed as the variable `p` 
    75  2. `string`: Murex data type
    76  3. `interface{}`: data you wish to marshal
    77  
    78  ## See Also
    79  
    80  * [apis/`Marshal()` (type)](../apis/Marshal.md):
    81    Converts structured memory into a structured file format (eg for stdio)
    82  * [apis/`Unmarshal()` (type)](../apis/Unmarshal.md):
    83    Converts a structured file format into structured memory
    84  * [apis/`lang.UnmarshalData()` (system API)](../apis/lang.UnmarshalData.md):
    85    Converts a Murex data-type into structured memory
    86  
    87  <hr/>
    88  
    89  This document was generated from [lang/define_marshal_doc.yaml](https://github.com/lmorg/murex/blob/master/lang/define_marshal_doc.yaml).