diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..c208c67 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,3 @@ +default: true +MD025: + front_matter_title: "" diff --git a/.vscode/settings.json b/.vscode/settings.json index cf8dd9a..e3bb2fc 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -19,11 +19,16 @@ "Esep", "Functors", "Rects", + "Serializable", "Stringn", + "Styleable", "Tpng", "edgehref", "ediamond", "emicklei", + "emicklei's", + "fontawesome", + "graphviz", "headhref", "icurve", "labelhref", @@ -35,7 +40,9 @@ "mosek", "nojustify", "nslimit", + "pymdownx", "sortv", + "superfences", "tailhref", "voro", "xdot", diff --git a/Node.go b/Node.go index 7579401..0da0023 100644 --- a/Node.go +++ b/Node.go @@ -7,6 +7,7 @@ type Node interface { attributes.Identity attributes.Styleable attributes.Serializable + // Edge creates an Edge to a Node Edge(to Node) Edge // EdgeWithAttributes creates an Edge with the provided attributes to a Node diff --git a/README.md b/README.md index 5905798..cfbe227 100644 --- a/README.md +++ b/README.md @@ -81,9 +81,9 @@ import ( func main() { graph := dot.NewGraph() graph.SetAttributeString("label", "an amazing graph") - clusterA := graph.Subgraph(&GraphOptions{ ID: "Cluster A", Cluster: true }) + clusterA := graph.Subgraph(WithID("Cluster A"), WithCluster()) clusterA.SetAttributeString("label", "Cluster A") - clusterB := graph.Subgraph(&GraphOptions{ ID: "Cluster B", Cluster: true }) + clusterB := graph.Subgraph(WithID("Cluster B"), WithCluster()) clusterB.SetAttributeString("label", "Cluster B") clusterA. @@ -99,24 +99,49 @@ func main() { } ``` -The attributes sub-package has all supported keys defined as variables, and can +The constants sub-package has all supported keys defined as variables, and can be used instead of plain strings to avoid both duplication and errors: ```go -graph := dot.NewGraph() -graph.SetAttributeString(attributes.KeyLabel, "a graph") -node := graph.Node("n1") -node.SetAttributeString(attributes.KeyLabel, "a node") -edge := graph.Edge(graph.Node("n2"), graph.Node("n3")) -edge.SetAttributeString(attributes.KeyLabel, "a edge") +package main + +import ( + "os" + "github.com/wwmoraes/dot" + "github.com/wwmoraes/dot/constants" +) + +func main() { + graph := dot.NewGraph() + graph.SetAttributeString(constants.KeyLabel, "a graph") + node := graph.Node("n1") + node.SetAttributeString(constants.KeyLabel, "a node") + edge := graph.Edge(graph.Node("n2"), graph.Node("n3")) + edge.SetAttributeString(constants.KeyLabel, "a edge") + + fd, _ := os.Create("sample.dot") + graph.WriteTo(fd) +} ``` You can also set literals and HTML values using the helper functions: ```go -graph := dot.NewGraph() -graph.Node("n1").SetAttributeLiteral(attributes.KeyLabel, `a left label\l`) -graph.Node("n2").SetAttributeHTML(attributes.KeyLabel, `a bold label`) +package main + +import ( + "os" + "github.com/wwmoraes/dot" + "github.com/wwmoraes/dot/constants" +) + +func main() { + graph := dot.NewGraph() + graph.Node("n1").SetAttributeLiteral(constants.KeyLabel, `a left label\l`) + graph.Node("n2").SetAttributeHTML(constants.KeyLabel, `a bold label`) + fd, _ := os.Create("sample.dot") + graph.WriteTo(fd) +} ``` ## ✍️ Authors diff --git a/docs/attributes/interfaces/Identity.md b/docs/attributes/interfaces/Identity.md new file mode 100644 index 0000000..99d01d4 --- /dev/null +++ b/docs/attributes/interfaces/Identity.md @@ -0,0 +1,14 @@ +--- +title: Identity +description: implemented by values that have an immutable identifier +--- + +# `Identity` + +Implemented by values that have an immutable identifier + +## source + +```go +--8<-- "attributes/Identity.go" +``` diff --git a/docs/attributes/interfaces/Reader.md b/docs/attributes/interfaces/Reader.md new file mode 100644 index 0000000..eab1a31 --- /dev/null +++ b/docs/attributes/interfaces/Reader.md @@ -0,0 +1,14 @@ +--- +title: Reader +description: implemented by attribute-based values that allows reading them +--- + +# `Reader` + +Implemented by attribute-based values that allows reading them + +## source + +```go +--8<-- "attributes/Reader.go" +``` diff --git a/docs/attributes/interfaces/Serializable.md b/docs/attributes/interfaces/Serializable.md new file mode 100644 index 0000000..140c46b --- /dev/null +++ b/docs/attributes/interfaces/Serializable.md @@ -0,0 +1,15 @@ +--- +title: Serializable +description: implemented by values that can be printed as string or written directly into an IO device +--- + +# `Serializable` + +Implemented by values that can be printed as string or written directly into an +IO device. + +## source + +```go +--8<-- "attributes/Serializable.go" +``` diff --git a/docs/attributes/interfaces/Styleable.md b/docs/attributes/interfaces/Styleable.md new file mode 100644 index 0000000..132e3d4 --- /dev/null +++ b/docs/attributes/interfaces/Styleable.md @@ -0,0 +1,14 @@ +--- +title: Styleable +description: implemented by values that support attributes +--- + +# `Styleable` + +Implemented by values that support attributes + +## source + +```go +--8<-- "attributes/Styleable.go" +``` diff --git a/docs/attributes/interfaces/Writer.md b/docs/attributes/interfaces/Writer.md new file mode 100644 index 0000000..642f1d5 --- /dev/null +++ b/docs/attributes/interfaces/Writer.md @@ -0,0 +1,14 @@ +--- +title: Writer +description: implemented by attribute-based values that allows mutating them +--- + +# `Writer` + +Implemented by attribute-based values that allows mutating them + +## source + +```go +--8<-- "attributes/Writer.go" +``` diff --git a/docs/attributes/keys.md b/docs/attributes/keys.md deleted file mode 100644 index 2093579..0000000 --- a/docs/attributes/keys.md +++ /dev/null @@ -1,12 +0,0 @@ -# Keys - -All known [Graphviz attribute names](graphviz-attrs) are defined as constants, -so you can opt-in and use those to prevent typos on your code. They're all plain -`string`s named after the original attribute and prefixed with `Key`, so the -constant for the attribute `label` is `KeyLabel`. - -```go ---8<-- "attributes/keysConstants.go" -``` - -[graphviz-attrs]: https://graphviz.org/doc/info/attrs.html diff --git a/docs/constants/Key.md b/docs/constants/Key.md new file mode 100644 index 0000000..e99d960 --- /dev/null +++ b/docs/constants/Key.md @@ -0,0 +1,15 @@ +--- +title: Key +description: attribute key values +--- + +# `Key` + +All Graphviz known attributes are mapped as `string` constants to prevent typos +and the creation of multiple string literals across the code. + +## source + +```go +--8<-- "constants/Key.go" +``` diff --git a/docs/index.md b/docs/index.md index 9adb76f..7588ccc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ this package is a WIP and will introduce breaking changes while on major version zero. -[![Status](https://img.shields.io/badge/status-active-success.svg)]() +[![Status](https://img.shields.io/badge/status-active-success.svg)](https://github.com/wwmoraes/dot) ![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/wwmoraes/dot) [![Go Report Card](https://goreportcard.com/badge/github.com/wwmoraes/dot)](https://goreportcard.com/report/github.com/wwmoraes/dot) [![GoDoc](https://godoc.org/github.com/wwmoraes/dot?status.svg)](https://pkg.go.dev/github.com/wwmoraes/dot) @@ -19,7 +19,7 @@ implementation focused on generating dot/gv files that [Graphviz](graphviz) can then convert into any of its output formats supported (e.g. png, jpeg, svg, pdf). Dot provides both interfaces and ready-to-use concrete types that represent -[dot language](dotlanguage) resources - namely Graphs, Nodes and Edges, plus all +[dot language](dot-language) resources - namely Graphs, Nodes and Edges, plus all attributes. This package was inspired/initially forked from [emicklei/dot](emicklei-dot), @@ -51,10 +51,13 @@ func main() { graph.Node("n1").SetAttributeString("label", "hello dot!") - graph.Write(os.Create("sample.dot")) + fd, _ := os.Create("sample.dot") + defer fd.Close() + + graph.WriteTo(fd) } ``` [graphviz]: https://graphviz.org -[dotlanguage]: http://www.graphviz.org/doc/info/lang.html +[dot-language]: http://www.graphviz.org/doc/info/lang.html [emicklei-dot]: https://github.com/emicklei/dot diff --git a/docs/interfaces/StyledEdge.md b/docs/interfaces/StyledEdge.md new file mode 100644 index 0000000..6901759 --- /dev/null +++ b/docs/interfaces/StyledEdge.md @@ -0,0 +1,14 @@ +--- +title: StyledEdge +description: implemented by edge values with convenience styling methods +--- + +# `StyledEdge` + +Implemented by dot-compatible edge values which have convenience styling methods + +## source + +```go +--8<-- "StyledEdge.go" +``` diff --git a/docs/interfaces/edge.md b/docs/interfaces/edge.md index 22caa8b..07c6330 100644 --- a/docs/interfaces/edge.md +++ b/docs/interfaces/edge.md @@ -1,7 +1,14 @@ -# Edge +--- +title: Edge +description: implemented by dot-compatible edge values +--- + +# `Edge` Implemented by dot-compatible edge values, with support for attributes. +## source + ```go --8<-- "Edge.go" ``` diff --git a/docs/interfaces/graph.md b/docs/interfaces/graph.md index 3ed434d..da3105f 100644 --- a/docs/interfaces/graph.md +++ b/docs/interfaces/graph.md @@ -1,6 +1,16 @@ -# Graph +--- +title: Graph +description: implemented by dot-compatible graph values +--- + +# `Graph` Implemented by dot-compatible graph values, with support for attributes. +Extends attributes' [Identity](../attributes/interfaces/Identity.md), +[Styleable](../attributes/interfaces/Styleable.md) and +[Serializable](../attributes/interfaces/Serializable.md) interfaces. + +## source ```go --8<-- "Graph.go" diff --git a/docs/interfaces/node.md b/docs/interfaces/node.md index dce9cf0..f8d9659 100644 --- a/docs/interfaces/node.md +++ b/docs/interfaces/node.md @@ -1,7 +1,14 @@ -# Node +--- +title: Node +description: implemented by dot-compatible node values +--- + +# `Node` Implemented by dot-compatible node values, with support for attributes. +## source + ```go --8<-- "Node.go" ``` diff --git a/docs/types/GraphOptionFn.md b/docs/types/GraphOptionFn.md new file mode 100644 index 0000000..7cafff6 --- /dev/null +++ b/docs/types/GraphOptionFn.md @@ -0,0 +1,50 @@ +--- +title: GraphOptionFn +description: functor that mutates graph options +--- + +# `GraphOptionFn` + +Implemented by functor values that set properties on a `GraphOptions` instance, +which are then used by `Graph`s `NewGraph`/`Graph.Subgraph` to configure new +[sub]graphs. + +A `nil` error is expected as a return value if the functor has successfully set +the options it is intended to. + +These functors are usually returned by `With*` functions that are free to accept +any parameters to be used within the functor, e.g. + +```go +func WithMyOptions(id string) GraphOptionFn { + return func(options GraphOptions) error { + // use the given id + options.SetID(id) + // always create as strict + options.SetStrict(true) + // use undirected (graph) instead of the default directed (digraph) + options.SetType(GraphTypeUndirected) + + return nil + } +} +``` + +then it can be used as + +```go +graph, _ := dot.NewGraph(WithMyOptions("some-id")) +``` + +## implementation + +```go +// GraphOptionFn is a functor that mutates graph options +type GraphOptionFn func(GraphOptions) error +``` + +## source + +```go +--8<-- "Graph.go" +``` diff --git a/mkdocs.yml b/mkdocs.yml index a624fe1..2167936 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,6 +14,7 @@ theme: - navigation.instant - navigation.tabs markdown_extensions: +- meta - admonition - pymdownx.tabbed - pymdownx.superfences