rs

rs

Rendering Suffix Support for yaml

Usage

1. Embed rs.BaseField as the very first field in your struct

   type MyStruct struct {
     rs.BaseField // MUST be the first one
   }
   

2. Write yaml doc with rendering suffix (say my-renderer)

   foo@my-renderer: bar
   

3. Implement the my-renderer to comply interface rs.RenderingHandler requirments (say MyRendererImpl)

4. Unmarshal your yaml data using go-yaml to MyStruct object (say myStructObj)

5. Resolve your yaml data by calling myStructObj.ResolveFields(&MyRendererImpl{}, -1)

NOTE: You can find more source code usage examples in arhat-dev/dukkha

Known Limitations

• Inline field marshaling issue, see go-yaml/yaml#362

  • Cause: rs.BaseField implemented yaml.UnmarshalYAML

  Sample Code:

  type A struct{
    rs.BaseField
  }
  
  type B struct{
    rs.BaseField
  
    // UseA will not be marshaled
    UseA A `yaml:",inline"`
  }
  

• Built-in map data structure with rendering suffix applied to map key are not supported

  Sample Code:

  type Bar struct {
    // ... any kind of fields
  }
  
  type Foo struct {
    rs.BaseField
  
    SomeBar map[string]Bar `yaml:"some_bar"`
  }
  

  some_bar:
    # this will not be resolved
    some_key_for_bar@my-renderer: my-renderer-value
  

  Workaround: Define your own struct, embed rs.BaseField as the first field and make the map a field with rs:"other" tag

  type BarMap struct{
    rs.BaseField
  
    Data map[string]Bar `rs:"other"`
  }
  
  type Foo struct {
    rs.BaseField
  
    SomeBar BarMap `yaml:"some_bar"`
  }
  

LICENSE

Copyright 2021 The arhat.dev Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.