Naming for Arduino framework wrapping

[quozl]

A naming that others may have faced. The Arduino framework has a set of well-known functions for general purpose I/O pin control, such as pinMode, digitalWrite, and digitalRead. If you didn't use the same names, because they are quite long and don't fit Forth conventions, what names did you choose?

So far I have chosen;

• m! or gpio-mode for pinMode, ( mode pin -- ),
• p! or gpio-pin! for digitalWrite, ( value pin -- ),
• p@ or gpio-pin@ for digitalRead, ( pin -- value ),
• a! or pwm-pin! for analogWrite, ( value pin -- ),
• a@ or adc@ for analogRead, ( pin -- value ).

[ruv]

Review of chosen names

The chosen short names for words to fetch and store a pin are good — they are similar to c@ and c! by their form and by the stack effects. Probably, I would use two-letter variants: mp!, dp!, dp@, ap!, ap@. But all of them have poor readability.

The chosen long names don't obey to a single convention: some of them have -pin suffix, but other don't have, some have !, but other conceptually similar words don't.

Common considerations

For memory operations, usually I rely on a presupposition that read operations are used more frequently than write operations. So I use "!" or other prefix for write operation names, and the empty prefix for read operation names. For example, I don't use get- prefix for getters. This approach is also used for new words in the Forth standard, for example see precision and set-precision.

For operations on pins, statistics can differ. But anyway, write instruction names should be more heavy than read, since they are to change a state.

A common convention for words that have side effects (that change a state) and for combinators is that their names are verbs. Their name forms can be as follows: {verb}, {verb}-{noun}, {verb}-{noun}-{adverb}, {verb}-{adverb}.

The names for words without side effects are usually nouns: {noun}, or {noun}-{adjective}.

A noun can be a compound noun.

Word set for operations on pins

For this set of words a naming format can be set-pin-X, and pin-X, where X varies for different kinds:

• set-pin-mode ( mode pin -- ) — mode is INPUT, OUTPUT, or INPUT_PULLUP.
• set-pin-level ( level pin -- ) — level is HIGH or LOW.
• pin-level ( pin -- level ) — level is HIGH or LOW.
• set-pin-pwm ( value pin -- ) — the value is a subject of "Pulse Width Modulation"; probably a better noun than pwm can be found.
• pin-adc ( pin -- value ) — the value is a subject of "Analog to Digital Converter"; probably a better noun than adc can be found.

Usually I use the verb set for an idempotent action. For comparison, when the verb put or write is used, it refers a nonidempotent action.

Some shorthands

Probably, in many use cases you know in advance a level or mode to set on a pin, so a more convenient words for that can be introduced:

• sink-pin ( pin -- ) — or down-pin, here we use sink or down as a verb.
• rise-pin ( pin -- ) — or up-pin, here we use rise or up as a verb.
• settle-pin-for-input ( pin -- ) — for-input plays the role of an adverb.
• settle-pin-for-output ( pin -- )
• settle-pin-for-pullup ( pin -- )

NB: the verbs sink, rise, settle are used for words that statically know how to change an object (a pin). In the latter case it is specified via the "adverb" part of the name. An alternative verb for settle could be adjust.

Separate namespace for the operations on pins

It should be noted that the names of this word set are constructed around the noun pin that is used as a proper name, and it actually determines a separate namespace for this word set. So it's a good idea to factor out this namespace explicitly into a separate word list.

If I would use a separate namespace (a separate word list) for operations on pins, for example the namespace pin ( -- wid ), it can looks like the following:

• pin::set-mode ( mode pin -- )
• pin::set-level ( level pin -- )
• pin::level ( pin -- level )
• pin::set-pwm ( value pin -- )
• pin::adc ( pin -- value )
• pin::sink ( pin -- )
• pin::rise ( pin -- )
• pin::settle-for-input ( pin -- )
• pin::settle-for-output ( pin -- )
• pin::settle-for-pullup ( pin -- )

I use a recognizer for such a syntax.

Separate namespace for each pin

We have a small number of pins, and each of them is probably used for its own unique aim in our application.
In such a case it could be convenient to have an own namespace for each pin.

If I would use a separate namespace for each pin (that is highly likely), or use a pin selector, it can looks like the following:

• X::set-mode ( mode -- )
• X::set-level ( level -- )
• X::level ( -- level )
• X::set-pwm ( value -- )
• X::adc ( -- value )
• X::sink ( -- )
• X::rise ( -- )
• X::settle-for-input ( -- )
• X::settle-for-output ( -- )
• X::settle-for-pullup ( -- )

Where X is a placeholder for an actual namespace alias ( -- wid ). NB: in this variant we pass less parameters via the stack, since a pin is known in advance — statically, or selected via a variable.

NB: this set of methods is actually a closure (in some sense) of the common set of methods over a selected pin. This closure should be generated automatically for each pin from a common model or template.