Figure Terminology

I can't believe how specific ContraDB had to get in it's breakdown of Contra terminology. This is a guide for ContrDB developers to make sense of it all.

TLDR: A dance has many figures. The data each figure stores is different, like for an allemande you've gotta know who is allemanding, but for long lines, it's obviously everybody and we don't bother to store that. What to store for each figure is determined by a figure definition in the JavaScript file figures.es6.

Move

A move is encoded as a string. It can contain at a minimum letters, spaces, single quotes (e.g. "Rory O'Moore") and ampersands (e.g. "Arch & Dive").

Alias

Consider dancing a see saw. Many people teach it as 'left shoulder do si do', but many people expect to find 'see saw' in the menus. Internally, ContraDB wants to encode it as a do si do with a shoulder parameter set to the left shoulder. If someone clicks the radio button to make it a right shoulder thing, we don't want to call that thing a 'right shoulder see saw', whe just wanna call it a 'do si do'.

Aliases are introduced to manage this complexity. Aliases are strings of the same format as moves.

• 'see saw' is an alias for the move 'do si do' - some do si dos are see saws, not all see saws are do si dos
• 'swat the flea' is an alias for the move 'box the gnat' - all swat the fleas are box the gnats, not all box the gnats are swat the fleas
• 'meltdown swing' is an alias for 'swing' - all meltdown swings are swings, not all swings are meltdown swings.
• Most moves are aliased to themselves, for example alias('allemande') → 'allemande'

You can see a list of all the aliases by visiting http://contradb.com/figures.

You can get the most specific alias for a figure by calling alias(figure). You can get the move by calling move(figure).

Figure Definition

In the file figures.es6 there exist specifications of all the figures, alphabetized by move name. Here's an example:

defineFigure("do si do",
             [param_subject_pairz, param_right_shoulder_spin, param_once_around, param_beats_8],
             {stringify: doSiDoStringify, alias: doSiDoAlias});

Formal Parameters

Notice the second argument to defineFigure above:

[param_subject_pairz, param_right_shoulder_spin, param_once_around, param_beats_8]

This is the formal parameter list for the figure.

Each figure takes zero or more params, of various types. Each type is presented to the user by a specialized UI element called a chooser. For example, one chooser type is chooser_revolutions, used in circle and allemande.

params

The main job of params is to specify a type of the parameter.

They also have an important secondary purpose. Params usually specify defaults. Examples:

• the default subject of the move swing is 'partners'. It's good to take a guess, because half the time we're right and save the user 2 valuable mouse clicks!
• By contradb convention, the default number of revolutions is one. Even though circle three-quarters is more common than circle once. Even though allemande once and a half is more common than allemande once.
• the default shoulder of the move do si do is true (meaning right shoulder).
• the default shoulder of the alias see saw is false (meaning left shoulder), overriding do si do's weaker default.

choosers

choosers are tied to specific UI widgets for presentation. The boolean chooser is a check box, the revolutions chooser is a select box for an angle.

Figure

Figures in dances pair a move with some actual parameters. If you look at the json, it is literally

{move:"do si do", parameter_values:["ladles",false,360,8]}

Actual Parameters aka Parameter Values

These have types defined above in the figure definition. Also, generically, all actual parameters except beats can accept nil. Actual parameters can also accept the string '*' in searches, which has the intuitive wildcard meaning.

Dancers

We use a lot of select boxes for choosing sets of dancers, so there is a large taxonomy of ways to specify dancers. The highlights are:

• pair: one pair of dancers, e.g. "gentlespoons".
• pairs: two pairs of dancers, paired off, e.g. "neighbors".
• pairz: one or two pairs of dancers, e.g. allemande is sometimes neighbors and sometimes gentlespoons.

Dialects

Contra dancers want to be able to rename 'gentlespoons' to 'larks'. They want to be able to rename 'gyre' to 'darcy'. A dialect is a parameter to every function that can ever print a figure or move, and it contains information for doing that.

A dialect is a set of idioms, represented as a hash for ease of transmission via JSON. It's not directly represented in the database.

Idiom

An idiom maps a term to a substitution and is saved in the database.

Dance

I'm pretty sure you know what a dance is.

Choreographer

People who write dances!

Program

An ordered list of activities

Activity

An activity has an optional dance and an optional note. The dance can be nil because it's a dance outside the scope of contradb - e.g. break, waltz, a squaredance, or a hyperlink to another dance off site.

User

What you'd expect. An Admin is a user with the "admin" boolean set to true. They have broader powers to view/edit dances and choreographers.