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 [ ]: