unlab_gpu/
plot_doc.rs

1//
2// Copyright (c) 2026 Łukasz Szpakowski
3//
4// This Source Code Form is subject to the terms of the Mozilla Public
5// License, v. 2.0. If a copy of the MPL was not distributed with this
6// file, You can obtain one at https://mozilla.org/MPL/2.0/.
7//
8//! A module of plotting documentation.
9use crate::doc::*;
10use crate::mod_node::*;
11
12/// Adds the plotting documentation to the root module of signature and the root module of
13/// documentation.
14pub fn add_plot_doc(sig_root_mod: &mut ModNode<Sig, ()>, doc_root_mod: &mut ModNode<String, Option<String>>)
15{
16    let doc = r#"
17# Plotting functions
18
19The plotting function allows to draw charts and/or histograms. This library contains the plotting
20functions which are:
21
22- [`plot`](#var.plot)
23- [`plot3`](#var.plot3)
24- [`histogram`](#var.histogram)
25- [`hist`](#var.hist)
26
27The `chart` chart description can contain for example axes and a title. The fields of chart
28description are:
29
30- `title` - the chart title (optional)
31- `x` - the $X$ axis can be:
32  - the array with two elements which are a floating-point range of $X$ axis for the 2D chart or
33    the 3D chart
34  - the iterable object with the values for the histogram
35- `y` - the $Y$ axis can be:
36  - the array with two elements which are a floating-point range of $Y$ axis for the 2D chart or
37    the 3D chart
38  - the array with two elements which are an unsigned integer range of $Y$ axis for the histogram
39- `z` - the $Z$ axis can be the array with two elements which are a floating-point range of $Z$
40  axis for the 3D chart
41- `windowid` - the window identifier (optional)
42- `haswindow` - if this field has the convertible value to `true`, the window with the chart is
43  shown (default: true) (optional)
44- `file` - the path to the image file with the chart (supported formats are: PNG, SVG) (optional)
45- `size` - the array with two elements which are width and height in pixels (default: 640x480)
46  (optional)
47
48The series represents date that is plotted in a chart as for example a line, points, or a surface
49with same color. Also, the series can have series a string that consists of the series kind, the
50color, and the label. The syntax of series string is:
51
52```
53series string = [series kind], [series color], [",", label]
54```
55
56Also, the histogram series can have a string that consists of the color and the label. The syntax
57of histogram series string is:
58
59```
60histogram series string = [series color], [",", label]
61```
62
63The series kind can be:
64
65- `-` - line (default)
66- `--` - dashed line
67- `:` - dotted line
68- `o` - circle
69- `x` - cross
70- `.` - point
71- `^` - triangle
72- `sxy` - surface on the $X$ axis and the $Y$ axis
73- `sxz` - surface on the $X$ axis and the $Z$ axis
74- `syz` - surface on the $Y$ axis and the $Z$ axis
75
76The series color can be:
77
78- `r` - red
79- `g` - green
80- `b` - blue
81- `c` - cyan
82- `m` - magenta
83- `y` - yellow
84- `k` - black
85- `w` - white
86
87If the series color isn't passed in the series string, the default series color is used from the
88following colors in order for the specified series:
89
90- red
91- blue
92- green
93- cyan
94- yellow
95- magenta
96
97The label is separated from the series kind and the series color by comma character. 
98"#;
99    match doc_root_mod.value() {
100        Some(prev_doc) => doc_root_mod.set_value(Some(prev_doc.clone() + "\n" + &doc[1..])),
101        None => doc_root_mod.set_value(Some(String::from(&doc[1..]))),
102    }
103    
104    let doc = r#"
105Draws the 2D chart on the window and/or saves to the file.
106
107The series consists of the `Xi` object, the `Yi` object, and the `si` series string. The `Xi`
108object and the `Yi` object can be iterable objects. One function with one argument can be one of
109objects for series. This function can return an error with the `plot` error kind.
110
111# Examples
112
113```
114chart = {
115    x: .[ -1.0, 1.0 .]
116    y: .[ -0.1, 1.0 .]
117}
118function f(x)
119    x * x
120end
121plot(chart, -1.0 to 1.0 by 0.02, f, ",x^2")?
122```
123"#;
124    sig_root_mod.add_var(String::from("plot"), Sig::BuiltinFun(vec![
125        BuiltinFunArg::Arg(String::from("chart")),
126        BuiltinFunArg::OptArg(String::from("X1")),
127        BuiltinFunArg::OptArg(String::from("Y1")),
128        BuiltinFunArg::OptArg(String::from("s1")),
129        BuiltinFunArg::DotDotDot,
130        BuiltinFunArg::OptArg(String::from("XN")),
131        BuiltinFunArg::OptArg(String::from("YN")),
132        BuiltinFunArg::OptArg(String::from("sN"))
133    ]));
134    doc_root_mod.add_var(String::from("plot"), String::from(&doc[1..]));
135
136    let doc = r#"
137Draws the 3D chart on the window and/or saves to the file.
138
139The series consists of the `Xi` object, the `Yi` object, the `Zi` object, and the `si` series
140string. The `Xi` object, the `Yi` object, and the `Zi` object can be iterable objects. Two
141functions with one argument can be two of arguments for line series. One function with two
142arguments can be one argument for surface series. The surface object with the rows and the columns
143or the surface function with two arguments can be:
144
145- the `Z` object for the surface on the $X$ axis and the $Y$ axis
146- the `Y` object for the surface on the $X$ axis and the $Z$ axis
147- the `X` object for the surface on the $Y$ axis and the $Z$ axis
148
149The columns of surface object or the first argument of surface function and the rows of surface
150object or the second argument of surface function are:
151
152- the `X` values and the `Y` values for the surface on the $X$ axis and the $Y$ axis
153- the `X` values and the `Z` values for the surface on the $X$ axis and the $Z$ axis
154- the `Y` values and the `Z` values for the surface on the $Y$ axis and the $Z$ axis
155
156This function can return an error with the `plot` error kind.
157
158# Examples
159
160```
161chart = {
162    x: .[ -3.0, 3.0 .]
163    y: .[ -3.0, 3.0 .]
164    z: .[ -3.0, 3.0 .]
165}
166function sin10(x)
167    sin(x * 10.0)
168end
169function cos10(x)
170    cos(x * 10.0)
171end
172plot3(chart, sin10, -2.5 to 2.5 by 0.025, cos10, ",line")?
173```
174
175```
176chart = {
177    x: .[ -3.0, 3.0 .]
178    y: .[ -3.0, 3.0 .]
179    z: .[ -3.0, 3.0 .]
180}
181function f(x, y)
182    cos(x * x + y * y)
183end
184plot3(chart, -3.0 to 3.0 by 0.1, f, -3.0 to 3.0 by 0.1, "sxz,surface")?
185```
186"#;
187    sig_root_mod.add_var(String::from("plot3"), Sig::BuiltinFun(vec![
188        BuiltinFunArg::Arg(String::from("chart")),
189        BuiltinFunArg::OptArg(String::from("X1")),
190        BuiltinFunArg::OptArg(String::from("Y1")),
191        BuiltinFunArg::OptArg(String::from("Z1")),
192        BuiltinFunArg::OptArg(String::from("s1")),
193        BuiltinFunArg::DotDotDot,
194        BuiltinFunArg::OptArg(String::from("XN")),
195        BuiltinFunArg::OptArg(String::from("YN")),
196        BuiltinFunArg::OptArg(String::from("ZN")),
197        BuiltinFunArg::OptArg(String::from("sN"))
198    ]));
199    doc_root_mod.add_var(String::from("plot3"), String::from(&doc[1..]));
200
201    let doc = r#"
202Draws the histogram on the window and/or saves to the file.
203
204The series consists of the `di` data and the `si` series string. The `di` data should be an
205iterable object. The element in the iterable object can be:
206
207- boolean value
208- integer number 
209- floating-point number
210- string
211
212This function can return an error with the `plot` error kind.
213
214# Examples
215
216```
217chart = {
218    x: 1 to 3
219    y: .[ 0, 9 .]
220}
221d = .[ 1, 1, 2, 2, 1, 3, 3, 2, 2, 1, 1, 2, 2, 2, 3, 3, 1, 2, 3 .]
222histogram(chart, d, "")?
223```
224"#;
225    sig_root_mod.add_var(String::from("histogram"), Sig::BuiltinFun(vec![
226        BuiltinFunArg::Arg(String::from("chart")),
227        BuiltinFunArg::OptArg(String::from("d1")),
228        BuiltinFunArg::OptArg(String::from("s1")),
229        BuiltinFunArg::DotDotDot,
230        BuiltinFunArg::OptArg(String::from("dN")),
231        BuiltinFunArg::OptArg(String::from("sN"))
232    ]));
233    doc_root_mod.add_var(String::from("histogram"), String::from(&doc[1..]));
234
235    let doc = r#"
236This function is alias to the [`histogram`](#var.histogram) function.
237"#;
238    sig_root_mod.add_var(String::from("hist"), Sig::BuiltinFun(vec![
239        BuiltinFunArg::Arg(String::from("chart")),
240        BuiltinFunArg::OptArg(String::from("d1")),
241        BuiltinFunArg::OptArg(String::from("s1")),
242        BuiltinFunArg::DotDotDot,
243        BuiltinFunArg::OptArg(String::from("dN")),
244        BuiltinFunArg::OptArg(String::from("sN"))
245    ]));
246    doc_root_mod.add_var(String::from("hist"), String::from(&doc[1..]));
247}
unlab_gpu/plot_doc.rs

unlab_gpu/
plot_doc.rs
