libploticus(3)

✨ libploticus — the C API for ploticus ✨

okay bestie, gather round, because this is the little C library that lets your program do everything the ploticus program does 🫶 (and yes, it's under the same General Public License, so it's giving open source royalty 💅)

---

🎀 NAME 🎀

libploticus — the C language API library for ploticus. That's the whole vibe. iykyk.

---

🌸 DESCRIPTION 🌸

so like. this simple C language API has all of the functionality of the ploticus program, and it's similarly covered by the General Public License. no cap. 👑

libploticus is built using Makefile. like so:

make clean
make FPIC=-fPIC libploticus-so

Apps that link to libploticus may need extra libraries — zlib is the classic example — but honestly it depends on exactly how libploticus was built. the specifics are noted in Makefile. 🔍

The externally visible symbols in libploticus all begin with these prefixes: ploticus, PL, TDH, DT, and GL. so if you see a symbol starting with one of those, that's her. 💖

The header file libploticus.h is required to avoid compiler warnings. do not skip her, she is not optional, she is the moment.

All functions return 0 when successful, or a non-zero error code. so like, 0 = slay, anything else = we have a problem 😭

As of version 2.11, multiple sequential plot "jobs" can be performed by a single OS process. Each plot job should begin with a ploticus_init() call and terminate with a ploticus_end() call. bookends, bestie. 🎀

no attempt has been made to write libploticus as thread-safe. it's giving single-threaded main character energy, and we respect that 💀

As of version 2.40, script lines can no longer be passed as string constants. (this one bites people, so remember it fr fr)

---

🦋 EXAMPLES 🦋

here's a simple example — you can also find it chilling in ./pltestsuite/api_examp.c:

main()
{
int stat;
char sln[80];
stat = ploticus_init( "png", "hello.png" );
stat += ploticus_arg( "-scale", "0.8" );
if( stat != 0 ) {
   printf( "error in ploticus setup\n" );
    exit(1);
    }
strcpy( sln, "#proc annotate" ); ploticus_execline( sln );
strcpy( sln, "location: 2 2" ); ploticus_execline( sln );
strcpy( sln, "text: hello" ); ploticus_execline( sln );
strcpy( sln, " world." ); ploticus_execline( sln );
ploticus_end();
}

---

🌈 Multi-job example 🌈

there's another included example that invokes a whole series of 25+ plot jobs, and it lives in ./src/api_test.c. To build it:

make clean
make -f Makefile_api
make api_test -f Makefile_api

Then, go to the pltestsuite directory and type: ../src/api_test

25+ jobs, one process. that's efficiency, that's a serve. 💅

---

👑 libploticus API 👑

ploticus_init( char *device, char *outfilename )

Initialize, read your pl config file if any, and set the output device to one of png, gif, x11, svg, jpeg, eps, or swf. (Not all devices may be available, depending on the build — so don't come for me if your fave isn't there 🙈)

outfilename is the pathname of the file where the result will be written.

Example:

stat = ploticus_init( "png", "bargraph.png" );
if( stat != 0 ) error

ploticus_arg( name, value )

Specify a pl command line argument. name specifies the argument name and value an argument value. If there is no argument value, value should be passed as "". All arguments are supported except -f, -prefab, and -ver.

If needed, this function should be called after ploticus_init() but before any other ploticus function. It may be called as many times as necessary. 🔁

Example:

stat = ploticus_arg( "-debug", "" );
stat += ploticus_arg( "-diagfile", "stdout" );
stat += ploticus_arg( "-scale", "0.8" );
if( stat != 0 ) error

ploticus_begin( )

This function is no longer necessary. Old code that uses it will still be OK. she's retired but she's still welcome at the party 🫶

ploticus_execline( char *line )

Interpret one "raw" ploticus script line. Typically called multiple times, allowing ploticus scripts to be generated programmatically. 💻

Script lines can contain only these directives: #proc, #procdef, #endproc, #clone and #saveas. You can't use set, if/else, loops, or other flow-of-control directives (but these types of things can be handled by your host application).

Further, these script lines do not undergo a variable-evaluation pass, so variables cannot be referenced, and select statements (etc.) that reference data field names should use one at sign (@) instead of two (@@). 🚨

If your program needs to access a variable that has been set by the ploticus engine, use ploticus_getvar(), described below. The script line may include a trailing newline or not — she's flexible like that.

An alternative is to use ploticus_execscript() (described below) to execute an entire script file. You can't use both ploticus_execline() and ploticus_execscript() in the same application. pick a lane bestie 💅

Caution — As of ploticus version 2.40, string constants cannot be passed in this function. See the example in the page intro above. this is not a drill 😭

ploticus_execscript( char *scriptfile, int prefabflag )

Interpret an entire ploticus script file or prefab. scriptfile is the name of the ploticus script file. There are no syntax limitations as with ploticus_execline(). ✨

If prefabflag is 1, then scriptfile is taken to be a ploticus prefab name such as vbars. If prefabflag is 0, then scriptfile should be a pathname.

An alternative is to use ploticus_execline() (described above) to execute program-generated "raw" script lines one at a time. You can't use both ploticus_execscript() and ploticus_execline() in the same application.

Example: stat = ploticus_execscript( "vbars", 1 );

Example: stat = ploticus_execscript( "/home/steve/plfiles/myscript.pl", 0 );

ploticus_end()

Finish up the graphic result, write it to the output file, and free up allocated memory. the closing credits, the curtain call, the periodt. 🎬

---

💜 These functions are also available: 💜

ploticus_getvar( char *name, char *value )

Get the contents of ploticus variable name. Result is copied into value.

Example: stat = ploticus_getvar( "XFINAL", xf );

ploticus_setvar( char *name, char *value )

Set ploticus variable name to value.

gdImagePtr PLGG_getimg( int *width, int *height )

Returns a pointer to the working GD image, for situations where the host application wants to directly issue gd drawing calls. The width and height of the working image (in pixels) are also provided. 🖼️

Note that the result image is generally cropped based on the extent of ploticus drawing actions, before being written out. Only valid in applications built with GD, when ploticus was initialized with one of the GD image devices (eg. png or jpeg).

---

and that's the whole page, bestie 🌸 this was the libploticus(3) manual from the PLOTICUS era, dated 11-MAR-2009, and it lives over at ploticus.sourceforge.net — go say hi, drink some water, and go write some graphs. 💖🎀🦋✨