README

OGDL for Go

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 language 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 and the implementations.

This implementation does not support cyles (OGDL Level 2).

Documentation

The documentation of the package is kindly generated by godoc.org.

Installation

go get github.com/rveen/ogdl

Discussion

Use the ogdl-go list, if necessary.

Example: a configuration file

If we have a text file 'conf.g' like this:

eth0
  ip
    192.168.1.1
  gateway
    192.168.1.10
  mask
    255.255.255.0
  timeout
    20

then,

g := ogdl.FromFile("conf.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 were not present, then the default value (60) will be assigned to 'to'.

Expand ▾ Collapse ▴

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

Examples

Constants

View Source
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

    func TCPRawServer(host string, handler func(c net.Conn, b []byte) []byte, timeout int) error

    func TCPServerV1

    func TCPServerV1(host string, handler func(net.Conn, *Graph) *Graph, timeout int) error

    func TCPServerV2

    func TCPServerV2(host string, handler func(net.Conn, *Graph) *Graph, timeout int) error

    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

      func FromBinary(b []byte) *Graph

        FromBinary converts an OGDL binary stream of bytes into a Graph.

        func FromBinaryFile

        func FromBinaryFile(file string) *Graph

          FromBinaryFile converts an OGDL binary stream of bytes into a Graph.

          func FromBinaryReader

          func FromBinaryReader(r io.Reader) *Graph

            FromBinaryReader converts an OGDL binary stream of bytes into a Graph.

            func FromBytes

            func FromBytes(b []byte) *Graph

              FromBytes parses OGDL text contained in a byte array. It returns a *Graph

              func FromFile

              func FromFile(s string) *Graph

                FromFile parses OGDL text contained in a file. It returns a Graph

                func FromJSON

                func FromJSON(buf []byte) (*Graph, error)

                  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

                  func FromReader(r io.Reader) *Graph

                    FromReader parses OGDL text coming from a generic io.Reader

                    func FromString

                    func FromString(s string) *Graph

                      FromString parses OGDL text from the given string. It returns a *Graph

                      func New

                      func New(n ...interface{}) *Graph

                        New returns a pointer to Graph, which will be either empty or contain the (optional) object given.

                        func NewExpression

                        func NewExpression(s string) *Graph

                          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
                          Output:
                          
                          2
                          

                          func NewPath

                          func NewPath(s string) *Graph

                            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

                            func NewTemplate(s string) *Graph

                              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
                              Output:
                              
                              Hello, Jenny
                              

                              func NewTemplateFromBytes

                              func NewTemplateFromBytes(b []byte) *Graph

                                NewTemplateBytes has the same function as NewTemplate except that the input stream is a byte array.

                                func (*Graph) Add

                                func (g *Graph) Add(n interface{}) *Graph

                                  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) AddNodes

                                  func (g *Graph) AddNodes(g2 *Graph) *Graph

                                    AddNodes adds subnodes of the given Graph to the current node.

                                    func (*Graph) Binary

                                    func (g *Graph) Binary() []byte

                                      Binary converts a Graph to a binary OGDL byte stream.

                                      func (*Graph) Bool

                                      func (g *Graph) Bool() 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) Bytes

                                        func (g *Graph) Bytes() []byte

                                          Bytes returns the graph as []byte, or nil if not possble.

                                          func (*Graph) Check

                                          func (g *Graph) Check(x *Graph) (bool, string)

                                            Check returns true if the Graph given as a parameter conforms to the schema represented by the receiver Graph.

                                            Example
                                            Output:
                                            
                                            true
                                            

                                            func (*Graph) Clear

                                            func (g *Graph) Clear()

                                              Clear removes all subnodes

                                              func (*Graph) Clone

                                              func (g *Graph) Clone() *Graph

                                                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

                                                func (g *Graph) Copy(c *Graph)

                                                  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

                                                  func (g *Graph) Create(s string) *Graph

                                                    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) DeleteAt

                                                      func (g *Graph) DeleteAt(i int)

                                                        DeleteAt removes a subnode by index

                                                        func (*Graph) Depth

                                                        func (g *Graph) Depth() int

                                                          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

                                                          func (g *Graph) Equals(c *Graph) bool

                                                            Equals returns true if the given graph and the receiver graph are equal.

                                                            func (*Graph) Eval

                                                            func (g *Graph) Eval(e *Graph) interface{}

                                                              Eval takes a parsed expression and evaluates it in the context of the current graph.

                                                              Example
                                                              Output:
                                                              
                                                              7
                                                              43
                                                              

                                                              func (*Graph) Find

                                                              func (g *Graph) Find(re string) (*Graph, error)

                                                                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

                                                                func (g *Graph) Float64(def ...float64) 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

                                                                  func (g *Graph) Get(s string) *Graph

                                                                    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
                                                                    Output:
                                                                    
                                                                    1
                                                                    3
                                                                    ---
                                                                    1
                                                                    3
                                                                    ---
                                                                    b
                                                                      1
                                                                    

                                                                    func (*Graph) GetAt

                                                                    func (g *Graph) GetAt(i int) *Graph

                                                                      GetAt returns a subnode by index, or nil if the index is out of range.

                                                                      func (*Graph) GetBool

                                                                      func (g *Graph) GetBool(path string) (bool, error)

                                                                        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

                                                                        func (g *Graph) GetBytes(path string) ([]byte, error)

                                                                          GetBytes returns the result of applying a path to the given Graph. The result is returned as a byte slice.

                                                                          func (*Graph) GetFloat64

                                                                          func (g *Graph) GetFloat64(path string) (float64, error)

                                                                            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

                                                                            func (g *Graph) GetInt64(path string) (int64, error)

                                                                              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

                                                                              func (g *Graph) GetString(path string) (string, error)

                                                                                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

                                                                                func (g *Graph) Int64(def ...int64) 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

                                                                                  func (g *Graph) Interface() interface{}

                                                                                    Interface returns the first child of this node as an interface

                                                                                    func (*Graph) IsNil

                                                                                    func (g *Graph) IsNil() bool

                                                                                      IsNil returns true is this node has no content.

                                                                                      func (*Graph) Len

                                                                                      func (g *Graph) Len() int

                                                                                        Len returns the number of subnodes (outgoing edges, out degree) of this node.

                                                                                        func (*Graph) Node

                                                                                        func (g *Graph) Node(s string) *Graph

                                                                                          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

                                                                                            func (tpl *Graph) Process(ctx *Graph) []byte

                                                                                              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

                                                                                                func (g *Graph) Set(s string, val interface{}) *Graph

                                                                                                  Set sets the first occurrence of the given path to the value given.

                                                                                                  TODO: Support indexes

                                                                                                  Example
                                                                                                  Output:
                                                                                                  
                                                                                                  a
                                                                                                    b
                                                                                                      d
                                                                                                  
                                                                                                  Example (A)
                                                                                                  Output:
                                                                                                  
                                                                                                  R
                                                                                                    b
                                                                                                    id
                                                                                                      1
                                                                                                  

                                                                                                  func (*Graph) Show

                                                                                                  func (g *Graph) Show() string

                                                                                                    Show prints the Graph as text including this (the top) node.

                                                                                                    func (*Graph) String

                                                                                                    func (g *Graph) String(def ...string) 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

                                                                                                      func (g *Graph) Substitute(s string, v interface{})

                                                                                                        Substitute traverses the graph substituting all nodes with content equal to s by v.

                                                                                                        func (*Graph) Text

                                                                                                        func (g *Graph) Text() string

                                                                                                          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

                                                                                                          func (g *Graph) ThisBytes() []byte

                                                                                                            ThisBytes returns the node as []byte, or nil if not possble.

                                                                                                            func (*Graph) ThisInt64

                                                                                                            func (g *Graph) ThisInt64() (int64, bool)

                                                                                                              ThisInt64 returns a int64 or nil

                                                                                                              func (*Graph) ThisNumber

                                                                                                              func (g *Graph) ThisNumber() interface{}

                                                                                                                ThisNumber returns either a float64, int64 or nil

                                                                                                                func (*Graph) ThisScalar

                                                                                                                func (g *Graph) ThisScalar() interface{}

                                                                                                                  ThisScalar returns this node's content as an interface

                                                                                                                  func (*Graph) ThisString

                                                                                                                  func (g *Graph) ThisString(def ...string) string

                                                                                                                    ThisString returns the current node content as a string

                                                                                                                    func (*Graph) ThisType

                                                                                                                    func (g *Graph) ThisType() string

                                                                                                                      ThisType returns the name of the native type contained in the current node.

                                                                                                                      func (*Graph) ThisValue

                                                                                                                      func (g *Graph) ThisValue() reflect.Value

                                                                                                                        ThisValue returns this node as a reflect.Value.

                                                                                                                        func (*Graph) Value

                                                                                                                        func (g *Graph) Value() reflect.Value

                                                                                                                          Value returns the node as a reflect.Value.

                                                                                                                          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 OpenLog

                                                                                                                            func OpenLog(file string) (*Log, error)

                                                                                                                              OpenLog opens a log file. If the file doesn't exist, it is created.

                                                                                                                              func (*Log) Add

                                                                                                                              func (log *Log) Add(g *Graph) int64

                                                                                                                                Add adds an OGDL object to the log. The starting position into the log is returned.

                                                                                                                                func (*Log) AddBinary

                                                                                                                                func (log *Log) AddBinary(b []byte) int64

                                                                                                                                  AddBinary adds an OGDL binary object to the log. The starting position into the log is returned.

                                                                                                                                  func (*Log) Close

                                                                                                                                  func (log *Log) Close()

                                                                                                                                    Close closes a log file

                                                                                                                                    func (*Log) Get

                                                                                                                                    func (log *Log) Get(i int64) (*Graph, int64, error)

                                                                                                                                      Get returns the OGDL object at the position given and the position of the next object, or an error.

                                                                                                                                      func (*Log) GetBinary

                                                                                                                                      func (log *Log) GetBinary(i int64) ([]byte, int64, error)

                                                                                                                                        GetBinary returns the OGDL object at the position given and the position of the next object, or an error. The object returned is in binary form, exactly as it is stored in the log.

                                                                                                                                        func (*Log) Sync

                                                                                                                                        func (log *Log) Sync()

                                                                                                                                          Sync commits the changes to disk (the exact behavior is OS dependent).

                                                                                                                                          type RFunction

                                                                                                                                          type RFunction struct {
                                                                                                                                          	Host     string
                                                                                                                                          	Protocol int
                                                                                                                                          	// contains filtered or unexported fields
                                                                                                                                          }

                                                                                                                                            RFunction represents a remote function (also known as a remote procedure call).

                                                                                                                                            func NewRFunction

                                                                                                                                            func NewRFunction(host string) *RFunction

                                                                                                                                            func (*RFunction) Call

                                                                                                                                            func (rf *RFunction) Call(g *Graph) (*Graph, error)

                                                                                                                                              Call makes a remote call. It sends the given Graph in binary format to the server and returns the response Graph.

                                                                                                                                              func (*RFunction) Close

                                                                                                                                              func (rf *RFunction) Close()

                                                                                                                                                Close closes the underlying connection, if open.

                                                                                                                                                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