structology

package module
v0.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 30, 2024 License: Apache-2.0 Imports: 9 Imported by: 19

README

structology - State tracker for golang struct

GoReportCard GoDoc

This library is compatible with Go 1.17+

Please refer to CHANGELOG.md if you encounter breaking changes.

Motivation

This project defines struct field set marker to distinctively identify input state, specifically for 'empty', 'nil', 'has been set' state. This is critical for update/patch operation with large struct where only small subset if defined, with presence marker allowing you handling user input effectively, ensuring data integrity, and improving the security of applications

Initially we have a few project holding marker abstraction to finally move it to this project.

This project also implement a state that wraps arbitrary go struct, and provide selectors to dynamically access/mutate any nested/addressable values, if set marker is defined all set operation also would flag respective marker field

Usage

Set Marker
type (
    HasEntity struct {
	    Id     bool
        Name   bool
        Active bool
	}
     Entity struct {
        Id     int
        Name   string
        Active bool
        Has    *EntityHas `setMarker:"true"`
    }
)

    var entity *Entity

	....// load entity and set all present fields with marker.Set(...)

	
    marker, err := NewMarker()
    if err != nil {
        log.Fatal(err)
    }
    isIdSet := marker.IsSet(marker.Index("Id"))
	fmt.Printf("is ID set : %v\n", isIdSet)
	
}
State with SetMarker
package bar

import (
	"fmt"
	"reflect"
	"github.com/viant/structology"
	"encoding/json"
)

type FooHas struct {
	Id   bool
	Name bool
}

type DummyHas struct {
	Id  bool
	Foo bool
}

type Foo struct {
	Id   int
	Name string
	Has  *FooHas `setMarker:"true"`
}

type Dummy struct {
	Id  int
	Foo *Foo
	Has *DummyHas `setMarker:"true"`
}

func ShowStateUsage() {
	
	dummy := &Dummy{Foo: &Foo{}}
	valueType := reflect.TypeOf(dummy)
	stateType := structology.NewStateType(valueType)
	state := stateType.WithValue(dummy)
	
	hasFoo, _ := state.Bool("Has.Foo")
	fmt.Printf("initial foo has marker: %v\n", 	hasFoo)
	hasFooName, _ := 	state.Bool("Foo.Has.Name") 
	fmt.Printf("initial foo has marker: %v\n", 	hasFooName)
	
	state.SetString("Foo.Name", "Bob Dummy")
	data, _ := json.Marshal(dummy)
	fmt.Printf("dummy: %s\n", data)

	hasFoo, _ = state.Bool("Has.Foo")
	fmt.Printf("foo has marker: %v\n", 	hasFoo)
	hasFooName, _ = 	state.Bool("Foo.Has.Name")
	fmt.Printf("foo has marker: %v\n", 	hasFooName)
	
}

Check unit test for more advanced usage.

Contributing to structology

structology is an open source project and contributors are welcome!

See TODO list

License

The source code is made available under the terms of the Apache License, Version 2, as stated in the file LICENSE.

Individual files may be made available under their own specific license, all compatible with Apache License, Version 2. Please see individual files for details.

Credits and Acknowledgements

Library Author: Adrian Witas

Documentation

Overview

Package structology provides utilities for manage application state with go structs

Index

Constants

View Source 
const (
	//SetMarkerTag defines set marker tag
	SetMarkerTag = "setMarker"
)

Variables

This section is empty.

Functions

func GenMarkerFields 

func GenMarkerFields(t reflect.Type) []reflect.StructField

GenMarkerFields generate marker struct fields

func HasSetMarker added in v0.3.0 

func HasSetMarker(t reflect.Type) bool

HasSetMarker returns true if struct has set marker

func IsSetMarker 

func IsSetMarker(tag reflect.StructTag) bool

func NewSelectors added in v0.3.0 

func NewSelectors(owner reflect.Type, opts ...SelectorOption) (Selectors, *Marker)

NewSelectors creates a selectors for supplied owner types

func ParseTime added in v0.4.3 

func ParseTime(layout, input string) (time.Time, error)

Types

type Marker 

type Marker struct {
	// contains filtered or unexported fields
}

Marker field set marker

func NewMarker 

func NewMarker(t reflect.Type, opts ...Option) (*Marker, error)

NewMarker returns new struct field set marker

func (*Marker) CanUseHolder 

func (p *Marker) CanUseHolder(ptr unsafe.Pointer) bool

func (*Marker) EnsureHolder added in v0.3.0 

func (p *Marker) EnsureHolder(ptr unsafe.Pointer)

func (*Marker) Index 

func (p *Marker) Index(name string) int

Index returns mapped field index or -1

func (*Marker) IsFieldSet added in v0.4.0 

func (p *Marker) IsFieldSet(ptr unsafe.Pointer, name string) bool

IsFieldSet returns true if filed has been set

func (*Marker) IsSet 

func (p *Marker) IsSet(ptr unsafe.Pointer, index int) bool

IsSet returns true if field has been set

func (*Marker) Set 

func (p *Marker) Set(ptr unsafe.Pointer, index int, flag bool) error

Set sets field marker

func (*Marker) SetAll 

func (p *Marker) SetAll(ptr unsafe.Pointer, flag bool) error

SetAll sets all marker field with supplied flag

func (*Marker) Type added in v0.4.0 

func (p *Marker) Type() reflect.Type

Type returns marker reflect type

type Option 

type Option func(m *Marker)

Option marker option

func WithIndex 

func WithIndex(index map[string]int) Option

WithIndex filed name to index mapping

func WithNoStrict added in v0.2.0 

func WithNoStrict(flag bool) Option

WithNoStrict create no strict option

type Options 

type Options []Option

Options represents marker option

func (Options) Apply 

func (o Options) Apply(m *Marker)

Apply applies options

type PathOption added in v0.3.0 

type PathOption func(o *pathOptions)

func WithPathIndex added in v0.3.0 

func WithPathIndex(indexes ...int) PathOption

type Selector added in v0.3.0 

type Selector struct {
	Selectors
	// contains filtered or unexported fields
}

Selector represents struct path selector

func (*Selector) Bool added in v0.3.0 

func (s *Selector) Bool(ptr unsafe.Pointer, opts ...PathOption) bool

func (*Selector) Float32 added in v0.3.0 

func (s *Selector) Float32(ptr unsafe.Pointer, opts ...PathOption) float32

func (*Selector) Float64 added in v0.3.0 

func (s *Selector) Float64(ptr unsafe.Pointer, opts ...PathOption) float64

func (*Selector) Has added in v0.4.0 

func (s *Selector) Has(ptr unsafe.Pointer, opts ...PathOption) bool

func (*Selector) Int added in v0.3.0 

func (s *Selector) Int(ptr unsafe.Pointer, opts ...PathOption) int

func (*Selector) IsAnonymous added in v0.4.3 

func (s *Selector) IsAnonymous() bool

func (*Selector) Name added in v0.4.3 

func (s *Selector) Name() string

Name returns selector leaf name

func (*Selector) Path added in v0.4.3 

func (s *Selector) Path() string

func (*Selector) Set added in v0.3.0 

func (s *Selector) Set(ptr unsafe.Pointer, value interface{}, opts ...PathOption) error

Set sets selector value

func (*Selector) SetBool added in v0.3.0 

func (s *Selector) SetBool(ptr unsafe.Pointer, value bool, opts ...PathOption)

SetBool sets selector bool value

func (*Selector) SetFloat32 added in v0.3.0 

func (s *Selector) SetFloat32(ptr unsafe.Pointer, value float32, opts ...PathOption)

SetFloat32 sets selector float32 value

func (*Selector) SetFloat64 added in v0.3.0 

func (s *Selector) SetFloat64(ptr unsafe.Pointer, value float64, opts ...PathOption)

SetFloat64 sets selector float64 value

func (*Selector) SetInt added in v0.3.0 

func (s *Selector) SetInt(ptr unsafe.Pointer, value int, opts ...PathOption)

SetInt sets selector int value

func (*Selector) SetString added in v0.3.0 

func (s *Selector) SetString(ptr unsafe.Pointer, value string, opts ...PathOption)

SetString sets selector string value

func (*Selector) SetValue added in v0.3.0 

func (s *Selector) SetValue(ptr unsafe.Pointer, value interface{}, opts ...PathOption) (err error)

SetValue sets selector value

func (*Selector) String added in v0.3.0 

func (s *Selector) String(ptr unsafe.Pointer, opts ...PathOption) string

func (*Selector) Tag added in v0.4.3 

func (s *Selector) Tag() reflect.StructTag

Tag returns selector leaf struct tag

func (*Selector) Type added in v0.3.0 

func (s *Selector) Type() reflect.Type

Type returns selector result type

func (*Selector) Value added in v0.3.0 

func (s *Selector) Value(ptr unsafe.Pointer, opts ...PathOption) interface{}

Value returns selector value

func (*Selector) Values added in v0.4.0 

func (s *Selector) Values(ptr unsafe.Pointer, opts ...PathOption) []interface{}

Value returns selector value

type SelectorOption added in v0.3.0 

type SelectorOption func(o *selectorOptions)

SelectorOption represents selector option

func WithCustomizedNames added in v0.3.0 

func WithCustomizedNames(fn func(name string, tag reflect.StructTag) []string) SelectorOption

WithCustomizedNames returns selector option with customized names use by selector indexer

func WithMarkerOption added in v0.3.0 

func WithMarkerOption(opt Option) SelectorOption

WithMarkerOption returns selector option with marker option

type Selectors added in v0.3.0 

type Selectors struct {
	Map   map[string]int
	Items []*Selector
	Root  []*Selector
}

Selectors indexed selectors

func (*Selectors) Add added in v0.4.3 

func (s *Selectors) Add(key string, selector *Selector)

func (*Selectors) Each added in v0.4.3 

func (s *Selectors) Each(cb func(key string, selector *Selector))

func (Selectors) Lookup added in v0.4.0 

func (s Selectors) Lookup(name string) *Selector

type Setter added in v0.6.0 

type Setter func(src interface{}, field *xunsafe.Field, holder unsafe.Pointer, opts ...SetterOption) error

func LookupSetter added in v0.6.0 

func LookupSetter(src reflect.Type, dest reflect.Type) Setter

LookupSetter TODO add conversion []interface to specific primitive slcies

type SetterOption added in v0.4.3 

type SetterOption func(o *setterOptions)

func WithTimeLayout added in v0.4.3 

func WithTimeLayout(timeLayout string) SetterOption

type State added in v0.3.0 

type State struct {
	// contains filtered or unexported fields
}

State represents a state

func (*State) Bool added in v0.3.0 

func (s *State) Bool(aPath string, pathOptions ...PathOption) (bool, error)

Bool returns a value for supplied path

func (*State) EnsureMarker added in v0.4.3 

func (s *State) EnsureMarker()

func (*State) Float64 added in v0.3.0 

func (s *State) Float64(aPath string, pathOptions ...PathOption) (float64, error)

func (*State) HasMarker added in v0.4.0 

func (s *State) HasMarker() bool

func (*State) MarkerHolder added in v0.4.0 

func (s *State) MarkerHolder() interface{}

func (*State) MergeFrom added in v0.6.0 

func (s *State) MergeFrom(from *State) error

MergeFrom merge stage with from state

func (*State) Pointer added in v0.3.0 

func (s *State) Pointer() unsafe.Pointer

Pointer returns state actual value pointer

func (*State) Selector added in v0.3.0 

func (s *State) Selector(aPath string) (*Selector, error)

Selector returns a state selector for supplied path

func (*State) SetBool added in v0.3.0 

func (s *State) SetBool(aPath string, value bool, pathOptions ...PathOption) error

SetBool set bool for supplied state path

func (*State) SetFloat32 added in v0.3.0 

func (s *State) SetFloat32(aPath string, value float32, pathOptions ...PathOption) error

func (*State) SetFloat64 added in v0.3.0 

func (s *State) SetFloat64(aPath string, value float64, pathOptions ...PathOption) error

SetFloat64 set float for supplied state path

func (*State) SetInt added in v0.3.0 

func (s *State) SetInt(aPath string, value int, pathOptions ...PathOption) error

SetInt set int for supplied path

func (*State) SetPrimitive added in v0.4.0 

func (s *State) SetPrimitive(aPath string, value interface{}, pathOptions ...PathOption) error

SetPrimitive sets primitive value

func (*State) SetString added in v0.3.0 

func (s *State) SetString(aPath string, value string, pathOptions ...PathOption) error

SetString set string for supplied state path

func (*State) SetValue added in v0.3.0 

func (s *State) SetValue(aPath string, value interface{}, pathOptions ...PathOption) error

SetValue set state value

func (*State) State added in v0.4.0 

func (s *State) State() interface{}

State return state value

func (*State) StatePtr added in v0.4.3 

func (s *State) StatePtr() interface{}

StatePtr return state value

func (*State) String added in v0.3.0 

func (s *State) String(aPath string, pathOptions ...PathOption) (string, error)

Bool returns a value for supplied path

func (*State) Sync added in v0.4.3 

func (s *State) Sync()

Sync syncs value ptr ot value if out of sync

func (*State) SyncPointer added in v0.6.0 

func (s *State) SyncPointer()

SyncPointer syncs value ptr to value

func (*State) Type added in v0.4.0 

func (s *State) Type() *StateType

Type returns state type

func (*State) Value added in v0.3.0 

func (s *State) Value(aPath string, pathOptions ...PathOption) (interface{}, error)

Value returns a value for supplied path

func (*State) Values added in v0.4.0 

func (s *State) Values(aPath string, pathOptions ...PathOption) ([]interface{}, error)

Values returns a values for supplied path

type StateType added in v0.3.0 

type StateType struct {
	// contains filtered or unexported fields
}

StateType represents a state type

func NewStateType added in v0.3.0 

func NewStateType(rType reflect.Type, opts ...SelectorOption) *StateType

NewStateType creates a state type

func (*StateType) HasMarker added in v0.4.0 

func (s *StateType) HasMarker() bool

func (*StateType) IsDefined added in v0.4.0 

func (s *StateType) IsDefined() bool

func (*StateType) Lookup added in v0.4.0 

func (s *StateType) Lookup(name string) *Selector

Lookup returns a selector

func (*StateType) Marker added in v0.4.0 

func (s *StateType) Marker() *Marker

Marker returns marker

func (*StateType) MatchByTag added in v0.4.3 

func (s *StateType) MatchByTag(tagName string) []*Selector

MatchByTag matches selector by tag name

func (*StateType) NewState added in v0.3.0 

func (t *StateType) NewState() *State

NewState creates a state

func (*StateType) RootSelectors added in v0.4.3 

func (s *StateType) RootSelectors() []*Selector

func (*StateType) Type added in v0.4.0 

func (s *StateType) Type() reflect.Type

Type returns state underlying reflect type

func (*StateType) WithValue added in v0.3.0 

func (t *StateType) WithValue(value interface{}) *State

WithValue creates a state with value

Source Files

View all Source files

Directories

Path Synopsis
encoding
json

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.