oorexx-gnuplot-subcom

A Gnuplot subcommand environment (ADDRESS) for Open Object Rexx.

Description

This is a binary C++ extension that registers a high-performance "gnuplot" subcommand environment in Open Object Rexx.

It allows Rexx scripts to direct commands to Gnuplot seamlessly using the address gnuplot syntax.

Gnuplot is a portable command-line program that can create 2D and 3D plots of functions, data, and data fits.

Features

• Dual workflow: generates standalone plot files or controls Gnuplot interactive sessions.
• Direct Array Plotting: plots data stored in Open Object Rexx Array objects.
• Cross-Platform: runs on POSIX operating systems and Windows.

Architecture

This library registers a native subcommand environment (gphost) globally within the ooRexx interpreter:

• When you load the library via ::requires "rxgnuplot" LIBRARY, a persistent pipe to Gnuplot is initialized.
• Any string sent to the gnuplot address (e.g., plot sin(x)) is piped directly to the active Gnuplot process in real-time.
• When the Rexx script ends, the pipe is safely closed and cleaned up.

Requirements

• Open Object Rexx 5
• Gnuplot
• CMake (for compiling from source)

Status

This project is currently a Work In Progress (WIP).

At this stage, the subcommand environment has only been built and tested successfully on Linux.

Limitations

• One-way Communication: The pipe is write-only.

  Commands are sent to Gnuplot, but you cannot capture Gnuplot's standard output directly back into Rexx variables (though Gnuplot will still output errors and interactive windows normally on your screen).

Installation

From precompiled binaries

If you downloaded a precompiled release zip (oorexx-gnuplot-subcom-[platform]-v*.zip):

1. Extract the binary file:

   • Linux: librxgnuplot.so
   • macOS: librxgnuplot.dylib
   • Windows: rxgnuplot.dll

2. Place the binary in your current working directory or in a directory included in your system's shared library path.

Compiling from source

1. Clone the repository:

   git clone https://github.com/sparrac/oorexx-gnuplot-subcom.git
   cd oorexx-gnuplot-subcom

2. Build using CMake:

   cmake -B build
   cmake --build build --config Release

3. It will create a binary inside the directory build:

   • Linux: librxgnuplot.so
   • macOS: librxgnuplot.dylib
   • Windows: rxgnuplot.dll

4. Place the binary in your current working directory or in a directory included in your system's shared library path.

Quick Start

#!/usr/bin/env rexx
-- demo.rex
-- Simple demo

address gnuplot
say 'address() =' address()

-- Creating a GIF
say 'Writing animation...'
'set terminal gif animate delay 100'
'set output "fourier_anim.gif"'
'set xrange[-5:5]'
'set yrange[-2:2]'
'set title "Fourier animation"'

f = '0'

do i = 1 to 100
  f = f '+' 'sin(' i '*x)'
  'plot' f 'notitle'
end

-- Creating a PNG
'reset'
'set terminal png'
'set output "scatterplot.png"'
'plot "-"'
'2 3'
'4 5'
'5 6'
'e'

-- GUI interface
'reset'
'set terminal wxt enhanced'
'plot exp(x)'

say 'Press Enter to exit and close the plot window...'
parse pull .

exit

::requires "rxgnuplot" LIBRARY

Reference

Once the rxgnuplot library is required, the gnuplot environment is registered. You can redirect any command block using:

address gnuplot
'set grid'
`plot sin(x)`

Every command sent to Gnuplot returns a standard Rexx return code (RC):

• 0 (RXSUBCOM_OK): Command was successfully sent down the pipe.
• Non-zero (RXSUBCOM_FAILURE): The Gnuplot process/pipe is not open or has crashed.

License

This project is distributed under the terms described in the LICENSE file.

Author

Salvador Parra Camacho

GitHub: https://github.com/sparrac