lilgraph

README

lilgraph

A Little Graph Language -- a plain text format for describing simple directed graphs.

The format is inspired by DOT, with a few bits stripped out or tweaked, and a hint of Cypher thrown in.

Example

// A node is an id, with optional attributes in square-brackets after it. All
// attrs are treated as strings.
// The first attr item can be standalone; this is treated specially, as the
// Type property, and isn't part of the attrs map.

luke [human; homeplanet=tatooine]
leia [human; homeplanet=alderaan]

// Types are optional, though:

chewbacca [homeplanet=kashyyyk]

// Nodes don't _need_ to have attributes, though. A bare id is a valid node:

obi_wan

// Duplicate nodes are merged. Later attributes win. So these two:

luke[saber_color=blue force_sensitivity=high]
luke[saber_color=green]

// ... are equivalent to:

luke[saber_color=green force_sensitivity=high]

// A specific node id can only have one type value declared. That value can be
// repeated, or omitted, later; but can't change. So these are OK...

luke [human]
luke

// ...but this would fail:

# luke[forceghost]

// Edges can be declared between any node ids.

obi_wan -> luke

// To form edges, nodes don't have to be declared beforehand.

r2d2 -> sandcrawler
c3po -> sandcrawler

// Edges can have attributes too. These are declared in the middle of edges.
// Like nodes, the first value can be standalone and is treated as "type".

luke -[member]-> jedi
leia -[member]-> rebel_alliance

// If you need big edge attribute lists, you can split them over multiple lines.

luke -[member;
    callsign="Red Five"
    primary_craft="X-Wing"
    pilot_training_qualification="Bullseye'ing womprats in his T16"
]-> red_squadron

// Edges can be chained.
yoda -[trained]-> dooku -[trained]-> qui_gon -[trained]-> obi_wan -[trained]-> anakin

// Like nodes, duplicate edges are merged. This is based on edge source, target
// and type.  So, these form three separate edges, one of them type-less:

obi_wan -> luke
obi_wan -[protected]-> luke
obi_wan -[trained]-> luke
obi_wan -[protected since=birth]-> luke
obi_wan -[trained when="0 BBY"]-> luke

// If you like alignment, edge arrows can be extended.

han_solo ---[owns]---> millenium_falcon
chewbacca -[crew_of]-> millenium_falcon

/*
C-style block comments are supported.
*/
# Hash comments are also supported

Documentation

Index

• Variables
• type Edge
  • func (c *Edge) AttrsMap() map[string]string
  • func (c *Edge) DeleteAttr(key string)
  • func (e *Edge) From() *Node
  • func (c *Edge) GetAttr(key string) (string, bool)
  • func (c *Edge) ReplaceAttrs(m map[string]string)
  • func (c *Edge) SetAttr(key, value string) error
  • func (e *Edge) To() *Node
  • func (e *Edge) Type() string
• type Lilgraph
  • func NewGraph() *Lilgraph
  • func Parse(src []byte) (*Lilgraph, error)
  • func ParseFile(path string) (*Lilgraph, error)
  • func (g *Lilgraph) AddEdge(from *Node, to *Node, edgeType string) (*Edge, bool, error)
  • func (g *Lilgraph) AddNode(id string, typ string) (*Node, bool, error)
  • func (g *Lilgraph) DeleteEdge(e *Edge) bool
  • func (g *Lilgraph) DeleteNode(n *Node) bool
  • func (g *Lilgraph) Edges() iter.Seq[*Edge]
  • func (g *Lilgraph) Find(id string) *Node
  • func (g *Lilgraph) FindEdge(from *Node, to *Node, edgeType string) (*Edge, bool)
  • func (g *Lilgraph) FindEdges(from *Node, to *Node) iter.Seq[*Edge]
  • func (g *Lilgraph) MarshalText() (text []byte, err error)
  • func (g *Lilgraph) Nodes() iter.Seq[*Node]
  • func (g *Lilgraph) SortTopo() error
• type Node
  • func (c *Node) AttrsMap() map[string]string
  • func (c *Node) DeleteAttr(key string)
  • func (n *Node) EdgesFrom() iter.Seq[*Edge]
  • func (n *Node) EdgesTo() iter.Seq[*Edge]
  • func (c *Node) GetAttr(key string) (string, bool)
  • func (n *Node) Id() string
  • func (c *Node) ReplaceAttrs(m map[string]string)
  • func (c *Node) SetAttr(key, value string) error
  • func (c *Node) Type() string

Variables

var (
	ErrInvalidId    = errors.New("invalid node id")
	ErrParseFail    = errors.New("failed parsing")
	ErrLoop         = errors.New("cannot create edge from a node to itself")
	ErrBadParseType = errors.New("unexpected parser result type")
	ErrTypeChange   = errors.New("nodes cannot be redefined with a different type")
	ErrTypeInAttrs  = errors.New("attributes called 'type' aren't allowed to avoid ambiguity")
	ErrCyclic       = errors.New("graph is cyclic")
)

Types

type Edge

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

func (*Edge) AttrsMap

func (c *Edge) AttrsMap() map[string]string

func (*Edge) DeleteAttr

func (c *Edge) DeleteAttr(key string)

func (*Edge) From

func (e *Edge) From() *Node

func (*Edge) GetAttr

func (c *Edge) GetAttr(key string) (string, bool)

func (*Edge) ReplaceAttrs

func (c *Edge) ReplaceAttrs(m map[string]string)

func (*Edge) SetAttr

func (c *Edge) SetAttr(key, value string) error

func (*Edge) To

func (e *Edge) To() *Node

func (*Edge) Type

func (e *Edge) Type() string

type Lilgraph

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

func NewGraph

func NewGraph() *Lilgraph

func Parse

func Parse(src []byte) (*Lilgraph, error)

func ParseFile

func ParseFile(path string) (*Lilgraph, error)

func (*Lilgraph) AddEdge

func (g *Lilgraph) AddEdge(from *Node, to *Node, edgeType string) (*Edge, bool, error)

func (*Lilgraph) AddNode

func (g *Lilgraph) AddNode(id string, typ string) (*Node, bool, error)

func (*Lilgraph) DeleteEdge

func (g *Lilgraph) DeleteEdge(e *Edge) bool

func (*Lilgraph) DeleteNode

func (g *Lilgraph) DeleteNode(n *Node) bool

func (*Lilgraph) Edges

func (g *Lilgraph) Edges() iter.Seq[*Edge]

func (*Lilgraph) Find

func (g *Lilgraph) Find(id string) *Node

func (*Lilgraph) FindEdge

func (g *Lilgraph) FindEdge(from *Node, to *Node, edgeType string) (*Edge, bool)

func (*Lilgraph) FindEdges

func (g *Lilgraph) FindEdges(from *Node, to *Node) iter.Seq[*Edge]

func (*Lilgraph) MarshalText

func (g *Lilgraph) MarshalText() (text []byte, err error)

func (*Lilgraph) Nodes

func (g *Lilgraph) Nodes() iter.Seq[*Node]

func (*Lilgraph) SortTopo

func (g *Lilgraph) SortTopo() error

type Node

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

func (*Node) AttrsMap

func (c *Node) AttrsMap() map[string]string

func (*Node) DeleteAttr

func (c *Node) DeleteAttr(key string)

func (*Node) EdgesFrom

func (n *Node) EdgesFrom() iter.Seq[*Edge]

func (*Node) EdgesTo

func (n *Node) EdgesTo() iter.Seq[*Edge]

func (*Node) GetAttr

func (c *Node) GetAttr(key string) (string, bool)

func (*Node) Id

func (n *Node) Id() string

func (*Node) ReplaceAttrs

func (c *Node) ReplaceAttrs(m map[string]string)

func (*Node) SetAttr

func (c *Node) SetAttr(key, value string) error

func (*Node) Type

func (c *Node) Type() string