This page covers what a program gives back to people: a table on the screen, a CSV or Excel file, a chart, a report in HTML, Word or PDF, and a mail. The example report_chart uses most of them.
Rows
table, export, chart and a report all take rows. A list of rows can hold any one kind of
thing:
| A row is | Its columns |
|---|---|
A Row (from .table() of a device output, Meraki, a web API) |
its columns |
A dict |
its keys |
A named tuple or a NamedTuple class |
its fields |
Any other object, such as a PingResult or a LogEvent |
its public values; lists inside it are not columns |
| A plain value (text, number, address, quantity) | one column named value |
Every row of one list must be the same kind of thing. A mixed list is an error that names the
two kinds. An AuditResult from audit() is taken as its rows.
table
| Command | Does |
|---|---|
table(rows: Sequence[object] \| AuditResult, columns: list[str] \| None = None) |
prints the rows as a table |
- Numbers are on the right, text on the left. Long lines are not cut.
columnschooses and orders the columns. A name no row has is an error that lists the columns there are.Trueshows asyes,Falseasno, nothing as an empty cell. ASecretalways shows as***.- An empty list prints
(no rows).
rows: list[dict[str, str]] = [
{"host": "core-sw1", "ip": "192.0.2.1", "state": "up"},
{"host": "edge-rt2", "ip": "192.0.2.2", "state": "down"},
]
table(rows)
table(rows, ["host", "state"])
host ip state
-------- --------- -----
core-sw1 192.0.2.1 up
edge-rt2 192.0.2.2 down
host state
-------- -----
core-sw1 up
edge-rt2 down
export
| Command | Does |
|---|---|
export(rows: Sequence[object] \| AuditResult, path: str, columns: list[str] \| None = None) |
writes the rows to a file |
The ending of path chooses the kind. export writes two kinds only:
| Ending | What is written |
|---|---|
.csv |
UTF-8 with a byte order mark, so Excel opens it with its accents right. Every value is text, as table shows it |
.xlsx |
One sheet. The first row is the column names in bold, frozen, with a filter. Numbers are written as numbers. Columns are as wide as their text, up to 60 characters |
Any other ending is an error. Other files are written by other commands: Topology.save writes
.json, .csv or .dot (see logs and topology), and a configuration or a
snapshot has its own .save (see devices).
rows: list[dict[str, str]] = [{"host": "core-sw1", "state": "up"}]
export(rows, "hosts.csv")
export(rows, "hosts.xlsx", ["host"])
chart and picture
| Command | Gives |
|---|---|
chart(rows: Sequence[object], x: str, y: str, path: str, kind: str = 'line', title: str = '') |
Picture: draws column y against column x and writes a .png |
picture(path: str) |
Picture: a picture file already on the disk, to put in a report |
kindis"line"or"bar".pathmust end in.png.- The
ycolumn holds numbers, or quantities of one kind. A column of quantities is drawn in the unit its largest value prints in, and that unit is written on the axis: 900 kbps and 1.2 Mbps are drawn as 0.9 and 1.2 on one Mbps axis. - A row with no value in
y, or with another kind of value, is an error that names the row. - Without
titlethe chart is titled "y by x". - No window opens: the chart is drawn straight to the file.
pictureof a file that does not exist is an error.
readings: list[dict[str, Rate]] = [{"peak": 12Mbps}, {"peak": 86Mbps}, {"peak": 92Mbps}]
drawn: Picture = chart(readings, x="peak", y="peak", path="peak.png", kind="bar", title="Peak")
logo: Picture = picture("logo.png")
report
| Command | Does |
|---|---|
report(template: str, path: str, **values: object) |
fills the holes of the template and writes path |
The ending of path chooses the kind of report:
path ends in |
The template is | Notes |
|---|---|---|
.html |
an HTML file (.html or .htm) |
A picture is put inside the page itself, so the file stands alone |
.docx |
a Word file (.docx) |
The engineer keeps his own styles, logo and cover |
.pdf |
a Word file (.docx) |
Bogolang fills the Word file, then converts it |
Holes
A hole is a plain name in braces, such as {link}, as in the device templates of the
configuration and templates page.
- A real brace is written twice:
{{gives{and}}gives}. This matters in the CSS of an HTML template:body {{ margin: 2em; }}. - A hole is a name of letters, digits and
_. An expression such as{a + b}is refused: work the value out in Bogolang and pass it by name. - Every hole needs a value, and every value needs a hole. A value the template has no hole for is an error, so a misspelt name does not pass unseen.
- A
Secretis refused: a report never holds a secret.
What a value becomes:
| Value | In HTML | In Word |
|---|---|---|
| Text, a number, a quantity, an address | the text, made safe for HTML | the text, in the style of the place where the hole begins |
A list of rows, or an AuditResult |
a <table> with a header row |
a Word table |
A Picture |
an <img> with the picture inside the page |
the picture, 16 cm wide |
In a Word template a table or a picture needs a paragraph of its own: the hole must stand alone in it. A hole in a table cell, a header or a footer takes text only. Word may split a hole over several pieces of text with different styles; Bogolang reads it whole.
An example
The template of the example report_chart, template.html:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Uplink report</title>
<style>
body {{ font-family: sans-serif; margin: 2em; }}
table {{ border-collapse: collapse; }}
th, td {{ border: 1px solid #999; padding: 4px 8px; }}
th {{ background: #1f3864; color: white; }}
</style>
</head>
<body>
<h1>Uplink report: {link}</h1>
<p>Capacity {capacity}. Busiest hour {busiest} at {peak}. Hours above {limit} of the capacity: {busy_hours}.</p>
{chart}
<h2>Readings</h2>
{readings}
</body>
</html>
The program fills it:
```bogo skip report("template.html", str(out / "report.html"), link=c.link, capacity=c.capacity, busiest=top.hour, peak=top.peak, limit=f"{c.limit:.0%}", busy_hours=len(busy), chart=drawn, readings=c.readings)
The page it writes begins:
Uplink report: edge-rt2 Gi0/0/1
Capacity 100Mbps. Busiest hour 14:00 at 92Mbps. Hours above 80% of the capacity: 2.
<img src="data:image/png;base64,...
The example makes no Word report, because a Word template is a file no one can read as text.
To make one, write the same holes in a Word document, save it as `template.docx`, and give
`report("template.docx", "report.docx", ...)`.
### Mistakes are found before anything is written
bad.html, line 2: '{ margin: 2em; }' is not a hole. A hole is a plain name of letters, digits and _, such as {vlan}. Work out values in Bogolang and pass them by name. The hole {capacity} in template.html has no value. Give it as report(..., capacity=...). good.html has no hole {extra}. Holes: link.
The first is a CSS brace written once. Written twice, it is a real brace.
### PDF
For `.pdf`, Bogolang makes the Word file and converts it. It uses Microsoft Word on Windows when
the `docx2pdf` package is installed, else LibreOffice. With neither, it stops with an error that
says so; an `.html` or a `.docx` report works without them.
**No PDF report has ever been made.** Only the choice between Word and LibreOffice was tested.
See [not proven](not-proven.md).
## `mail`
| Command | Does |
|---|---|
| `mail(to: str, subject: str, body: str, attach: list[str] \| None = None)` | sends one mail |
### The settings
The mail server is stored once, in the protected store of the operating system:
bogo login --mail
It asks for the server, the security (`starttls`, `ssl` or `none`), the port (offered as 587,
465 for `ssl`, 25 for `none`), the user, the password and the sender address. A server that asks
for no login takes an empty user. A program never holds them. `bogo logout --mail` removes them.
A program that sends with no settings stored stops with: `No mail settings are stored. Store
them first with: bogo login --mail`.
### What `mail` does
- `to` holds one address, or several separated by commas. Each is checked for its form before
anything is sent.
- An attachment that does not exist stops the program before anything is sent.
- A mail leaves the computer and cannot be taken back. A program that sends one should ask
first with `confirm(...)`, unless it runs unattended on purpose.
- A failed send stops the program with an error. A password in the error text is shown as
`***`.
- Each mail is a line of the run record (`bogo run --record`): the addresses, the subject and
whether it left. The body is not recorded.
```bogo
if confirm("Send the loss report to the NOC?"):
mail("noc@example.com, oncall@example.com", "Loss report",
"Two hosts checked.\nOne is down.", attach=["hosts.csv"])
--dry and --replay show the mail and send nothing
With bogo run --dry, mail prints what it would send. It reads no settings and contacts no
server. A dry run writes no line in the run record. A run with --replay does the same, and
its first line starts with REPLAY in place of DRY RUN.
DRY RUN: mail to noc@example.com, oncall@example.com. Nothing is sent.
Subject: Loss report
Two hosts checked.
One is down.
Attachments: hosts.csv
A program can ask whether it runs dry with dry_run(), to say "would send" and not "sent".
mail has never talked to a real mail server. The tests replace the one function that
sends. A draft placed in Outlook for the engineer to read and send himself is not in this
version. See not proven.
For posting one line to a chat or alerting tool, see webhook on the
APIs and platforms page.