knoa

README

Knoa

The swiss knife to deal with the hassle of unstructured data.

package main

import (
	"fmt"

	"github.com/ivancorrales/knoa"
	"github.com/ivancorrales/knoa/outputter"
)

type Person struct {
	Firstname string   `structs:"firstname"`
	Age       int      `structs:"age"`
	Siblings  []Person `structs:"siblings,omitempty"`
}

func main() {
	k := knoa.Map().Set("firstname", "John", "age", 20)
	fmt.Println(k.JSON())
	// {"age":20,"firstname":"John"}

	k.Set("siblings", []Person{
		{
			Firstname: "Tim",
			Age:       29,
		},
		{
			Firstname: "Bob",
			Age:       40,
		},
	})
	fmt.Println(k.JSON())
	// {"age":20,"firstname":"John","siblings":[{"age":29,"firstname":"Tim"},{"age":40,"firstname":"Bob"}]}

	k.Set("age", 23, "siblings[1].age", 39)
	fmt.Println(k.JSON())
	// {"age":23,"firstname":"John","siblings":[{"age":29,"firstname":"Tim"},{"age":39,"firstname":"Bob"}]}

	k.Set("siblings[*].age", 40)
	fmt.Println(k.JSON())
	// {"age":23,"firstname":"John","siblings":[{"age":40,"firstname":"Tim"},{"age":40,"firstname":"Bob"}]}

	k.Unset("siblings[0]")
	fmt.Println(k.JSON())
	// {"age":23,"firstname":"John","siblings":[{"age":40,"firstname":"Bob"}]}

	fmt.Println(k.JSON(outputter.WithPrefixAndIdent(" ", " ")))
	/**
	{
	 "age": 23,
	 "firstname": "John",
	 "siblings": [
	  {
       "age": 40,
	   "firstname": "Bob"
	  }
	 ]
	}
	**/
	
	fmt.Println(k.YAML())
	/**
	age: 23
	firstname: John
	siblings:
		- age: 40
		firstname: Bob
	**/

	var person Person
	k.To(&person)
	fmt.Println(person)
	// {John 23 [{Bob 40 []}]}
}

The above code can be run at https://go.dev/play/p/LCkzZSiXbo9

Getting started

Installation

Use go get to retrieve the library to add it to your GOPATH workspace, or project's Go module dependencies.

go get -u github.com/ivancorrales/knoa

To update the library use go get -u to retrieve the latest version of it.

go get -u github.com/ivancorrales/knoa

You could specify a concrete version of this module as It's shown on the below. Replace x.y.z by the desired version.

module github.com/<org>/<repository>
require ( 
  github.com/ivancorrales/knoa vX.Y.Z
)

Pre-requisites

• Go 1.20+

Examples

Check the following examples

Create and modify an array dynamically

k := knoa.Array().Set("[1]", []string{"red", "blue", "green"}, "[2].firstname", "John")
fmt.Println(k.String())
// [null,["red","blue","green"],{"firstname":"John"}]

k.Set("[0]", struct {
    FullName  string `structs:"fullName"`
    RoleLevel int    `structs:"roleLevel"`
}{
    "Senior Developer",
    3,
})
fmt.Println(k.String())
// [{"fullName":"Senior Developer","roleLevel":3},["red","blue","green"],{"firstname":"John"}]

k.Set("[0].enabled", false, "[2].firstname", "Jane")
fmt.Println(k.String())
// [{"enabled":false,"fullName":"Senior Developer","roleLevel":3},["red","blue","green"],{"firstname":"Jane"}]

Create and modify a map dynamically

k := knoa.Map().Set("firstname", "John", "age", 20)
fmt.Println(k.String())
// {"age":20,"firstname":"John"}

k.Set("siblings", []Person{
    {
        Firstname: "Tim",
        Age:       29,
    }, {
        Firstname: "Bob",
        Age:       40,
    },
})
fmt.Println(k.String())
// {"age":20,"firstname":"John","siblings":[{"age":29,"firstname":"Tim"},{"age":40,"firstname":"Bob"}]}

k.Set("age", 23, "siblings[1].age", 39)
fmt.Println(k.String())
// {"age":23,"firstname":"John","siblings":[{"age":29,"firstname":"Tim"},{"age":39,"firstname":"Bob"}]}

Decode an unstructured data into an array of structs

type Person struct {
    Firstname string `struct:"firstname"`
    Age       int    `struct:"age"`
}



k:= knoa.FromArray([]any{
    Person{
        Firstname: "Jane",
        Age:       20,
	},
})
k.Set("[1]", Person{
        Firstname: "Bob",
        Age:       23,
    },"[2].firstname", "John")

var output []Person
k.To(&output)

Decode an unstructured data into a struct

type Person struct {
    Firstname string   `structs:"firstname"`
    Age       int      `structs:"age"`
    Siblings  []Person `structs:"siblings,omitempty"`
}

k := knoa.Map().Set("firstname", "John", "age", 20)
	
k.Set("siblings", []Person{
    {
	    Firstname: "Tim",
		Age:       29,
	}, 
	{
	    Firstname: "Bob",
		Age:       40,
	},
})

k.Set("age", 23, "siblings[1].age", 39)

var person Person
k.To(&person)

Additionally, we encourage to have a look at folder examples to get a better understanding on how knoa works.

Contributing

See the contributing documentation.

Please, feel free to create any feature request that you miss or register any bug that need to be fixed.

Documentation

Index

• Variables
• func WithAttributeNameFormat(attrNameFmt string) func(builder *builder)
• func WithStrictMode(strict bool) func(builder *builder)
• type Knoa
  • func Array(opts ...Opt) Knoa[[]any]
  • func FromArray(content []any, opts ...Opt) Knoa[[]any]
  • func FromMap(content map[string]any, opts ...Opt) Knoa[map[string]any]
  • func Map(opts ...Opt) Knoa[map[string]any]
  • func New[T Type](options ...Opt) Knoa[T]
• type Opt
• type Type

Variables

var (
	WithFuncPrefix   = mutator.WithFuncPrefix
	WithStringPrefix = mutator.WithStringPrefix
)

Functions

func WithAttributeNameFormat

func WithAttributeNameFormat(attrNameFmt string) func(builder *builder)

func WithStrictMode

func WithStrictMode(strict bool) func(builder *builder)

Types

type Knoa

type Knoa[T Type] interface {
	Set(pathValueList ...any) Knoa[T]
	Unset(pathValueList ...string) Knoa[T]
	Apply(args ...any) Knoa[T]
	With(opts ...mutator.OperationOpt) func(pathValueList ...any) Knoa[T]
	Out() T
	YAML(opts ...outputter.YAMLOpt) string
	JSON(opts ...outputter.JSONOpt) string
	To(output interface{})
	Error() error
}

func Array

func Array(opts ...Opt) Knoa[[]any]

func FromArray

func FromArray(content []any, opts ...Opt) Knoa[[]any]

func FromMap

func FromMap(content map[string]any, opts ...Opt) Knoa[map[string]any]

func Map

func Map(opts ...Opt) Knoa[map[string]any]

func New

func New[T Type](options ...Opt) Knoa[T]

type Opt

type Opt func(sanitizer *builder)

type Type

type Type internal.Type