<commit_before>\section{Using the output drivers}
\label{sec:drivers}

If an application decides to avail itself of the code generators
in the \gviz\ libraries, the simplest way is to pass a graph
which has been laid out to the function \verb+dotneato_write+.
This will generate and write the appropriate graphics instructions.

The \gviz\ architecture uses a data structure {\tt GVC\_t} to
define a rendering environment or context. Among other parameters,
this specifies what output formats are created and in which files.
A single {\tt GVC\_t} value can be used with multiple graphs.
An instance of an environment can be created by a call to
\begin{verbatim}
    extern GVC_t *gvNEWcontext(char **info, char *user);
\end{verbatim}
The first argument is an array of 3 character pointers
providing version information; see Appendix~\ref{sec:info} for a
description of this data. The second argument is a string giving a
name for the user. If desired, the application can call the library
function {\tt username} to obtain this value.

For convenience, the \gviz\ library provides a simple way to 
create an environment:
\begin{verbatim}
    extern GVC_t *gvContext();
\end{verbatim}
This uses the {\tt Info} created when \gviz\ was built, plus
an empty string for the user's name.

To initialize the environment, the application should
call the function \verb+dotneato_initialize+ :
\begin{verbatim}
  extern void dotneato_initialize(GVC_t* gvc, int argc, char* argv[]);
\end{verbatim}
This function takes the environment value, plus an array of strings.
It calls {\tt aginit} to initialize the \graph\ library, and then
uses the values in {\tt argv} to set the appropriate values in {\tt gvc}.
These strings should be the flags commonly accepted by the various
\gviz\ programs such as {\tt "-T"} and {\tt "-o"}.

For example, the application can use a synthetic argument list
\begin{verbatim}
    GVC_t* gvc = gcContext();
    char* args[] = {
        "command",
        "-Tgif",       /* gif output */
        "-oabc.gif"    /* output  to file abc.gif */
    };
    dotneato_initialize (gvc, sizeof(args)/sizeof(char*), args);
\end{verbatim}
to specify {\tt GIF} output written to the file {\tt abc.gif}.
Another approach is to use the program's actual argument list, 
after removing flags not handled by \gviz.
 
Most of the information is stored in {\tt gvc} for use later. However,
if the {\tt argv} array contains non-flag arguments, these are taken
to be input files and are stored in {\tt char* Files[]}. This is a
{\tt NULL}-terminated array of all the non-flag values.

Sometime before calling \verb+dotneato_write+, the application
needs to bind the environment and graph together. For this, it uses
the function:
\begin{verbatim}
  extern void gvBindContext(GVC_t* gvc, Agraph_t* g);
\end{verbatim}
 
With this setup, and after a call to a layout algorithm, the
application can generate output by calling \verb+dotneato_write+:
\begin{verbatim}
  extern void dotneato_write (GVC_t *gvc);
\end{verbatim}
This function relies on a variety of implicit parameters which
are used to control the concrete representation. Most of these are
specified as graph attributes. These are noted in 
Tables~\ref{tab:nattr_geom}, \ref{tab:eattr_geom} and
\ref{tab:gattr_geom}.

If an application uses \verb+dotneato_write+,
it should afterwards call \verb+dotneato_eof+. 
This tells the code generator
that output is finished, so it can emit any needed trailers.
If appropriate, this can be achieved by a call to \verb+dotneato_terminate+,
which invokes \verb+dotneato_eof+ and then exits with an exit value reflecting
any errors that arose in using the \gviz\ libraries. 

The Appendices~\ref{sec:simple}, \ref{sec:dot}, and \ref{sec:demo}
show how all of these pieces fit together.

<commit_msg>Update libguide to reflect plug-in architecture<commit_after>\section{The \gviz\ context}
\label{sec:gvc}

Up to now, we have used a \gviz\ context \gvc\ without
considering its purpose. As suggested earlier, this value is used
to store various layout information that is independent of a particular
graph and its attributes. In particular, it maintains lists of the
available layout algorithms and renderers; it also records the most recent
layout algorithm applied to a graph. It can be used to specify multiple
renderings of a given graph layout into different associated files.
It is also used to store various global information used during
rendering.

A single \gvc\ value can be used with multiple graphs, though
with only one graph at a time. In addition, if {\tt gvLayout()}
was invoked for a graph and \gvc, then {\tt gvFreeLayout()} should
be called before using {\tt gvLayout()} again, even on the same graph.
 
An instance of a \gvc\ can be created by a call to
\begin{verbatim}
    extern GVC_t *gvNEWcontext(char **info, char *user);
\end{verbatim}
The first argument is an array of three character pointers
providing version information; see Section~\ref{sec:info} below for a
description of this data. The second argument is a string giving a
name for the user. If desired, the application can call the library
function {\tt gvUsername()} to obtain this value. These strings
are stored in the \gvc\ and used in various messages and comments.

For convenience, the \gviz\ library provides a simple way to 
create a context:
\begin{verbatim}
    extern GVC_t *gvContext();
\end{verbatim}
which is what we have used in the examples shown here.
This uses version information created when \gviz\ was built, plus
the value returned by {\tt gvUsername()}.

One can initialize a \gvc\ to record a list of graphs, layout algorithms
and renderers. To do this, the application should
call the function {\tt gvParseArgs}:
\begin{verbatim}
  extern void gvParseArgs(GVC_t* gvc, int argc, char* argv[]);
\end{verbatim}
This function takes the context value, plus an array of strings
using the same conventions as the parameters to {\tt main} function
in a C program. In particular, {\tt argc} should be the number of
values in {\tt argv}. If {\tt argv[0]} is the name of one of the
layout algorithms, this will be bound to the \gvc\ value and used
at layout time.
The remaining {\tt argv} values, if any, are interpreted exactly like
the allowed command line flags for any \gviz\ program.
Thus, {\tt "-T"} can be used to set the output type, and {\tt "-o"}
can be used to specify the output files.

For example, the application can use a synthetic argument list
\begin{verbatim}
    GVC_t* gvc = gcContext();
    char* args[] = {
        "dot",
        "-Tgif",       /* gif output */
        "-oabc.gif"    /* output to file abc.gif */
    };
    gvParseArgs (gvc, sizeof(args)/sizeof(char*), args);
\end{verbatim}
to specify a dot layout in {\tt GIF} output written to the file {\tt abc.gif}.
Another approach is to use a program's actual argument list, 
after removing flags not handled by \gviz.
 
Most of the information is stored in a \gvc\ value for use during
rendering. However,
if the {\tt argv} array contains non-flag arguments, i.e., strings
after the first not beginning with {\tt "-"}, these are taken
to be input files defining a stream of graphs to be drawn. 
These graphs can be accessed by calls to {\tt gvNextInputGraph}.

Once the \gvc\ has been initialized this way, the application can
call {\tt gvNextInputGraph} to get each input graph in sequence, and
then invoke {\tt gvLayoutJobs} and {\tt gvRenderJobs}
to do the specified layouts and renderings. See
Appendix~\ref{sec:dot} for a typical example of this approach.

We note that {\tt gvLayout} basically attaches the graph
and layout algorithm to the \gvc, as would be done by
{\tt gvParseArgs}, and then invokes {\tt gvLayoutJobs}. A similar
remark holds for {\tt gvRender} and {\tt gvRenderJobs}.
 
\subsection{Application-specific data}
\label{sec:info}

When possible, the code generators in the library log how an image file
was created in the output file. To do this, they rely on 
the application providing an array 
\begin{verbatim}
    extern char* Info[3];
\end{verbatim}
giving the desired version information.
The three strings should be the name of the application, the version
of the application, and a build date. For example, \dot\ might provide
\begin{verbatim}
    char *Info[] = {
        "dot",              /* Program */
        "1.8.10",           /* Version */
        "16 Dec 2006"        /* Build Date */
    };
\end{verbatim}


{'fraction_non_alphanumeric': 0.079625014833274, 'fraction_numerical': 0.0015426604960246827, 'mean_word_length': 3.9228971962616823, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4405911', 'n_tokens_mistral': 2422, 'n_tokens_neox': 2361, 'n_words': 1224}