Documentation ¶
Overview ¶
Package ogdl is used to process OGDL, the Ordered Graph Data Language.
OGDL is a textual format to write trees or graphs of text, where indentation and spaces define the structure. Here is an example:
network ip 192.168.1.100 gw 192.168.1.9
The languange is simple, either in its textual representation or its number of productions (the specification rules), allowing for compact implementations.
OGDL character streams are normally formed by Unicode characters, and encoded as UTF-8 strings, but any encoding that is ASCII transparent is compatible with the specification.
See the full spec at http://ogdl.org.
Installation ¶
To install this package just do:
go get github.com/rveen/ogdl
An example ¶
If we have a text file 'config.g' containing:
eth0 ip 192.168.1.1 gateway 192.168.1.10 mask 255.255.255.0 timeout 20
then,
g := ogdl.FromFile("config.g") ip := g.Get("eth0.ip").String() to := g.Get("eth0.timeout").Int64(60) println("ip:",ip,", timeout:",to)
will print
ip: 192.168.1.1, timeout: 20
If the timeout parameter was not present, then the default value (60) will be assigned to 'to'. The default value is optional, but be aware that Int64() will return 0 in case that the parameter doesn't exist.
The configuration file can be written in a conciser way:
eth0 ip 192.168.1.1 gateway 192.168.1.10 mask 255.255.255.0 timeout 20
A template example ¶
The package includes a template processor. It takes an arbitrary input stream with some variables in it, and produces an output stream with the variables resolved out of a Graph object which acts as context.
For example (given the previous config file):
g := ogdl.FromFile("config.g") t := ogdl.NewTemplate("The gateway's IP is $eth0.gateway") b := t.Process(g)
string(b) is then:
The gateway's IP is 192.168.1.10
Function signature conventions ¶
Some rules are followed:
.<Type>() Return the first subnode content converted to the specified type. .This<Type>() Return the node content itself converted to the specified type. .Get() Return the specified path as a (possible nil) *Graph object. .Get<Type>() Return the specified path converted to the specified type. These series of functions return value and error.
Index ¶
- Constants
- func TCPRawServer(host string, handler func(c net.Conn, b []byte) []byte, timeout int) error
- func TCPServerV1(host string, handler func(net.Conn, *Graph) *Graph, timeout int) error
- func TCPServerV2(host string, handler func(net.Conn, *Graph) *Graph, timeout int) error
- type Graph
- func FromBinary(b []byte) *Graph
- func FromBinaryFile(file string) *Graph
- func FromBinaryReader(r io.Reader) *Graph
- func FromBytes(b []byte) *Graph
- func FromFile(s string) *Graph
- func FromJSON(buf []byte) (*Graph, error)
- func FromReader(r io.Reader) *Graph
- func FromString(s string) *Graph
- func New(n ...interface{}) *Graph
- func NewExpression(s string) *Graph
- func NewPath(s string) *Graph
- func NewTemplate(s string) *Graph
- func NewTemplateFromBytes(b []byte) *Graph
- func (g *Graph) Add(n interface{}) *Graph
- func (g *Graph) AddNodes(g2 *Graph) *Graph
- func (g *Graph) Binary() []byte
- func (g *Graph) Bool() bool
- func (g *Graph) Bytes() []byte
- func (g *Graph) Check(x *Graph) (bool, string)
- func (g *Graph) Clear()
- func (g *Graph) Clone() *Graph
- func (g *Graph) Copy(c *Graph)
- func (g *Graph) Create(s string) *Graph
- func (g *Graph) Delete(n interface{})
- func (g *Graph) DeleteAt(i int)
- func (g *Graph) Depth() int
- func (g *Graph) Equals(c *Graph) bool
- func (g *Graph) Eval(e *Graph) interface{}
- func (g *Graph) Find(re string) (*Graph, error)
- func (g *Graph) Float64(def ...float64) float64
- func (g *Graph) Get(s string) *Graph
- func (g *Graph) GetAt(i int) *Graph
- func (g *Graph) GetBool(path string) (bool, error)
- func (g *Graph) GetBytes(path string) ([]byte, error)
- func (g *Graph) GetFloat64(path string) (float64, error)
- func (g *Graph) GetInt64(path string) (int64, error)
- func (g *Graph) GetString(path string) (string, error)
- func (g *Graph) Int64(def ...int64) int64
- func (g *Graph) Interface() interface{}
- func (g *Graph) IsNil() bool
- func (g *Graph) Len() int
- func (g *Graph) Node(s string) *Graph
- func (g *Graph) Number() interface{}
- func (tpl *Graph) Process(ctx *Graph) []byte
- func (g *Graph) Scalar() interface{}
- func (g *Graph) Set(s string, val interface{}) *Graph
- func (g *Graph) Show() string
- func (g *Graph) String(def ...string) string
- func (g *Graph) Substitute(s string, v interface{})
- func (g *Graph) Text() string
- func (g *Graph) ThisBytes() []byte
- func (g *Graph) ThisInt64() (int64, bool)
- func (g *Graph) ThisNumber() interface{}
- func (g *Graph) ThisScalar() interface{}
- func (g *Graph) ThisString(def ...string) string
- func (g *Graph) ThisType() string
- func (g *Graph) ThisValue() reflect.Value
- func (g *Graph) Value() reflect.Value
- type Log
- type RFunction
Examples ¶
Constants ¶
const ( TypeExpression = "!e" TypePath = "!p" TypeVariable = "!v" TypeSelector = "!s" TypeIndex = "!i" TypeGroup = "!g" TypeTemplate = "!t" TypeString = "!string" TypeIf = "!if" TypeEnd = "!end" TypeElse = "!else" TypeFor = "!for" TypeBreak = "!break" )
Nodes containing these strings are special
Variables ¶
This section is empty.
Functions ¶
func TCPRawServer ¶ added in v1.1.0
func TCPServerV1 ¶ added in v1.1.0
Types ¶
type Graph ¶
type Graph struct { This interface{} Out []*Graph }
Graph is a node with outgoing pointers to other Graph objects. It is implemented as a named list.
func FromBinary ¶ added in v1.1.0
FromBinary converts an OGDL binary stream of bytes into a Graph.
func FromBinaryFile ¶ added in v1.1.0
FromBinaryFile converts an OGDL binary stream of bytes into a Graph.
func FromBinaryReader ¶ added in v1.1.0
FromBinaryReader converts an OGDL binary stream of bytes into a Graph.
func FromBytes ¶ added in v1.1.0
FromBytes parses OGDL text contained in a byte array. It returns a *Graph
func FromJSON ¶ added in v1.1.0
FromJSON converts a JSON text stream into OGDL
Json types returned by Unmashal: bool, for JSON booleans float64, for JSON numbers string, for JSON strings []interface{}, for JSON arrays map[string]interface{}, for JSON objects nil for JSON null
func FromReader ¶ added in v1.1.0
FromReader parses OGDL text coming from a generic io.Reader
func FromString ¶ added in v1.1.0
FromString parses OGDL text from the given string. It returns a *Graph
func New ¶ added in v1.1.0
func New(n ...interface{}) *Graph
New returns a pointer to Graph, which will be either empty or contain the (optional) object given.
func NewExpression ¶
NewExpression parses an expression in text format (given in the string) to a Graph, in the form of a suitable syntax tree.
expression := expr1 (op2 expr1)* expr1 := path | constant | op1 path | op1 constant | '(' expr ')' | op1 '(' expr ')' constant ::= quoted | number
Example ¶
e := NewExpression("1-2+3") g := New() i := g.Eval(e) fmt.Println(i)
Output: 2
func NewPath ¶
NewPath takes a Unicode string representing an OGDL path, parses it and returns it as a Graph object.
It also parses extended paths, as those used in templates, which may have argument lists.
func NewTemplate ¶
NewTemplate parses a text template given as a string and converts it to a Graph. Templates have fixed and variable parts. Variables all begin with '$'.
A template is a text file in any format: plain text, HTML, XML, OGDL or whatever. The dolar sign acts as an escape character that switches from the text to the variable plane. Parsed templates are converted back to text by evaluating the variable parts against a Graph object, by means of the Process() method.
Template grammar
template ::= ( text | variable )* variable ::= ('$' path) | ('$' '(' expression ')') | ('$' '{' expression '}') path ::= as defined in path.go expression ::= as defined in expression.go
Some variables act as directives: $if, $else, $end, $for, $break.
$if(expression) $else $end $for(destPath,sourcepath) $break $end
Example ¶
p := NewTemplate("Hello, $user") g := New() g.Add("user").Add("Jenny") fmt.Println(string(p.Process(g)))
Output: Hello, Jenny
func NewTemplateFromBytes ¶ added in v1.1.0
NewTemplateBytes has the same function as NewTemplate except that the input stream is a byte array.
func (*Graph) Add ¶
Add adds a subnode to the current node. If the node to be added is a Graph, it is added as is, else it is wrapped in a newly created Graph object.
func (*Graph) Bool ¶
Bool returns the node as a boolean. If the node is not a boolean, it returns false, or the default value if given.
func (*Graph) Check ¶
Check returns true if the Graph given as a parameter conforms to the schema represented by the receiver Graph.
Example ¶
schema := FromString("a !int, b !string, c !float, d !bool") g := FromString("a 1, b s, c 1.0, d true") b, message := schema.Check(g) fmt.Println(b, message)
Output: true
func (*Graph) Clone ¶ added in v1.1.0
Clone returns a copy of the current graph.
Warning (from the Go faq): Copying an interface value makes a copy of the thing stored in the interface value. If the interface value holds a struct, copying the interface value makes a copy of the struct. If the interface value holds a pointer, copying the interface value makes a copy of the pointer, but not the data it points to.
func (*Graph) Copy ¶
Copy adds a copy of the graph given to the current graph.
Warning (from the Go faq): Copying an interface value makes a copy of the thing stored in the interface value. If the interface value holds a struct, copying the interface value makes a copy of the struct. If the interface value holds a pointer, copying the interface value makes a copy of the pointer, but not the data it points to.
func (*Graph) Create ¶ added in v1.1.0
Create returns the first subnode whose string value is equal to the given string, with its subnodes deleted. If not found, the node is created and returned.
func (*Graph) Delete ¶
func (g *Graph) Delete(n interface{})
Delete removes all subnodes with the given content
func (*Graph) Depth ¶
Depth returns the depth of the graph if it is a tree, or -1 if it has cycles.
TODO: Cycles are inferred if level>100, but nodes traversed are not remembered (they should if cycles need to be detected).
func (*Graph) Equals ¶ added in v1.1.0
Equals returns true if the given graph and the receiver graph are equal.
func (*Graph) Eval ¶
Eval takes a parsed expression and evaluates it in the context of the current graph.
Example ¶
g := New() g.Add("a").Add(4) g.Add("b").Add("4") e := NewExpression("a+3") e2 := NewExpression("b+3") fmt.Println(g.Eval(e)) fmt.Println(g.Eval(e2))
Output: 7 43
func (*Graph) Find ¶ added in v1.1.0
Find returns a Graph with all subnodes that match the regular expression given. It only walks through the subnodes of the current Graph. If the regex doesn't compile, an error will be returned. If the result set is empty, both return values are nil (no error is signaled).
func (*Graph) Float64 ¶
Float64 returns the node as a float64. If the node is not a number, it returns NaN, or the default value if given.
func (*Graph) Get ¶
Get recurses a Graph following a given path and returns the result.
This function returns a *Graph in any condition. When there is nothing to return, a nil Graph is returned. This behavior is designed so that the next function in a chain never gets an invalid receiver, avoiding null pointer errors.
OGDL Path: elements are separated by '.' or [] or {} index := [N] selector := {N} tokens can be quoted
Example ¶
g := FromString("a\n b 1\n c 2\n b 3") fmt.Println(g.Get("a.b{0}").Text()) fmt.Println(g.Get("a.b{1}").Text()) fmt.Println("---") fmt.Println(g.Get("a.b{}").Text()) fmt.Println("---") fmt.Println(g.Get("a[0]").Text())
Output: 1 3 --- 1 3 --- b 1
func (*Graph) GetBool ¶
GetBool returns the result of applying a path to the given Graph. The result is returned as a bool. If the path result cannot be converted to a boolean, then an error is returned.
func (*Graph) GetBytes ¶
GetBytes returns the result of applying a path to the given Graph. The result is returned as a byte slice.
func (*Graph) GetFloat64 ¶
GetFloat64 returns the result of applying a path to the given Graph. The result is returned as a float64. If the path result cannot be converted to a float, then an error is returned.
func (*Graph) GetInt64 ¶
GetInt64 returns the result of applying a path to the given Graph. The result is returned as an int64. If the path result cannot be converted to an integer, then an error is returned.
func (*Graph) GetString ¶
GetString returns the result of applying a path to the given Graph. The result is returned as a string. If the error information is not used, then this method is equivalent to Get(path).String()
func (*Graph) Int64 ¶
Int64 returns the node as an int64. If the node is not a number, it returns 0, or the default value if given.
func (*Graph) Interface ¶ added in v1.1.0
func (g *Graph) Interface() interface{}
Interface returns the first child of this node as an interface
func (*Graph) Node ¶
Node returns the first subnode whose string value is equal to the given string. It returns nil if not found.
func (*Graph) Number ¶
func (g *Graph) Number() interface{}
Number returns either a float64, int64 or nil
func (*Graph) Process ¶
Process processes the parsed template, returning the resulting text in a byte array. The variable parts are resolved out of the Graph given.
func (*Graph) Scalar ¶
func (g *Graph) Scalar() interface{}
Scalar returns the current node content, reducing the number of types following these rules:
uint* -> int64 int* -> int64 float* -> float64 byte -> int64 rune -> int64 bool -> bool string, []byte: if it represents an int or float or bool, convert to int64, float64 or bool
Any other type is returned as is.
func (*Graph) Set ¶
Set sets the first occurrence of the given path to the value given.
TODO: Support indexes
Example ¶
g := FromString("a b c") g.Set("a.b", "d") fmt.Println(g.Text())
Output: a b d
Example (A) ¶
g := New() g.Add("R").Add("b") r := g.Node("R") r.Set("id", "1") fmt.Println(g.Text())
Output: R b id 1
func (*Graph) String ¶
String returns a string representation of this node, or an empty string. This function doesn't return an error, because it is mostly used in single variable return situations. String accepts one default value, which will be returned instead of an empty string.
func (*Graph) Substitute ¶
Substitute traverses the graph substituting all nodes with content equal to s by v.
func (*Graph) Text ¶
Text is the OGDL text emitter. It converts a Graph into OGDL text.
Strings are quoted if they contain spaces, newlines or special characters. Null elements are not printed, and act as transparent nodes.
BUG():Handle comments correctly. BUG(): 2 times almost the same code:
func (*Graph) ThisBytes ¶ added in v1.1.0
ThisBytes returns the node as []byte, or nil if not possble.
func (*Graph) ThisNumber ¶ added in v1.1.0
func (g *Graph) ThisNumber() interface{}
ThisNumber returns either a float64, int64 or nil
func (*Graph) ThisScalar ¶ added in v1.1.0
func (g *Graph) ThisScalar() interface{}
ThisScalar returns this node's content as an interface
func (*Graph) ThisString ¶ added in v1.1.0
ThisString returns the current node content as a string
func (*Graph) ThisType ¶ added in v1.1.0
ThisType returns the name of the native type contained in the current node.
type Log ¶
type Log struct {
// contains filtered or unexported fields
}
Log is a log store for binary OGDL objects.
All objects are appended to a file, and a position is returned.
func (*Log) Add ¶
Add adds an OGDL object to the log. The starting position into the log is returned.
func (*Log) AddBinary ¶
AddBinary adds an OGDL binary object to the log. The starting position into the log is returned.
func (*Log) Get ¶
Get returns the OGDL object at the position given and the position of the next object, or an error.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
gpath
gpath <path> [file] Return the specified path from an OGDL file, or from stdin.
|
gpath <path> [file] Return the specified path from an OGDL file, or from stdin. |
gtemplate
gtemplate <template_file> [ogdl_file]* Processes a template file and solves variables in it using data from any of the OGDL files given
|
gtemplate <template_file> [ogdl_file]* Processes a template file and solves variables in it using data from any of the OGDL files given |