sqi

README

sqi

A simple Go query library for interface{}s.

Sqi lets you ask questions about your data. It can be used to find values and extract results from complex user data, as well as data that has been hydrated via an encoding such as JSON.

QUICK START

Sqi accesses nested data via a simple topic string. It provides the general function Eval() for locating a result, along with conveniences such as EvalInt(), EvalString(), etc. for typed results. The main use case is to provide a path (/) delimited string and data to an Eval() function.

Here's a complete example:

package main

import (
	"fmt"
	"github.com/hackborn/sqi"
)

func main() {
	// User-defined data model
	type Person struct {
		Name     string
		Children []Person
	}

	// User-defined data
	parent := &Person{"Katie", []Person{
		Person{"Eleanor", nil},
		Person{"Jason", nil},
	}}

	// Get a single top-level value
	name := sqi.EvalString("/Name", parent, nil)

	// Get a collection of nested values.
	children, _ := sqi.Eval("/Children", parent, nil)

	// Get a value from a child.
	childname := sqi.EvalString("/Children[0]/Name", parent, nil)

	fmt.Println("Parent's name is", name)
	fmt.Println("Parent's children are", children)
	fmt.Println("First child's name is", childname)
}

The output is

Parent's name is Katie
Parent's children are [{Eleanor []} {Jason []}]
First child's name is Eleanor

OPERATORS

Examples for the following operators use this data model:

type Person struct {
	Name     string
	Age      int
	Children []Person
}

PATH

The path / operator answers the field or map key with the given value.

Example:

sqi.EvalString(`/Name`, &Person{Name: "Ana"})

results in "Ana".

EQUALS

The equals == operator answers true if the left side matches the right side, false otherwise.

Example:

sqi.EvalBool(`/Age == 22`, &Person{Age: 22})

results in true.

NOT EQUALS

The not equals != operator is the opposite of equals.

AND

The and && operator evalutes to true if both the left and right sides are true.

OR

The or || operator evalutes to true if either the left or right side is true.

PARENTHESES

The parentheses () operator encapsulates a phrase.

ARRAY

The array [] operator answers an element of an array or slice. Currently it only supports a single index value.

Example:

sqi.Eval(`/Children[0]`, &Person{Children: []Person{Person{Name: "a"}}})

results in Person{Name: a}.

TECHNIQUES

SELECT

A select finds one or more items from a collection. Selects in sqi are basically paths with an equality statement.

Example 1. Answer a collection of one or more items.

sqi.Eval(`/Children/(/Name == "c")`, &Person{Children: []Person{Person{Name: "a"}, Person{Name: "c"}}})

results in []Person{Person{Name: c}}.

Example 2. Answer a single value from a collection.

sqi.Eval(`(/Children/(/Name == "c"))[0]`, &Person{Children: []Person{Person{Name: "a"}, Person{Name: "c"}}})

results in Person{Name: c}.

CREDIT

Much thanks to a couple people who have provided great info on top down operator precedence parsers:
Cristian Dima
Eli Bendersky

Documentation

Index

• func Eval(term string, input interface{}, opt *Opt) (interface{}, error)
• func EvalBool(term string, input interface{}, opt *Opt) bool
• func EvalFloat64(term string, input interface{}, opt *Opt) float64
• func EvalInt(term string, input interface{}, opt *Opt) int
• func EvalString(term string, input interface{}, opt *Opt) string
• func EvalStringInterfaceMap(term string, input interface{}, opt *Opt) map[string]interface{}
• func EvalStringSlice(term string, input interface{}, opt *Opt) []string
• func EvalStringStringMap(term string, input interface{}, opt *Opt) map[string]string
• type AstNode
• type Expr
  • func MakeExpr(term string) (Expr, error)
• type Opt

Functions

func Eval

func Eval(term string, input interface{}, opt *Opt) (interface{}, error)

Eval runs term against input, returning the result.

func EvalBool

func EvalBool(term string, input interface{}, opt *Opt) bool

EvalBool runs term against input, returning the boolean result. If an error occurs, the opt.OnError is returned.

func EvalFloat64

func EvalFloat64(term string, input interface{}, opt *Opt) float64

EvalFloat64 runs term against input, returning the float64 result. If an error occurs, the opt.OnError is returned.

func EvalInt

func EvalInt(term string, input interface{}, opt *Opt) int

EvalInt runs term against input, returning the int result. If an error occurs, the opt.OnError is returned.

func EvalString

func EvalString(term string, input interface{}, opt *Opt) string

EvalString runs term against input, returning the string result. If an error occurs, the opt.OnError is returned.

func EvalStringInterfaceMap

func EvalStringInterfaceMap(term string, input interface{}, opt *Opt) map[string]interface{}

EvalStringInterfaceMap runs term against input, returning the string map result. If an error occurs, the opt.OnError is returned or nil.

func EvalStringSlice

func EvalStringSlice(term string, input interface{}, opt *Opt) []string

EvalStringSlice runs term against input, returning the string slice result. If an error occurs, the opt.OnError is returned or nil.

func EvalStringStringMap

func EvalStringStringMap(term string, input interface{}, opt *Opt) map[string]string

EvalStringStringMap runs term against input, returning the string map result. If an error occurs, the opt.OnError is returned or nil.

Types

type AstNode

type AstNode interface {
	// Evaluate the interface, returning the results. This is intended
	// to  be only an internal API: the Opt* is a pointer but can not be nil.
	Eval(interface{}, *Opt) (interface{}, error)
}

AstNode defines the basic interface for evaluating expressions.

type Expr

type Expr interface {
	Eval(interface{}, *Opt) (interface{}, error)
}

Expr is an interface for anything that can evaluate input.

func MakeExpr

func MakeExpr(term string) (Expr, error)

MakeExpr converts an expression string into an evaluatable object.

type Opt

type Opt struct {
	// Strict causes sloppy conditions to become errors. For example, comparing a
	// number to a string is false if strict is off, but error if it's on.
	Strict bool
	// OnError is a value returned when one of the typed Eval() statements returns an error.
	// Must match the type. For example, the value must be assigend a string if using EvalString().
	OnError interface{}
}

Opt contains options for evaluation.