New language extension: Allow underscores in identifiers

[cfbsoftware]

Release v4.3 of Astrobe will allow the use of the underscore character ('_') in Oberon identifier names (i.e. constant definitions etc.) For example:

Code: Select all

MCU.PINMODEOD0 

can then be written as

Code: Select all

MCU.PINMODE_OD0

This feature is solely intended for use with multi-word uppercase identifiers like these.

Normally you should avoid using uppercase names in Oberon programs to eliminate the possibility of clashing with Oberon's reserved words and standard procedures. However using peripheral register names in your programs that match those used by NXP, STMicroelectronics etc. in their documentation is felt to be a justifiable exception to the rule.

The problem is that the Oberon convention of writing multi-word names in CamelCaps cannot be used for uppercase names. The resulting difficulty of distinguishing each word has a negative impact on legibility. This particularly applies to some of the STMicroelectronics' definitions:

Code: Select all

GPIOCCRH
GPIOCODR
RCCAPB2ENR 

When underscores are allowed these can then be written as:

Code: Select all

GPIOC_CRH
GPIOC_ODR
RCC_APB2ENR

[Oberoid]

Some considerations about naming register constants.

I'm also wrestling with the uppercase names of registers in datasheets.
PWMMCR cannot be considered "self explaining" - code.

I prefer the camelBack style over the underscore style.

pwmMCR vs PWM_MCR

However the abriviations are still cryptic and I kept going back and forth between code and datasheet.S
My first reflex was adding the NXP description at the declaration part of the register constants. But that did not solve the problem of cryptic abreviations and made the text bulky.
So I used fully written keywords: M becomes Match, C becomes Counter. The keywords Register can be abreviated as R, Interrupt as I, Control as C.

Another optimisation of naming register constants is possible. Using the concept of locality.
Registers of the device pwm are local the module PWM, never accessed directly from other modules.
So from an Oberon perspective using an abreviation of the device in the name of the register is not necessary.

examples naming styles:

NXP
-----------
PWMMIR
PWMMTCR
PWMMPR

camelBack+abr
-------------------
pwmMIR
pwmMTCR
pwmMPCR

camelBack full words
------------------------
pwmMatchInterruptR
pwmMatchTimerControlR
pwmMatchPrescaleControlR

camelBack, full words, no reference
-------------------------------------------
matchInterruptR
matchTimerControlR
matchPrescaleControlR

[cfbsoftware]

These sorts of naming issues are subjective and depend on personal taste. What is important is that you decide on one style and apply it consistently.

When you have decided which you prefer you can then have the best of both worlds by including alias definitions for your constants e.g.:

Code: Select all

CONST
  matchInterruptR  = MCU.PWMMIR;
  matchTimerControlR = MCU.PWMMTCR;
  matchPrescaleControlR = MCU.PWMMPR;

You can then use the naming style you prefer in the body of your code but you have a lookup table at the top of your module which points you to the references in the NXP documentation.

[Oberoid]

Thanks for your reply
I will try out your recomendations on aliasing constants.