Skip to content

Version 0.1.0 is a first version, for trial. See what is not proven →

bogolang
FR

← Documentation

Tables, reports and mail

Tables, Excel files, charts, reports and mail.

All documentation pages

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.
  • columns chooses and orders the columns. A name no row has is an error that lists the columns there are.
  • True shows as yes, False as no, nothing as an empty cell. A Secret always shows as ***.
  • An empty list prints (no rows).
Bogolang
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).

Bogolang
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
  • kind is "line" or "bar". path must end in .png.
  • The y column 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 title the chart is titled "y by x".
  • No window opens: the chart is drawn straight to the file.
  • picture of a file that does not exist is an error.
Bogolang
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 Secret is 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.