Shell Script Utilities

When a totolo package is installed using pip like pip install totolo, the following shell scripts are made available. The following python packages are required: pip install pandas openpyxl xlwt xlsxwriter.

A helpful reminder

$ to-help
Theme Ontology  https://www.themeontology.org
python-totolo   https://github.com/theme-ontology/python-totolo

To learn more about python usage, follow the github link.

The following commands are provided:
  to-makelist
  to-mergelist
  to-mergefiles
  to-help
Use "command -h" to find out more about each.

Happy Theming!
MO\PS

Utility to make lists as spreadsheets

$ to-makelist -h
usage: to-makelist [-h] [-t] [-s] [-r] [-d] [-a] path_ontology path_changes names [names ...]

Create an excel sheet with some of the theme data from the ontology. If neither -t or -s are given, selects themes to include.

positional arguments:
  path_ontology      Path to the ontology.
  path_changes       Path to the Excel sheet file that will be written.
  names              object names or patterns

options:
  -h, --help         show this help message and exit
  -t, --themes       select themes
  -s, --stories      select stories
  -r, --regex        names are regex patterns
  -d, --descendants  also include children/descendants of selected objects
  -a, --ancestors    also include parents/ancestors of selected objects

This utility is provided as a command line script. Example: "to-makelist ./ontology/notes mydata.xlsx -d theme1 theme2".

Utility to merge excel sheet of changes into a local ontology

$ to-mergelist -h
usage: to-mergelist [-h] [--dryrun] path_changes path_ontology

Merge an excel sheet of changes into a theme ontology directory. The first row should contain column headers, including: sid, weight, theme, motivation, revised theme, revised weight, revised
motivation, revised capacity, action.

positional arguments:
  path_changes   Path to the Excel sheet with changes.
  path_ontology  Path to the ontology.

options:
  -h, --help     show this help message and exit
  --dryrun       Read and report on stdout, but do not write changes to ontology.

This utility is provided as a command line script. Example: "to-mergelist mydata.xlsx ./ontology/notes".

Utility to merge one or more local ontologies together

$ to-mergefiles -h
usage: to-mergefiles [-h] [--dryrun] [--reorder] [paths ...]

Merge a number of files, or a number of dirs.

positional arguments:
  paths       One or more paths. The paths must all point to files, or all point to dirs.

options:
  -h, --help  show this help message and exit
  --dryrun    Read and report on stdout, but do not write changes to final path.
  --reorder   If set, reorder the entries in each file alphabetically.

This utility is provided as a command line script. Example: "to-mergefiles file1 file2 fileN".

Utility to write project contents to JSON

to-makejson -h
usage: to-makejson [-h] [-p PATH] [--verbosity VERBOSITY] [-v VERSION] [-t] [-s] [-c]
                   [--reorg | --no-reorg]
                   [source ...]

Output a version of the ontology as json. Use -t -s -c to select themes, stories, and/or collections
respectively. If none of these flags are given, all will be included.

positional arguments:
  source                Paths to include or version to download. If a single argument matching tag
                        pattern vYYYY.MM is given, it will be interpreted as a version. Otherwise the
                        arguments will be treated as one or more local paths.

options:
  -h, --help            show this help message and exit
  -p PATH, --path PATH  Path to the ontology.
  --verbosity VERBOSITY
                        Which fields to include. 'official': (default) include fields for official
                        release. 'all': include all fields.
  -v VERSION, --version VERSION
                        Named version to use. If not specified the latest version of the master branch
                        will be used.
  -t                    Include themes.
  -s                    Include stories.
  -c                    Include collections.
  --reorg, --no-reorg   If set (default) reorganize the ontology in some ways. In particular, remove
                        collection entries on stories and add corresponding component entries on the
                        collections instead.

This utility is provided as a command line script. Example: "to-makejson v2025.04 -tsc >
ontology_v202404.json"