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

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