This issue tracks the API stability of each package for the 1.0 release.

• dot: not yet stable.
• dot/ast: stable as of commit bfd11f7.

Hi Robin,

I can tell that you are a big fan of gocc. Would you share your opinion on BNF based parsing vs Ragel, from which the blogger claimed that, "It seems that there is a fair variety of tools designed to make writing Lexers, Scanners and Tokenizers easier, but Ragel has a reputation for being simple and consistently producing the fastest final code"

PS. you can find out more about Ragel here if you want to.

To stress test the lexer and parser generated from the DOT grammar, the test cases from the official Graphviz project will be downloaded and parsed.

The intention is to implement a script which downloads these test cases from the graphviz repository, and converts them to UTF-8 encoding. To verify the read and write capabilities of the library, these test files will be parsed and the resulting graphs will be pretty-printed in DOT format and compared against the original test files, ignoring separating whitespaces.

• Read support (parse test files)
• Write support (pretty-print decoded graphs)
• Generate PNG images from the input test DOT files and the output DOT files, and compare these images pixel by pixel.
• Configure Travis to retrieve the test cases using this script

Future ambition.

• Round-trip (validate pretty-printed output vs. original input, ignoring separating spaces)

The DOT parser has been merged with the gonum graph project.

See https://github.com/gonum/graph/issues/9#issuecomment-287614432 for background discussion, and gonum/graph#198 for the PR tracking its inclusion.

The graphism/dot repository will remain for the time being. Primarily to give current users a time to update their import paths.

For active development, the new home of graphism/dot is the gonum/graph repository, under the import path formats/dot.

-import "github.com/graphism/dot"
+import "github.com/gonum/graph/formats/dot"

The PR gonum/graph#198 has now been merged, and graphism/dot has found its new home at gonum/graph/formats/dot. The code is dual licensed, both in public domain (CC0) and BSD, and users are free to choose whichever is better suited for them.

My understanding is that the Gocc compiler kit is used to generate lexers and parsers from the BNF grammar of the DOT file format.

If so, would you think it is a good idea not to enforce this Gocc dependency to dot users by separating the building process into a different package, while dot only makes use of the generated code? It's like there are two level of dependencies as well for Debian packages -- the dependencies to build it and the dependencies to run it, which has far less dependencies than that of building it, most of the time.

This is a meta issue to discuss various design decisions related to the DOT package.

NOTE: This section is under construction, and will be revised based on continuous discussions, so feel free to join.

Aim and Objectives

The aim of this project is to create a general purpose package for accessing Graphviz DOT files, including both read and write support. To achieve this aim, a set of objectives have been identified.

• 1. Write a BNF grammar for the DOT file format and use Gocc to generate lexers and parsers.
• 2. Read support. Implement a translation from DOT AST to generic graph data structures.
• 3. Write support. Provide a means of translating generic graph data structures into DOT files (potentially using DOT ASTs which knows how to pretty-print themselves).
• 4. Read support. Support translating into gonum graphs
• 5. Write support. Support translating out of gonum graphs

Non-goals

An explicit non-goal of this project is to implement a specific graph data structure. Rather, it is intended to allow support for translating into and out of various graph data structures. We should make sure to investigate the feasibility of utilizing the gonum/graph package as the generic graph data structure. Where ever the graph data structure is defined, it should be as part of another repository, not the DOT repository. It is possible that a graphism/graph repo will be created for this purpose.

Public domain

The source code and any original content of this repository is intended to be released into the public domain. Anyone wishing to join the project are kindly asked to consider releasing their contributions into the public domain.

The contents of bar.go is hosted on play.golang.org.

Contents of a.dot:

digraph {
    A -> A
}

$ go run bar.go a.dot
panic: simple: adding self edge

Hi Robin ,

Hope that when you are achieving your Aim and Objectives, you will also bear in mind how the package can be used.

One thing specific comes into my mind is the ability to break big graphs apart into smaller ones, as nowadays, any (automatically generated) chart can be super big, which makes viewing such graphs impractical. Take this automatically generated chart for e.g., it is just too big to be comprehensible.

Just keep a record here so that you can refer back later on when time allows. If you want to tackle it yourself, here is a sample soure and how it looks. Else, I'll build one myself on top of your dot package.

BTW, breaking big graphs apart into smaller clusters is a hard problem. I don't have the sufficient graph theory knowledge to do it the "proper way", but I do have thought of some easy tricks that will/would make it work.

Happy hacking.