Example usage of compiler:
// Generate a png
daya myfile.daya output.png
// Generate an svg
daya myfile.daya output.svg
// Generate only the intermediary dot
daya myfile.daya output.dot
daya is a tool and library to convert from the .daya format to regular .dot, .png or .svg.
The daya-format is intended to allow for rapid diagramming from text sources. Mostly relationship-like diagrams such as UML's activity- and component-diagrams etc. There are currently no plan to add features for sequence-diagrams and such.
It can be thought of as "a subset of dot with custom types" (*). "Type" here are, due to the visual nature of it all, more comparable to CSS classes than types from strictly typed programming languages: they provide templates for how different parts shall appear.
The subset of features, attributes and such is highly opiniated, and very much subject to change as we move toward v1.0.
(*): This is also to be read as; There are many, many diagram-situations which are not intended to be solved by daya.
Prerequisite: have graphviz (https://graphviz.org/download/) installed and dot available in path on your system.
Create a .daya file - e.g "gettingstarted.daya":
// Create one or more node types
node User;
node System;
// Create one or more edge types
edge controls;
// Create instances based on node types
emperor: User;
deathstar: System;
// Create relationships based on instances and edge types
emperor controls deathstar;
then run: daya gettingstarted.daya gettingstarted.png
to create a diagram and save it as output.png for your viewing pleasures:
file: common_types.daya:
// Define common node-types
node Interface {
label="<Interface>";
shape=diamond;
fgcolor=#666666;
bgcolor=#ffddaa;
}
node Module {
label="[Module]";
shape=box;
fgcolor=#000000;
bgcolor=#ffffff;
}
// Define edge-/relationship-types
edge implements {
label="Implements";
edge_style=dashed;
target_symbol=arrow_open;
}
edge depends_on; // rely on defaults
edge relates_to {
source_symbol=arrow_open;
target_symbol=arrow_open;
}
file: mygraph.daya
// imports the file as described above. Limitation: path can't contain newline
@common_types.daya
// Set title of diagram
label="My example diagram";
// Declare the module-instances, optionally grouped
IIterator: Interface {
note="You can add notes to instances";
}
group Core {
note="You can add notes to groups";
// Groups are by default label-less (for now)
label="Core";
MySomething: Module;
MyElse: Module;
}
SomeDependency: Module {
// An instantiation can override base-node fields
bgcolor="#ffdddd";
}
// Describe relationships between modules
MySomething implements IIterator;
MySomething depends_on SomeDependency;
MySomething relates_to MyElse {
// A relationship can override base-edge fields
target_symbol=arrow_filled;
}
Result:
Types of statements:
-
Declare a node-type:
// Using only default properties node NodeType; // or override particular properties node OtherNodeType { label="Custom label"; shape=diamond; }
-
Declare an edge-type
// Using only default properties - a simple, one-directional arrow when used in a relationship edge owns; // or override particular properties - to render e.g a two-way arrow edge twowaydataflow { source_symbol=arrow_filled; target_symbol=arrow_filled; }
-
Create a specific instance of a node
// Will inherit the properties of the given node type myinstance: NodeType; // And optionally override particular ones for this given instance otherinstance: OtherNodeType { shape=circle; }
-
Specify a relationship between two node-instances using an edge
// Using the default style of the particular edge myinstance owns otherinstance; // Or override particular properties for the edge used in this given relationship otherinstance twowaydataflow myinstance { label="Overridden label for edge"; }
For the different types there are a set of allowed parameters that can be specificed:
- For node or instance:
- label: string - supports in-file newlines or \n
- bgcolor: string/#rrggbb, forwarded directly to dot.
- fgcolor: see bgcolor.
- shape: string, forwarded directly to dot: https://graphviz.org/doc/info/shapes.html
- for edge or relationship:
- label: string
- source_symbol: none|arrow_filled|arrow_closed|arrow_open. default: none
- target_symbol: see source_symbol. default: arrow_open
- edge_style: solid|dotted|dashed|bold. default: solid
- An instance automatically inherits the parameters of their node-type. The labels are concatinated with a newline, the remaining fields are overridden.
- If no label is specified, the name is used
- The parameters of an edge can be overridden pr relationship-entry
See releases in repo, or Build-section below.
To install a release, download the platform-appropriate archive, decompress it, and put the resident daya-binary somewhere in your path.
Development is done using quite recent zig 0.10.x builds.
Build and run (from /compiler):
$ zig build run -- --help
or (e.g.) for installation on Unix-like systems (from /compiler):
$ zig build -Drelease-safe --prefix /usr/local
Run tests for libdaya (from /libdaya):
$ zig build test
The system is split into the following components:
- Compiler library (/libdaya) - the core compiler, can be linked into e.g compiler exe, web service, and possibly in the end as WASM to make the web frontend standalone.
- Compiler executable (/compiler)
- Web service (not started)
- Web frontend (not started)
The main logic of the daya-compiler is organized as a library located under /libdaya. Then there's a simple executable-wrapper located under /compiler.
The core component of it all. Provides functionaly to parse .daya, validate the results, output valid .dot + eventually directly execute system-installed dot to generate a graphical representation of the diagram.
Two parts:
- An endpoint which takes daya and returns dot, PNG or SVG.
- Provider of the static frontend
Minimal, single-page, input-form to provide daya data and desired output-format (dot, png, svg).
...
- Overall:
- Value rapidness and sensical defaults over exact control
- Internals:
- Reproducible builds - as far as possible, ie.: up until dot
- If the compiler hasn't complained, then dot shall succeed. ie.: if the compiler hasn't detected an error, then the intermediary dot-data shall be valid.
- Integrate dot / libdot statically linked
- including libs for png and svg?
- Ensure all include-paths are relative to the containing file.
- Currently a lot of the defaults is handled within dot.zig - this is error-prone if we were to change graphing-backend
- Support lifting notes to top level of generated doc? E.g. now, if added to an instance wihtin a group, the note also gets rendered within the same group
- Support multiple files as input (glob?) + a parameter to specify output-format, which will reuse the respective input-names with added extension for output
- Design and implement scoping strategy
- Support monitor/auto-build?
- .daya
- TBD: Implement more advanced (composed) shapes? E.g. an UML-like class with sections?
- Include-functionality:
- Need to explore specific use cases to determine full functionality set here. Leaves as-is for now (in-place + common global scope).
- Reconsider scoping to avoid unwanted collisions between subdiagrams + but still accommodate convenient definition-reuse.
- Explicitly define behaviour wrt duplicate definitions; shall the latter be invalid behaviour, or shall they be fused? Either simply adding children, or explicitly checking for type and override values.
- Simplify syntax: allow } as EOS. Don't require quotes around #-colors. Consider removing ; alltogether. Nl can serve the same purpose.
- Finish v1 daya-syntax: what is scope?
- Ensure compilator supports entire daya-syntax
- Lower importance:
- Implement web service
- Implement frontend
- Nice-to-haves:
- Accept a list of "instantiations" to only render whatever relates to them. Accept "degrees of separation" as well?
- Support "playback"-functionality? Render node-by-node as they are instantiated, ordered by source?
- Mode to allow anonymous types? E.g. don't require predefined nodes/edges, more simular to how dot behaves.
- Allow edges to specify valid source/target-node types?
- graphviz - daya currently uses graphviz/dot as the low level graph tool