Zangle is a literate programming tool for extracting code fragments from markdown and other types of text documents into separate files ready for compilation.
NOTE: Currently zangle only supports markdown.
- minimal requirements:
- 0.11.0-dev.4410+76f7b40e1 or higher
$ zig build -Drelease
Let book/ be a directory of markdown files.
Tangle all files within a document
$ zangle tangle book/
List all files in a document
$ zangle ls book/
Render the content of a tag to stdout
$ zangle call book/ --tag='interpreter step'
Render a graph representing document structure
$ zangle graph book/ | dot -Tpng -o grpah.png
Render a graph representing the structure of a single file output
$ zangle graph book/ --file=lib/Linker.zig | dot -Tpng -o grpah.png
Find where given tags reside within output files (TODO)
$ zangle find README.md --tag='parser codegen' --tag='command-line parser'
Create a new literate document from existing files (TODO)
$ find src lib -name '*.zig' | zangle init build.zig --stdin > Zangle.md
This project fetches the real package from sr.ht using the new zig package manager however most options are the same as
the init-exe template with a few minor changes. The general structure follows:
const std = @import("std");
pub fn build(b: *std.Build) void {
[[declare release and target options]]
[[import zangle from the dependency list, set target parameters, and install the artifact]]
[[setup a run command such that it can be tested without having write the path to the binary in zig-out]]
}For the target options, .ReleaseSafe was chosen such that the program would panic as soon as it invokes safety-checked
undefined behaviour.
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{
.preferred_optimize_mode = .ReleaseSafe,
});The package is hosted on sr.ht as a sub project of a game project which uses zangle to document every design choice made for all code included in the final game.
.{
.name = "zangle",
.version = "0.3.0",
.dependencies = .{
.zangle = .{
.url = "https://git.sr.ht/~tauoverpi/levy/archive/b449d537902961e4d5d7704378f00655068d5cf1.tar.gz",
},
},
}In build.zig, the real zangle is loaded as a dependency and set to follow the local target and optimization
configuration.
const dep = b.dependency("zangle", .{});
const zangle = dep.artifact("zangle");
zangle.target = target;
zangle.optimize = optimize;Then installed with b.installArtifact() which also ensures that the executable is built upon invoking zig build.
b.installArtifact(zangle);Finally, testing out zangle should require no more than zig build run to invoke it.
const run_cmd = b.addRunArtifact(zangle);
run_cmd.step.dependOn(b.getInstallStep());
if (b.args) |args| {
run_cmd.addArgs(args);
}
const run_step = b.step("run", "Run the app");
run_step.dependOn(&run_cmd.step);This concludes the example zangle document with two files written where one included other tags.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent