first commit
This commit is contained in:
commit
f7fd0b587f
4 changed files with 373 additions and 0 deletions
7
.gitignore
vendored
Normal file
7
.gitignore
vendored
Normal file
|
@ -0,0 +1,7 @@
|
|||
# testing files
|
||||
build
|
||||
build.ninja
|
||||
ngen.toml
|
||||
tree.c
|
||||
tree.pdf
|
||||
tv.c
|
165
LICENSE.txt
Normal file
165
LICENSE.txt
Normal file
|
@ -0,0 +1,165 @@
|
|||
GNU LESSER GENERAL PUBLIC LICENSE
|
||||
Version 3, 29 June 2007
|
||||
|
||||
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
|
||||
Everyone is permitted to copy and distribute verbatim copies
|
||||
of this license document, but changing it is not allowed.
|
||||
|
||||
|
||||
This version of the GNU Lesser General Public License incorporates
|
||||
the terms and conditions of version 3 of the GNU General Public
|
||||
License, supplemented by the additional permissions listed below.
|
||||
|
||||
0. Additional Definitions.
|
||||
|
||||
As used herein, "this License" refers to version 3 of the GNU Lesser
|
||||
General Public License, and the "GNU GPL" refers to version 3 of the GNU
|
||||
General Public License.
|
||||
|
||||
"The Library" refers to a covered work governed by this License,
|
||||
other than an Application or a Combined Work as defined below.
|
||||
|
||||
An "Application" is any work that makes use of an interface provided
|
||||
by the Library, but which is not otherwise based on the Library.
|
||||
Defining a subclass of a class defined by the Library is deemed a mode
|
||||
of using an interface provided by the Library.
|
||||
|
||||
A "Combined Work" is a work produced by combining or linking an
|
||||
Application with the Library. The particular version of the Library
|
||||
with which the Combined Work was made is also called the "Linked
|
||||
Version".
|
||||
|
||||
The "Minimal Corresponding Source" for a Combined Work means the
|
||||
Corresponding Source for the Combined Work, excluding any source code
|
||||
for portions of the Combined Work that, considered in isolation, are
|
||||
based on the Application, and not on the Linked Version.
|
||||
|
||||
The "Corresponding Application Code" for a Combined Work means the
|
||||
object code and/or source code for the Application, including any data
|
||||
and utility programs needed for reproducing the Combined Work from the
|
||||
Application, but excluding the System Libraries of the Combined Work.
|
||||
|
||||
1. Exception to Section 3 of the GNU GPL.
|
||||
|
||||
You may convey a covered work under sections 3 and 4 of this License
|
||||
without being bound by section 3 of the GNU GPL.
|
||||
|
||||
2. Conveying Modified Versions.
|
||||
|
||||
If you modify a copy of the Library, and, in your modifications, a
|
||||
facility refers to a function or data to be supplied by an Application
|
||||
that uses the facility (other than as an argument passed when the
|
||||
facility is invoked), then you may convey a copy of the modified
|
||||
version:
|
||||
|
||||
a) under this License, provided that you make a good faith effort to
|
||||
ensure that, in the event an Application does not supply the
|
||||
function or data, the facility still operates, and performs
|
||||
whatever part of its purpose remains meaningful, or
|
||||
|
||||
b) under the GNU GPL, with none of the additional permissions of
|
||||
this License applicable to that copy.
|
||||
|
||||
3. Object Code Incorporating Material from Library Header Files.
|
||||
|
||||
The object code form of an Application may incorporate material from
|
||||
a header file that is part of the Library. You may convey such object
|
||||
code under terms of your choice, provided that, if the incorporated
|
||||
material is not limited to numerical parameters, data structure
|
||||
layouts and accessors, or small macros, inline functions and templates
|
||||
(ten or fewer lines in length), you do both of the following:
|
||||
|
||||
a) Give prominent notice with each copy of the object code that the
|
||||
Library is used in it and that the Library and its use are
|
||||
covered by this License.
|
||||
|
||||
b) Accompany the object code with a copy of the GNU GPL and this license
|
||||
document.
|
||||
|
||||
4. Combined Works.
|
||||
|
||||
You may convey a Combined Work under terms of your choice that,
|
||||
taken together, effectively do not restrict modification of the
|
||||
portions of the Library contained in the Combined Work and reverse
|
||||
engineering for debugging such modifications, if you also do each of
|
||||
the following:
|
||||
|
||||
a) Give prominent notice with each copy of the Combined Work that
|
||||
the Library is used in it and that the Library and its use are
|
||||
covered by this License.
|
||||
|
||||
b) Accompany the Combined Work with a copy of the GNU GPL and this license
|
||||
document.
|
||||
|
||||
c) For a Combined Work that displays copyright notices during
|
||||
execution, include the copyright notice for the Library among
|
||||
these notices, as well as a reference directing the user to the
|
||||
copies of the GNU GPL and this license document.
|
||||
|
||||
d) Do one of the following:
|
||||
|
||||
0) Convey the Minimal Corresponding Source under the terms of this
|
||||
License, and the Corresponding Application Code in a form
|
||||
suitable for, and under terms that permit, the user to
|
||||
recombine or relink the Application with a modified version of
|
||||
the Linked Version to produce a modified Combined Work, in the
|
||||
manner specified by section 6 of the GNU GPL for conveying
|
||||
Corresponding Source.
|
||||
|
||||
1) Use a suitable shared library mechanism for linking with the
|
||||
Library. A suitable mechanism is one that (a) uses at run time
|
||||
a copy of the Library already present on the user's computer
|
||||
system, and (b) will operate properly with a modified version
|
||||
of the Library that is interface-compatible with the Linked
|
||||
Version.
|
||||
|
||||
e) Provide Installation Information, but only if you would otherwise
|
||||
be required to provide such information under section 6 of the
|
||||
GNU GPL, and only to the extent that such information is
|
||||
necessary to install and execute a modified version of the
|
||||
Combined Work produced by recombining or relinking the
|
||||
Application with a modified version of the Linked Version. (If
|
||||
you use option 4d0, the Installation Information must accompany
|
||||
the Minimal Corresponding Source and Corresponding Application
|
||||
Code. If you use option 4d1, you must provide the Installation
|
||||
Information in the manner specified by section 6 of the GNU GPL
|
||||
for conveying Corresponding Source.)
|
||||
|
||||
5. Combined Libraries.
|
||||
|
||||
You may place library facilities that are a work based on the
|
||||
Library side by side in a single library together with other library
|
||||
facilities that are not Applications and are not covered by this
|
||||
License, and convey such a combined library under terms of your
|
||||
choice, if you do both of the following:
|
||||
|
||||
a) Accompany the combined library with a copy of the same work based
|
||||
on the Library, uncombined with any other library facilities,
|
||||
conveyed under the terms of this License.
|
||||
|
||||
b) Give prominent notice with the combined library that part of it
|
||||
is a work based on the Library, and explaining where to find the
|
||||
accompanying uncombined form of the same work.
|
||||
|
||||
6. Revised Versions of the GNU Lesser General Public License.
|
||||
|
||||
The Free Software Foundation may publish revised and/or new versions
|
||||
of the GNU Lesser General Public License from time to time. Such new
|
||||
versions will be similar in spirit to the present version, but may
|
||||
differ in detail to address new problems or concerns.
|
||||
|
||||
Each version is given a distinguishing version number. If the
|
||||
Library as you received it specifies that a certain numbered version
|
||||
of the GNU Lesser General Public License "or any later version"
|
||||
applies to it, you have the option of following the terms and
|
||||
conditions either of that published version or of any later version
|
||||
published by the Free Software Foundation. If the Library as you
|
||||
received it does not specify a version number of the GNU Lesser
|
||||
General Public License, you may choose any version of the GNU Lesser
|
||||
General Public License ever published by the Free Software Foundation.
|
||||
|
||||
If the Library as you received it specifies that a proxy can decide
|
||||
whether future versions of the GNU Lesser General Public License shall
|
||||
apply, that proxy's public statement of acceptance of any version is
|
||||
permanent authorization for you to choose that version for the
|
||||
Library.
|
33
README.md
Normal file
33
README.md
Normal file
|
@ -0,0 +1,33 @@
|
|||
# treeviz
|
||||
A header-only C library which uses [graphviz](https://www.graphviz.org/) to
|
||||
visualize recursive data structures.
|
||||
|
||||
This library is intended mostly for debugging purposes, as it can oftentimes
|
||||
be useful to visualize your program's data layout. This is especially true with
|
||||
deeply nested recursive data structures.
|
||||
|
||||
The methods in this library use two functions that end-user must write
|
||||
themselves:
|
||||
|
||||
1. One that iterates over a node's children,
|
||||
1. And another that represents a node's data.
|
||||
|
||||
This design allows the library to work with **any recursive data structure.**
|
||||
As it turns out, these two functions are all you need to generalize the task
|
||||
of visualization.
|
||||
|
||||
## Dependencies
|
||||
You must have graphviz installed, and the `dot` executable in your path. That's
|
||||
it.
|
||||
|
||||
*Optional:* Becuase this library renders your tree to a pdf (for now), it is
|
||||
nice to have a pdf viewer that updates the screen automatically upon an update
|
||||
to the file being viewed. [Zathura](https://github.com/pwmt/zathura) is one such
|
||||
viewer, but there are many available.
|
||||
|
||||
## TODO: write documentation
|
||||
There are some notes in the header file that may guide you before I write the
|
||||
actual docs.
|
||||
|
||||
---
|
||||
Copyright (C) Noah Swerhun under the terms of the LGPLv3 (see LICENSE.txt).
|
168
treeviz.h
Normal file
168
treeviz.h
Normal file
|
@ -0,0 +1,168 @@
|
|||
#ifndef TREEVIZ_H
|
||||
#define TREEVIZ_H
|
||||
|
||||
// TreeViz context. Contains settings for the visualizer functions. This
|
||||
// is wrapped in a struct so you don't have to always pass the same options
|
||||
// to every funcion call. However, if you want to do that, you can use the
|
||||
// `TV_vizl` function.
|
||||
typedef struct TVCtx_T {
|
||||
// Output filename. Should end in `.pdf`
|
||||
char *filename;
|
||||
|
||||
// Function that takes a reference to a node, and returns a string
|
||||
// representing the node's data. The representation should not include any
|
||||
// information about children, just the data stored in the node that the
|
||||
// function was called on.
|
||||
char *(*represent_data)(void *node);
|
||||
|
||||
// A function that takes a node, and iteratively returns each child of the
|
||||
// node on each successive call, setting `done` to 1 when all children have
|
||||
// been processed. Be sure to use `cur_idx` to track the function's progress:
|
||||
// this function will be called in a recursive context, so using static memory
|
||||
// introduces some funny bugs.
|
||||
void *(*next_child)(void *root_node, int *done, int *cur_idx);
|
||||
} TVCtx;
|
||||
|
||||
// Visualize the tree rooted at `root_node`, using the settings found in `ctx`.
|
||||
void TV_vizv(void *root_node, TVCtx *ctx);
|
||||
|
||||
// Visualize the tree rooted at `root_node`, using the settings specifed. See
|
||||
// the `TVCtx` struct.
|
||||
void TV_vizl(void *root_node, char *filename,
|
||||
char *(*represent_data)(void *root_node),
|
||||
void *(*next_child)(void *root_node, int *done, int *cur_idx));
|
||||
|
||||
#endif
|
||||
|
||||
#ifdef TREEVIZ_IMPLEMENTATION
|
||||
#ifndef TREEVIZ_IMPL_ALREADY
|
||||
#define TREEVIZ_IMPL_ALREADY
|
||||
|
||||
#include <assert.h>
|
||||
#include <errno.h>
|
||||
#include <fcntl.h>
|
||||
#include <stdio.h>
|
||||
#include <stdlib.h>
|
||||
#include <string.h>
|
||||
#include <sys/wait.h>
|
||||
#include <unistd.h>
|
||||
|
||||
#define ERRCHECK(...) \
|
||||
if (errno != 0) { \
|
||||
fprintf(stderr, "error: %s (errno %d)\n", strerror(errno), errno); \
|
||||
fprintf(stderr, __VA_ARGS__); \
|
||||
fputc('\n', stderr); \
|
||||
assert(errno == 0); \
|
||||
}
|
||||
|
||||
#define NOT_NULL(x) assert(x != NULL)
|
||||
|
||||
void _TV_write_dot(void *root_node, int fd, TVCtx *ctx, size_t *id) {
|
||||
void *(*next_child)(void *root_node, int *done, int *cur_idx) =
|
||||
ctx->next_child;
|
||||
char *(*represent_data)(void *node) = ctx->represent_data;
|
||||
|
||||
char *repr = represent_data(root_node);
|
||||
|
||||
size_t cur_id = *id;
|
||||
++(*id);
|
||||
|
||||
errno = 0;
|
||||
if (root_node == NULL) {
|
||||
dprintf(fd, "%zu [style=filled,fillcolor=gray,label=\"%s\"];", cur_id,
|
||||
repr);
|
||||
} else {
|
||||
dprintf(fd, "%zu [label=\"%s\"];", cur_id, repr);
|
||||
}
|
||||
ERRCHECK("TreeViz: _TV_write_dot: could not write to pipe");
|
||||
|
||||
free(repr);
|
||||
|
||||
if (root_node == NULL) {
|
||||
return;
|
||||
}
|
||||
|
||||
int done = 0;
|
||||
int iter = 0;
|
||||
while (!done) {
|
||||
void *child = next_child(root_node, &done, &iter);
|
||||
|
||||
errno = 0;
|
||||
dprintf(fd, "%zu->%zu;", cur_id, *id);
|
||||
ERRCHECK("TreeViz: _TV_write_dot: could not write to pipe");
|
||||
|
||||
_TV_write_dot(child, fd, ctx, id);
|
||||
}
|
||||
}
|
||||
|
||||
void TV_vizv(void *root_node, TVCtx *ctx) {
|
||||
int pipe_stdin[2];
|
||||
|
||||
errno = 0;
|
||||
pipe(pipe_stdin);
|
||||
ERRCHECK("TreeViz: TV_vizv: could not create pipe to dot")
|
||||
|
||||
int child_stdin_write = pipe_stdin[1];
|
||||
int child_stdin_read = pipe_stdin[0];
|
||||
|
||||
char o_argument[1024] = "-o";
|
||||
strncat(o_argument, ctx->filename, 1021);
|
||||
|
||||
errno = 0;
|
||||
pid_t pid = fork();
|
||||
ERRCHECK("TreeViz: TV_vizv: could not fork process");
|
||||
|
||||
if (pid == 0) {
|
||||
//// CHILD PROCESS
|
||||
close(child_stdin_write);
|
||||
ERRCHECK("TreeViz: TV_vizv: CHILD: could not close old pipe, write end");
|
||||
|
||||
dup2(child_stdin_read, STDIN_FILENO);
|
||||
ERRCHECK("TreeViz: TV_vizv: CHILD: could not set stdin fileno");
|
||||
|
||||
close(child_stdin_read);
|
||||
ERRCHECK("TreeViz: TV_vizv: CHILD: could not close old pipe, read end");
|
||||
|
||||
char *run = "dot";
|
||||
execlp(run, run, "-Tpdf", o_argument);
|
||||
ERRCHECK("TreeViz: TV_vizv: CHILD: could not exec `%s`.\n\nDo you have "
|
||||
"graphviz installed and in your PATH?\n",
|
||||
run);
|
||||
} else {
|
||||
//// PARENT PROCESS
|
||||
close(child_stdin_read);
|
||||
ERRCHECK("TreeViz: TV_vizv: could not close old pipe, read end");
|
||||
|
||||
dprintf(child_stdin_write, "digraph{node [shape=rect];");
|
||||
ERRCHECK("TreeViz: TV_vizv: could not write to pipe");
|
||||
|
||||
size_t id = 0;
|
||||
_TV_write_dot(root_node, child_stdin_write, ctx, &id);
|
||||
|
||||
errno = 0;
|
||||
dprintf(child_stdin_write, "}");
|
||||
ERRCHECK("TreeViz: TV_vizv: could not write to pipe");
|
||||
|
||||
close(child_stdin_write);
|
||||
ERRCHECK("TreeViz: TV_vizv: could not close old pipe, write end");
|
||||
|
||||
int status;
|
||||
wait(&status);
|
||||
ERRCHECK("TreeViz: TV_vizv: could not wait on child process");
|
||||
if (!WIFEXITED(status) || WEXITSTATUS(status) != 0) {
|
||||
fprintf(stderr, "TreeViz: TV_vizv: dot process failed. "
|
||||
"terminating immediately.\n");
|
||||
assert(status == 0);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
void TV_vizl(void *root_node, char *filename,
|
||||
char *(*represent_data)(void *root_node),
|
||||
void *(*next_child)(void *root_node, int *done, int *cur_idx)) {
|
||||
TVCtx ctx = {filename, represent_data, next_child};
|
||||
TV_vizv(root_node, &ctx);
|
||||
}
|
||||
|
||||
#endif
|
||||
#endif
|
Loading…
Reference in a new issue