4. Edit#
A rivt file is a Python file (utf-8 ) that includes the import statement
import rivtlib.rivtapi as rv
providing four primary API functions (7 total).
API#
The API functions take a triple quoted string as the argument. When running in an IDE (e.g. VSCode) the file may be executed interactively. Interactive output is formatted as utf-8 text for speed and flexibility. API functions may be grouped and executed step-wise using the standard cell decorator # %%. Document and report files are generated by the functions rv.write_public() and rv.write_private() which output files in GitHub Flavored Markdown (GFM) and PDF.
API |
Name |
Purpose |
rv.R |
Run |
Run external programs |
rv.I |
Insert |
Insert static resources |
rv.V |
Value |
Calculate values |
rv.T |
Tool |
Python functions |
rv.X |
Exclude |
Skip rivt function (editing) |
rv.W |
Write |
Write docs or reports |
rv.Q |
Quit |
Exit program |
Each API function defines a document section which may be arranged in any order or frequency.
Syntax#
The first line of each function includes a section label (that also may be a section title) followed by formatting parameters. New sections may be labeled as separate or integrated with preceding sections. The section body can contain any utf-8 text. Commands and tags applicable to each function are defined [here](#commands) and [here](#tags).
rivt syntax uses COMMANDS for file operations and TAGS for text formatting. Any text not defined by commands or tags is passed through as restructuredText. COMMANDS and TAGS are based on the docutils Python lbrary.
Commands#
Commands read and write external files. They start in the first column with vertical bars. A double bar is used for write commands ( || ) and a single bar for reads. The bar is followed by the command name and parameters separated by a single bar ( | ) as follows:
| READ COMMAND | relative file path | param1, param2
|| WRITE COMMAND | relative file path | param1, param2
In the tables below parameter options are separated with semi-colons and list elements are separated with commas. Options are in parenthesis. File locations are specified using paths relative to the rivt file location and folder structure. Folder organization is described here.
READ
Scope |
Command |
File Types |
rv.V |
| VREAD | rel. pth | dec1 |
.csv |
rv.I rv.V |
| TABLE | rel. pth | col width, l; c; r |
.csv, .txt, .xlsx |
rv.I rv.V |
| IMG | rel. pth | caption, scale, -; ([_F]) |
.png, .jpg |
rv.I rv.V |
| IMG2 | rel. pth | c1, c2, s1, s2, -; ([_F]) |
.png, .jpg |
rv.I |
| TEXT | rel. pth | plain; rivt; literal; latex |
.txt, .tex |
rv.I |
| APPEND | rel. pth | num; nonum |
.pdf (pdf, html) |
WRITE
Scope |
Command |
Notes |
rv.V |
a = 1+1 | unit | reference |
= is command tag |
rv.W |
|| WRITE | docs | tpdf; txt; html; lpdf |
tpdf = text-pdf |
rv.W |
|| REPORT | docs | tpdf; txt; html; lpdf |
lpdf = latex-pdf |
Examples#
Example 1#
API functions start in column one. rivt-strings are indented four spaces (for legibility and code folding).A rivt doc is assembled by each function in order of the input order. Each function also, optionally, defines a doc section.
import rivtlib.rivtapi as rv
rv.R("""Run function | pass; redact | nocolor; color code
The Run function processes shell commands.
Each API function defines a new document section. The first line is a
heading line which includes the section heading, a parameter for redacting
sections in a mirror file intended for public sharing, and a parameter for
the background color for the section. If the section heading is preceded by
two dashes (--) the section is continued from the prior section without
introducting a new number.
File formatting follows pep8 and ruff. API functions start in column one.
All other lines are indented 4 spaces to facilitate section folding,
bookmarks and legibility.
""")
rv.I("""Insert function | pass; redact | nocolor
The Insert function formats static objects including images, tables,
equations and text.
||text | data01/describe.txt | rivt
The table command inserts and formats tabular data from csv or xls files.
The _[t] tag formats and autonumbers table titles.
A table title _[t]
|| table | data/file.csv | 60,r
The image command inserts and formats image data from png or jpg files. The
_[f] tag formats and autonumbers figures.
A figure caption _[f]
|| image | data/f1.png | 50
Two images may be placed side by side as follows:
The first figure caption _[f]
The second figure caption _[f]
|| image | private/image/f2.png, private/image/f3.png | 45,35
The tags _[x] and _[s] format LaTeX and sympy equations:
\gamma = \frac{5}{x+y} + 3 _[x]
x = 32 + (y/2) _[s]
""")
rv.V("""Values function | pass; redact | nocolor
The Values fucntion evaluates variables and equations.
The equal tag declares a value. A sequence of declared values terminated
with a blank line is formatted as a table.
Example of assignment list _[t]
f1 = 10.1 * LBF |LBF, N| a force value
d1 = 12.1 * IN |IN, CM| a length value
An equation tag provides an equation description and number. A colon-equal
tag assigns a value and specifies the result units and the output decimal
places printed in the result and equation.
Example equation - Area of circle _[e]
a1 := 3.14(d1/2)^2 | IN^2, CM^2 | 1,2
|| declare | data01/values02.csv
The declare command imports values from the csv file written by rivt when
processing values in other documents.
""")
rv.T("""Tools function | pass; redact | nocolor
The Tools function processes Python code.
""")
rv.X("""Any text
Changing a function to X skips evaluation of that function. Its purposes
include review commenting and debugging.
""")
rv.W("""Write function | pass; redact | nocolor
The Write function generates docs and reports.
| docs |
| report |
""")
Example 2#
API functions start in column one. rivt-strings are indented four spaces (for legibility and code folding).A rivt doc is assembled by each function in order of the input order. Each function also, optionally, defines a doc section.
import rivtlib.rivtapi as rv
rv.R("""Run function | pass; redact | nocolor; color code
The Run function processes shell commands.
Each API function defines a new document section. The first line is a
heading line which includes the section heading, a parameter for redacting
sections in a mirror file intended for public sharing, and a parameter for
the background color for the section. If the section heading is preceded by
two dashes (--) the section is continued from the prior section without
introducting a new number.
File formatting follows pep8 and ruff. API functions start in column one.
All other lines are indented 4 spaces to facilitate section folding,
bookmarks and legibility.
""")
rv.I("""Insert function | pass; redact | nocolor
The Insert function formats static objects including images, tables,
equations and text.
||text | data01/describe.txt | rivt
The table command inserts and formats tabular data from csv or xls files.
The _[t] tag formats and autonumbers table titles.
A table title _[t]
|| table | data/file.csv | 60,r
The image command inserts and formats image data from png or jpg files. The
_[f] tag formats and autonumbers figures.
A figure caption _[f]
|| image | data/f1.png | 50
Two images may be placed side by side as follows:
The first figure caption _[f]
The second figure caption _[f]
|| image | private/image/f2.png, private/image/f3.png | 45,35
The tags _[x] and _[s] format LaTeX and sympy equations:
\gamma = \frac{5}{x+y} + 3 _[x]
x = 32 + (y/2) _[s]
""")
rv.V("""Values function | pass; redact | nocolor
The Values fucntion evaluates variables and equations.
The equal tag declares a value. A sequence of declared values terminated
with a blank line is formatted as a table.
Example of assignment list _[t]
f1 = 10.1 * LBF |LBF, N| a force value
d1 = 12.1 * IN |IN, CM| a length value
An equation tag provides an equation description and number. A colon-equal
tag assigns a value and specifies the result units and the output decimal
places printed in the result and equation.
Example equation - Area of circle _[e]
a1 := 3.14(d1/2)^2 | IN^2, CM^2 | 1,2
|| declare | data01/values02.csv
The declare command imports values from the csv file written by rivt when
processing values in other documents.
""")
rv.T("""Tools function | pass; redact | nocolor
The Tools function processes Python code.
""")
rv.X("""Any text
Changing a function to X skips evaluation of that function. Its purposes
include review commenting and debugging.
""")
rv.W("""Write function | pass; redact | nocolor
The Write function generates docs and reports.
| docs |
| report |
""")