foresight_script

foresight_script, interpreter of a gnuplot command subset.

Supported (with gnuplot abbreviations):

• set|unset title|xlabel|ylabel|y2label ["text"], set xrange|yrange|y2range [min:max] (* or empty autoscales an end), set|unset logscale [AXES] (AXES concatenates x, y, y2, e.g. xy2; all when absent), set|unset grid, set|unset key, set output "file", set terminal svg|html [size W,H] [refresh SECONDS];
• set terminal dumb [size COLS,ROWS] [mono|ansi|ansi256|ansirgb] (text, default 79x24 on standard output -), set terminal block [half|quadrants|sextants|braille] [size COLS,ROWS] [mono|ansi|ansi256|ansirgb] (text drawn with Unicode block or Braille characters);
• set|unset multiplot [layout ROWS,COLS] [title "t"]: each plot fills the next panel, settings carry over; without layout each panel lies in its set origin X,Y / set size W,H box (page fractions);
• set xtics|ytics|y2tics [auto|STEP|START,STEP[,END]] [mirror|nomirror] (y2 ticks are off until set), unset xtics|ytics|y2tics, set format [AXES] ["fmt"], unset format, set key [on|off] [left|right|center] [top|bottom|center] [box|nobox] [autotitle [columnhead]|noautotitle], set style data|function STYLE, unset style function, set style line N [lc ...] [lt N] [lw W] [dt N] [pt N] [ps S];
• set datafile separator [whitespace|tab|comma|"chars"], unset datafile [separator]; set samples N[,M];
• plot 'file' [using [X:]Y[:...]] [index N] [every I:J:K:L:M:N] [with STYLE] [title "t"|notitle] [axes x1y1|x1y2] [smooth unique|frequency|fnormal|cumulative|cnormal] [lc [rgb] "color"|N] [lw W] [dt N] [pt N] [ps S], ... ('' repeats the previous file; smooth: see foresight_smooth), STYLE lines|points|linespoints|impulses|steps|fsteps| histeps|dots|yerrorbars|xerrorbars|xyerrorbars|yerrorlines|xerrorlines|xyerrorlines (error bars: x:y:dy or x:y:low:high, x:y:dx:dy or x:y:xlow:xhigh:ylow:yhigh), abbreviated as gnuplot (foresight_style); replot [items]; a using field is a column number or a parenthesized expression, ($2*1e3) (see foresight_expression), or a column header name, "residual"; title columnhead[(N)] titles an item with a column header; ls N, lt N in an item apply a line style, a palette color;
• with boxerrorbars|boxxyerror|candlesticks [whiskerbars [F]]|financebars|boxplot (gnuplot's layouts), set style boxplot [range R|fraction F] [[no]outliers] [pointtype P] [candlesticks|financebars] [medianlinewidth W] [separation S] [labels off|auto|x] [sorted|unsorted];
• with vectors|arrows [head|heads|nohead|backhead] [filled|empty|nofilled], with ellipses [units xy], with polygons, with labels [left|center|right] [rotate by A] [offset X,Y] [point] [tc "c"] (using x:y:N, the text of column N), with sectors (gnuplot's layouts); unset xrange|yrange|y2range autoscales;
• with parallelaxes [at X], set|unset spiderplot, with spiderplot (using Y[:key(N)], an axis per item, a line or polygon per row), set paxis N range [min:max]|tics [...]|label "t", unset paxis N tics, set style spiderplot [fs FILL] [lw W] [pt N] [ps S], set grid spiderplot;
• with boxes (using x:y[:width], from y = 0), with filledcurves [closed|x1|x2|y=V|xy=X,Y] [above|below] (using x:y1:y2 for a band), with rgbimage|rgbalpha (x:y:r:g:b[:a]), set|unset rgbmax V, fs|fillstyle FILL in an item, set style fill FILL (FILL: empty, [transparent] solid [D], pattern [N], border [lc C|-1], noborder), set boxwidth [W] [absolute|relative], unset boxwidth;
• with histograms (using Y[:xtic(N)], the rows at the point numbers 0, 1, ...), set style histogram clustered [gap G]|rowstacked; using ...:xtic(N) / xticlabels(N): the text of column N labels the abscissae, the labels replacing the x ticks;
• plot 'file' [matrix] with image (using x:y:z on a regular grid, or the values of a matrix file), set palette [rgbformulae R,G,B|defined (v c, ...)|gray|color|viridis|positive|negative|maxcolors N], set cbrange [min:max], set|unset cblabel ["t"], set|unset colorbox;
• with circles (using x:y[:r[:start:end]], wedges with angles in degrees); foresight's with pie [donut F] (using Y[:xtic(N)], alone in its panel);
• foresight's panel charts: with gauge range [A:B] [segments N] [format "fmt"], with radar, with rose [linear] (using Y[:xtic(N)]), alone in their panel (several gauges or radars side by side);
• set|unset polar (items theta:r, functions of t over set trange [min:max]), set angles degrees|radians (also the trigonometric functions of the expressions), set|unset theta [right|top|left|bottom] [clockwise|cw| counterclockwise|ccw], set rrange [min:max], set|unset rtics [...] (as xtics), set|unset ttics [[START,]STEP] [format "fmt"], set|unset raxis, set grid [polar [STEP]], set border [MASK] [polar], unset border, set size [square|nosquare|ratio R|noratio] [W,H];
• foresight extensions: set terminal ... theme classic|vfd|lcd [glow|noglow] (any terminal), the colors of a 1980s display (see foresight_theme); fs ... segments N, bars cut into N cells over the y range (foresight_style); plot ... with readout [format "fmt"], the last finite value of the item in seven-segment digits on a glass of fmt (a printf conversion with a field width, %10.3e by default; see foresight_readout), lc its only style option; set readout [on|off] [left|right|center] [top|bottom|center] [horizontal|vertical] [opaque|noopaque] [size H], unset readout;
• a function of x as a plot item, plot sin(x)/x title "sinc" (same options, styles lines, points or linespoints, set style function, lines by default): sampled at set samples points (100) over the x range before its extension to the ticks, the data extent, or [-10:10] with neither; evenly in log x on a log axis.

Anything else is an error naming the command, never silently ignored. Errors are returned (iostat, iomsg with source:line:), not stopped on, so a watch loop can survive a bad cycle.

Source: src/lib/foresight_script.F90

Dependencies

Contents

• line_style_object
• script_object
• init
• run_file
• run_text
• execute
• plot_command
• register_file
• save_output
• set_command
• unset_command
• regular_grid
• fail
• parse_using
• apply_line_style
• parse_every
• after_command
• axes_argument
• style_code
• canonical_style
• change_extension
• extension
• is_multiplot_option
• keyword
• is_word
• next_integer
• next_real
• next_word
• no_more
• columnhead_title
• function_drawable
• is_item_option
• is_line_option
• line_option
• plain_columns
• string_argument
• valid_axes
• to_number

Variables

Name	Type	Attributes	Description
DUMB_CELL	real(kind=R8P)	parameter	Text device cell size [font size].
FUNCTION_STYLES	character(len=*)	parameter	Styles

Derived Types

line_style_object

Line properties: a set style line, or the options of a plot item; unallocated means the default.

Components

Name	Type	Attributes	Description
id	integer(kind=I4P)		Style number.
lc	character(len=:)	allocatable	Color.
lw	real(kind=R8P)	allocatable	Line width.
dt	integer(kind=I4P)	allocatable	Dash type.
ps	real(kind=R8P)	allocatable	Point size.
pt	integer(kind=I4P)	allocatable	Point type.

script_object

Script interpreter state.

Components

Name	Type	Attributes	Description
figure	type(figure_object)		Figure being built.
output	character(len=:)	allocatable	Current output file.
output_set	logical		Output set by set output.
previous_file	character(len=:)	allocatable	File of the last plot item, for ''.
last_plot	character(len=:)	allocatable	Items of the last plot, for replot.
data_files	type(token_object)	allocatable	Data files read, for watching.
live_refresh	integer(kind=I4P)		HTML reload period applied when none is set [s].
multiplot	logical		Inside set multiplot.
advance_pending	logical		A multiplot panel was plotted: the next command
data_style	character(len=:)	allocatable	Default plot style, set style data.
function_style	character(len=:)	allocatable	Default function style, set style function.
autotitle	character(len=:)	allocatable	Untitled items: file (as written), columnhead,
line_styles	type(line_style_object)	allocatable	set style line definitions.
separator	character(len=:)	allocatable	Data cell separators, empty for whitespace.
samples	integer(kind=I4P)		Function samples, set samples.
rgbmax	real(kind=R8P)		Full intensity of RGB image components, set rgbmax.

Type-Bound Procedures

Name	Attributes	Description
execute	pass(self)	Execute one statement.
init	pass(self)	Reset the interpreter.
run_file	pass(self)	Run a script file.
run_text	pass(self)	Run script text.
plot_command	pass(self)	plot.
register_file	pass(self)	Remember a data file.
save_output	pass(self)	Render to the current output.
set_command	pass(self)	set.
unset_command	pass(self)	unset.

Subroutines

init

Reset the interpreter; plots go to output until set output.

subroutine init(self, output)

Arguments

Name	Type	Intent	Attributes	Description
self	class(script_object)	inout		Interpreter.
output	character(len=*)	in		Default output file.

Call graph

run_file

Run the script file.

subroutine run_file(self, file, iostat, iomsg)

Arguments

Name	Type	Intent	Attributes	Description
self	class(script_object)	inout		Interpreter.
file	character(len=*)	in		Script file.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

run_text

Run script text: lines ending in \ continue on the next one; the first error stops the run.

subroutine run_text(self, text, iostat, iomsg, source)

Arguments

Name	Type	Intent	Attributes	Description
self	class(script_object)	inout		Interpreter.
text	character(len=*)	in		Script text.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message, source:line: ....
source	character(len=*)	in	optional	Source name for messages.

Call graph

execute

Execute one statement.

subroutine execute(self, statement, iostat, iomsg)

Arguments

Name	Type	Intent	Attributes	Description
self	class(script_object)	inout		Interpreter.
statement	character(len=*)	in		Statement.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

plot_command

plot items: each a data file or a function with modifiers, comma separated; replaces the previous plot and renders it.

Functions are sampled once all the items are read: their x range depends on the data of the whole plot, as gnuplot. Until then each holds its place (its color, its key row) as an empty series.

subroutine plot_command(self, tokens, text, iostat, iomsg)

Arguments

Name	Type	Intent	Attributes	Description
self	class(script_object)	inout		Interpreter.
tokens	type(token_object)	in		Items tokens.
text	character(len=*)	in		Text the tokens come from, for function titles.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

register_file

Remember file among the data files read (once).

subroutine register_file(self, file)

Arguments

Name	Type	Intent	Attributes	Description
self	class(script_object)	inout		Interpreter.
file	character(len=*)	in		Data file.

Call graph

save_output

Render the figure to the current output; the format follows its extension.

subroutine save_output(self, iostat, iomsg)

Arguments

Name	Type	Intent	Attributes	Description
self	class(script_object)	inout		Interpreter.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

set_command

set options. Full intensity.

subroutine set_command(self, tokens, iostat, iomsg)

Arguments

Name	Type	Intent	Attributes	Description
self	class(script_object)	inout		Interpreter.
tokens	type(token_object)	in		Option tokens.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

unset_command

unset options. Axis number.

subroutine unset_command(self, tokens, iostat, iomsg)

Arguments

Name	Type	Intent	Attributes	Description
self	class(script_object)	inout		Interpreter.
tokens	type(token_object)	in		Option tokens.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

regular_grid

Gather the points (x, y, z) on a regular grid: the sorted distinct finite abscissae xs and ordinates ys, evenly spaced, and the values grid(i, j) at (xs(i), ys(j)), NaN where no point lies; problem if the points do not lie on such a grid.

Attributes: pure

subroutine regular_grid(x, y, z, xs, ys, grid, problem)

Arguments

Name	Type	Intent	Attributes	Description
x	real(kind=R8P)	in		Abscissae.
y	real(kind=R8P)	in		Ordinates.
z	real(kind=R8P)	in		Values.
xs	real(kind=R8P)	out	allocatable	Pixel centre abscissae.
ys	real(kind=R8P)	out	allocatable	Pixel centre ordinates.
grid	real(kind=R8P)	out	allocatable	Values.
problem	character(len=:)	out	allocatable	Problem, empty if none.

Call graph

fail

Set an error.

Attributes: pure

subroutine fail(message, iostat, iomsg)

Arguments

Name	Type	Intent	Attributes	Description
message	character(len=*)	in		Error message.
iostat	integer(kind=I4P)	out		Set to 1.
iomsg	character(len=:)	out	allocatable	Set to message.

Call graph

parse_using

using specification: 1 to 6 colon separated fields, each a column number (0 is the point number) or a parenthesized expression, as in gnuplot.

subroutine parse_using(spec, fields, iostat, iomsg, degrees)

Arguments

Name	Type	Intent	Attributes	Description
spec	character(len=*)	in		Specification.
fields	type(expression_object)	out	allocatable	Fields.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.
degrees	logical	in		Angles of the expressions in degrees.

Call graph

apply_line_style

Apply the line style id to line: its defined properties; an undefined style is the linetype id, as gnuplot.

Attributes: pure

subroutine apply_line_style(styles, id, line)

Arguments

Name	Type	Intent	Attributes	Description
styles	type(line_style_object)	in		Defined styles.
id	integer(kind=I4P)	in		Style number.
line	type(line_style_object)	inout		Line properties.

Call graph

parse_every

gnuplot every point_incr:block_incr:start_point:start_block:end_point:end_block; empty or missing fields keep their defaults (1, 1, 0, 0, no end, no end).

subroutine parse_every(spec, every, iostat, iomsg)

Arguments

Name	Type	Intent	Attributes	Description
spec	character(len=*)	in		Specification.
every	integer(kind=I4P)	out		Fields, ends -1 for none.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

Functions

after_command

Text of statement after its first word.

Attributes: pure

Returns: character(len=:)

function after_command(statement) result(rest)

Arguments

Name	Type	Intent	Attributes	Description
statement	character(len=*)	in		Statement.

Call graph

axes_argument

Optional axes names after a logscale option (default all: xyy2); a base other than 10 is an error.

Returns: logical

function axes_argument(tokens, axes, iostat, iomsg) result(ok)

Arguments

Name	Type	Intent	Attributes	Description
tokens	type(token_object)	in		Option tokens.
axes	character(len=:)	out	allocatable	Axes letters.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

style_code

Style code of a full style name.

Returns: integer(kind=I4P)

function style_code(name) result(code)

Arguments

Name	Type	Intent	Attributes	Description
name	character(len=*)	in		Full style name.

Call graph

canonical_style

Full gnuplot style name of word (full or abbreviated), empty if unsupported.

Attributes: pure

Returns: character(len=:)

function canonical_style(word) result(style)

Arguments

Name	Type	Intent	Attributes	Description
word	character(len=*)	in		Style word.

Call graph

change_extension

file with its extension replaced by ext (appended if none).

Attributes: pure

Returns: character(len=:)

function change_extension(file, ext) result(renamed)

Arguments

Name	Type	Intent	Attributes	Description
file	character(len=*)	in		File name.
ext	character(len=*)	in		New extension.

Call graph

extension

Lower case extension of file, empty if none.

Attributes: pure

Returns: character(len=:)

function extension(file) result(ext)

Arguments

Name	Type	Intent	Attributes	Description
file	character(len=*)	in		File name.

Call graph

is_multiplot_option

Whether the statement is set|unset multiplot ....

Attributes: pure

Returns: logical

function is_multiplot_option(tokens) result(is)

Arguments

Name	Type	Intent	Attributes	Description
tokens	type(token_object)	in		Statement tokens.

Call graph

keyword

Whether word abbreviates full with at least minimum characters, as gnuplot keywords.

Attributes: pure

Returns: logical

function keyword(word, full, minimum) result(match)

Arguments

Name	Type	Intent	Attributes	Description
word	character(len=*)	in		Word.
full	character(len=*)	in		Full keyword.
minimum	integer(kind=I4P)	in		Shortest accepted abbreviation.

Call graph

is_word

Whether word is one of the blank separated words.

Attributes: pure

Returns: logical

function is_word(word, words) result(found)

Arguments

Name	Type	Intent	Attributes	Description
word	character(len=*)	in		Word.
words	character(len=*)	in		Blank separated words.

Call graph

next_integer

Advance i to the next token, which must be an integer.

Returns: logical

function next_integer(tokens, i, value, iostat, iomsg) result(ok)

Arguments

Name	Type	Intent	Attributes	Description
tokens	type(token_object)	in		Tokens.
i	integer(kind=I4P)	inout		Token counter.
value	integer(kind=I4P)	out		Integer.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

next_real

Advance i to the next token, which must be a number.

Returns: logical

function next_real(tokens, i, value, iostat, iomsg) result(ok)

Arguments

Name	Type	Intent	Attributes	Description
tokens	type(token_object)	in		Tokens.
i	integer(kind=I4P)	inout		Token counter.
value	real(kind=R8P)	out		Number.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

next_word

Advance i to the next token, which must be a bare word.

Returns: logical

function next_word(tokens, i, word, iostat, iomsg) result(ok)

Arguments

Name	Type	Intent	Attributes	Description
tokens	type(token_object)	in		Tokens.
i	integer(kind=I4P)	inout		Token counter.
word	character(len=:)	out	allocatable	Token text.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

no_more

Error if tokens exist from position from on (unsupported sub-options).

Returns: logical

function no_more(tokens, from, iostat, iomsg) result(ok)

Arguments

Name	Type	Intent	Attributes	Description
tokens	type(token_object)	in		Tokens.
from	integer(kind=I4P)	in		First position that must be empty.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

columnhead_title

Parse columnhead, columnheader or columnhead(N) (gnuplot title columnhead): column is N, or 0 for the column of the y field; false if word is none of them.

Returns: logical

function columnhead_title(word, column) result(ok)

Arguments

Name	Type	Intent	Attributes	Description
word	character(len=*)	in		Title word.
column	integer(kind=I4P)	out		Header column, 0 for the y one.

Call graph

function_drawable

Whether the style with draws a function (FUNCTION_STYLES): not error bars, nor the filled and panel styles.

Attributes: pure

Returns: logical

function function_drawable(with) result(yes)

Arguments

Name	Type	Intent	Attributes	Description
with	character(len=*)	in		Full style name.

Call graph

is_item_option

Whether word is a plot item option: it ends a function expression.

Attributes: pure

Returns: logical

function is_item_option(word) result(is)

Arguments

Name	Type	Intent	Attributes	Description
word	character(len=*)	in		Word.

Call graph

is_line_option

Whether word names a line property: lc, lt, lw, dt, ps, pt or their long forms.

Attributes: pure

Returns: logical

function is_line_option(word) result(is)

Arguments

Name	Type	Intent	Attributes	Description
word	character(len=*)	in		Option word.

Call graph

line_option

Parse the line property at tokens(i) and its value into line, leaving i on the value's last token: lc [rgb] "color", lc N, lt N (palette color N), lw W, dt N, ps S, pt N.

Returns: logical

function line_option(tokens, i, line, iostat, iomsg) result(ok)

Arguments

Name	Type	Intent	Attributes	Description
tokens	type(token_object)	in		Tokens.
i	integer(kind=I4P)	inout		Token counter.
line	type(line_style_object)	inout		Line properties.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

plain_columns

using fields of plain columns.

Attributes: pure

Returns: type(expression_object)

function plain_columns(columns) result(fields)

Arguments

Name	Type	Intent	Attributes	Description
columns	integer(kind=I4P)	in		Columns.

Call graph

string_argument

Optional single quoted string after an option; absent means empty.

Returns: logical

function string_argument(tokens, text, iostat, iomsg) result(ok)

Arguments

Name	Type	Intent	Attributes	Description
tokens	type(token_object)	in		Option tokens.
text	character(len=:)	out	allocatable	String.
iostat	integer(kind=I4P)	out		0 on success.
iomsg	character(len=:)	out	allocatable	Error message.

Call graph

valid_axes

Whether names concatenates supported axis names: x, y, y2.

Attributes: pure

Returns: logical

function valid_axes(names) result(ok)

Arguments

Name	Type	Intent	Attributes	Description
names	character(len=*)	in		Axis names.

Call graph

to_number

Parse a number; false if malformed or beyond the real range.

Returns: logical

function to_number(word, value) result(ok)

Arguments

Name	Type	Intent	Attributes	Description
word	character(len=*)	in		Text.
value	real(kind=R8P)	out		Number.

Call graph