Reports

Reports turn a comparison into a document you can print, keep or send to somebody who does not have pb-diff: a code review pack, an audit trail of what a release changed, an attachment to a change request.

The five reports

Every report is under Compare ▸ Reports, and which ones are enabled depends on the tab in front.

Try it: the changes to one object

With the w_order_entry comparison of Your first comparison open, choose Compare ▸ Reports ▸ File Changes Report. The report prints every changed item in full with its changes highlighted, and opens in a tab of its own. Save it as HTML to share it with someone who does not have pb-diff installed; the saved report is in the examples.

The CLI writes the same report (result, report):

pb-diff-cli report changes old/w_order_entry.srw new/w_order_entry.srw --report-format html --output report/cli-changes.html --format json

Try it: what changed in a release

Compare the two releases of orders.pbl, as in Two releases of a library, or start pb-diff with them on the command line:

pb-diff.exe libraries\release-1.4\orders.pbl libraries\release-1.5\orders.pbl

With the summary in front, choose Compare ▸ Reports ▸ Comparison Changes Report. The report lists the eleven objects that changed, with their type and the size and date of each side, and leaves out the three that did not; its header still counts all fourteen, the three unchanged among them. The saved report is in the examples.

The CLI writes the same report for a nightly job:

pb-diff-cli report summary-changes libraries/release-1.4/orders.pbl libraries/release-1.5/orders.pbl --output changes.html --format json

The report tab

A report opens as a tab of its own, rendered as you would read it on paper. While it is in front, the tool bar carries Save As, Print, Preview and Browser, because a report is a thing you print or send rather than one you edit: save it to a file, print it through the ordinary Windows print dialog, look at the pages first, or hand it to the system browser, which is the quickest way to get it in front of somebody else. The same commands are File ▸ Save As, File ▸ Print, File ▸ Print Preview and Compare ▸ Reports ▸ Open in Browser.

Printing uses the standard Windows print dialog and print queue, so any installed printer is available and the usual page setup applies.

Reports also open as tabs when a source-control client launches pb-diff with -SDI. Library summaries and their detail tabs can both create reports. Closing a report returns to its comparison if it is still open, otherwise to the primary summary. Opening an unrelated saved report requires Studio mode.

Save formats

Script text in a report is indented to the Tab size from Options ▸ Text settings, the same setting the compare panes use, so a report reads the way the comparison it came from reads. CSV and JSON are data rather than a page and carry the text as the file holds it, tabs included, subject to the CSV safety rule below.

To prevent spreadsheet formula injection, CSV text cells are prefixed with a single quote (') before CSV quoting if their first character after any leading whitespace or control characters is =, +, - or @, or if they start with a tab or carriage return. The original text is otherwise preserved. Generated counts and sizes remain unprefixed numbers.

A saved or printed report is always a white page with dark ink on it, whichever colour scheme pb-diff is running in: it is going to a printer or to somebody else's reader, and neither of those knows anything about your scheme. The report tab inside the window is the other way round: it is a pane of the application, so in the dark scheme it is dark, with the same change highlights the compare panes use.

pb-diff does not produce legacy binary .xls or .doc files. Writing them properly needs a large third-party library, and pb-diff ships with no third-party runtime dependencies. CSV opens in Excel and HTML opens in Word.

Opening a saved report

File ▸ Open Saved Report reads a report you saved as JSON back into a report tab. A report saved as PDF, HTML, CSV or RTF opens in the program Windows registers for it, because only the JSON form carries the report model.

The saved JSON names the schema it was written to, in a schemaVersion member. A file that is not there, one that cannot be read, one that is not valid JSON, one that is JSON but not a pb-diff report, and one written to a schema version this build does not read each say which of those it was, and load nothing: no half a report, and no falling back to showing you something else. A report already open in the tab stays as it was.

Reports saved before that member existed still open: no version in the file means the version it was written to, not an unrecognised one. The one file that no longer opens is a Comparison Report Current Filter , the sixth report pb-diff used to offer; the message says so and names it, rather than calling the file damaged. Open the comparison again and save a Comparison Report in its place.

Reports from a script

The same reports can be produced headlessly for a build or a nightly job, with pb-diff-cli report. The report kind comes first, then the two inputs:

pb-diff-cli report summary         old.pbl new.pbl --output changes.html
pb-diff-cli report summary-changes old.pbl new.pbl --output changes.csv
pb-diff-cli report changes         old\w_main.srw new\w_main.srw --output w_main.pdf
pb-diff-cli report full            old\w_main.srw new\w_main.srw --report-format json

The format is taken from the file name, or given explicitly with --report-format. Without --output, the text formats are written to standard output; PDF has to go to a file. The CLI uses fixed defaults rather than your desktop settings, so the same command gives the same report on every machine. See Automate with pb-diff-cli.