Managing score packages on the command-line

Abjad comes with a number of command-line tools which are used outside of the Python interpreter to handle a variety of routine tasks, including:

  • Building Abjad's API documentation
  • Running doctests (documentation or docstring tests)
  • Collecting statistics on the code-base
  • Replacing strings
  • Removing junk and temporary files
  • Running abjad-book to embed notation in LaTeX

These tools are grouped as subcommands under the umbrella of Abjad's ajv script.

Like nearly all command-line tools, written in Python or not, we can pull up documentation about ajv by calling it with the --help flag.

Note: The "!" prefix here tells IPython to run the command not in Python but in Bash.


In [1]:
!ajv --help


usage: abj-dev-script [-h] [--version]
                      {help,list,builds,clean,material,replace,score,segment,stats}
                      ...

Entry-point to Abjad developer scripts catalog.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

subcommands:
  {help,list,builds,clean,material,replace,score,segment,stats}
    help                print subcommand help
    list                list subcommands
    builds              Manage score package build targets.
    clean               Clean *.pyc, *.swp, .cache, __pycache__ and tmp* files
                        and folders from PATH.
    material            Manage score package materials.
    replace             Replace text.
    score               Manage score packages.
    segment             Manage score package segments.
    stats               Build statistics about Python modules in PATH.

Composition workflow

The score project layout suggests a particular overall workflow for composing scores:

  • Create materials and segments
  • Edit materials and segments
  • Stage segments
  • Illustrate materials and segments
  • Collect segments illustrations into the build directory
  • Create a build target
  • Render a build target
  • Distribute (archive) build target assets

This workflow is afforded by tools available either directly in your terminal, or implemented as subcommands of ajv:

Creation tasks

  • Creating scores
  • Creating materials
  • Creating segments
  • Creating build targets

Illustration tasks

  • Illustrating materials
  • Illustrating segments

Segment-specific tasks

  • Staging segments
  • Collecting segments

Rendering tasks

  • Rending materials
  • Rendering segments
  • Rendering build target assets

File-system-management tasks

  • Renaming materials, segments and build targets
  • Copying materials, segments and build targets
  • Deleting materials, segments and build targets
  • Editing materials and segments

Managing scores


In [2]:
!ajv score --help


usage: manage-score-script [-h] [--version] --new TITLE [--year YEAR]
                           [--composer-name NAME] [--composer-email EMAIL]
                           [--composer-github GITHUB_USERNAME]
                           [--composer-library LIBRARY_NAME]
                           [--composer-website WEBSITE] [--force]

Manage score packages.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

actions:
  --new TITLE, -N TITLE
                        create a new score

--new options:
  --year YEAR, -y YEAR
  --composer-name NAME, -n NAME
  --composer-email EMAIL, -e EMAIL
  --composer-github GITHUB_USERNAME, -g GITHUB_USERNAME
  --composer-library LIBRARY_NAME, -l LIBRARY_NAME
  --composer-website WEBSITE, -w WEBSITE

common options:
  --force, -f           force overwriting

To create a new score

ajv score --new "My Score" \
    --year 2016 \
    --composer-name "Jane Doe Composer" \
    --composer-email "composer@composer.com" \
    --composer-github "jdcomposer" \
    --composer-library "my_library" \
    --composer-website "composer.com"

Make sure to install that score as a Python package

cd my_score
pip install -e .

Working inside a score

When using the commands ajv material, ajv segment and ajv target, you need to let them know what score you want to operate upon. You can either pass in the name of a score package installed in your system, or you can simply work from within the score package directory itself - ajv is clever enough to figure out that there's a score there.

To be explicit:

ajv segment --list -s my_score

To be implicit:

cd my_score
ajv segment --list

Managing materials


In [3]:
!ajv material --help


usage: manage-material-script [-h] [--version]
                              (--new NAME | --edit PATTERN [PATTERN ...] | --illustrate PATTERN [PATTERN ...] | --render PATTERN [PATTERN ...] | --list)
                              [--score-path SCORE] [--force]

Manage score package materials.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

actions:
  --new NAME, -N NAME   create a new material
  --edit PATTERN [PATTERN ...], -E PATTERN [PATTERN ...]
                        edit materials
  --illustrate PATTERN [PATTERN ...], -I PATTERN [PATTERN ...]
                        illustrate materials
  --render PATTERN [PATTERN ...], -R PATTERN [PATTERN ...]
                        render material illustrations
  --list, -L            list materials

common options:
  --score-path SCORE, -s SCORE
                        score path or package name
  --force, -f           force overwriting

To create a material

ajv material --new my_material_name

To edit a material

ajv material --edit my_material_name

To illustrate a material

ajv material --illustrate my_material_name

Managing score segments


In [4]:
!ajv segment --help


usage: manage-segment-script [-h] [--version]
                             (--new NAME | --edit [PATTERN [PATTERN ...]] | --illustrate PATTERN [PATTERN ...] | --render PATTERN [PATTERN ...] | --collect | --stage | --list)
                             [--score-path SCORE] [--force] [-u]

Manage score package segments.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

actions:
  --new NAME, -N NAME   create a new segment
  --edit [PATTERN [PATTERN ...]], -E [PATTERN [PATTERN ...]]
                        edit segments
  --illustrate PATTERN [PATTERN ...], -I PATTERN [PATTERN ...]
                        illustrate segments
  --render PATTERN [PATTERN ...], -R PATTERN [PATTERN ...]
                        render segment illustrations
  --collect, -C         collect segment illustrations
  --stage, -T           stage segments for illustration
  --list, -L            list segments

common options:
  --score-path SCORE, -s SCORE
                        score path or package name
  --force, -f           force overwriting
  -u, --unstaged        Include segments not staged in segments/metadata.json

Managing build targets


In [6]:
!ajv builds --help


usage: manage-build-target-script [-h] [--version]
                                  (--new [NAME] | --render NAME | --distribute NAME | --list)
                                  [--front-cover] [--back-cover] [--preface]
                                  [--score] [--music] [--parts]
                                  [--paper-size PAPER_SIZE]
                                  [--orientation ORIENTATION]
                                  [--score-path SCORE] [--force]

Manage score package build targets.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

actions:
  --new [NAME], -N [NAME]
                        create a new build target
  --render NAME, -R NAME
                        render sources
  --distribute NAME, -U NAME
                        stage build artifacts for distribution
  --list, -L            list build targets

--render flags:
  Use when rendering specific assets only.

  --front-cover         render the front cover LaTeX source
  --back-cover          render the back cover LaTeX source
  --preface             render the preface LaTeX source
  --score               render the aggregate score LaTeX source
  --music               render the music LilyPond source
  --parts               render the parts LilyPond source

--new options:
  --paper-size PAPER_SIZE
                        select new build target paper size
  --orientation ORIENTATION
                        select new build target orientation

common options:
  --score-path SCORE, -s SCORE
                        score path or package name
  --force, -f           force overwriting

In [ ]: