RPL comment syntax

[c3d]

I am in the process of implementing comments for DB48X, and I am wondering about the best way to deal with them.

There seems to be a wide consensus that comments in RPL begin with @ and end with a newline. This is exemplified with code found on the Wikipedia page about RPL, which has examples like this:

Code:

« 
    0       @ Start with zero on the stack
    1 10    @ Loop from 1 to 10
    FOR I   @ "I" is the local variable
       I +  @ Add "I" to the running total
    NEXT    @ Repeat...
 »

Notice that the comments are aligned on the right. That also seems to be a rather common style for RPL comments.

Now, I see several ways to approach comments on DB48X:

1/ Parse them, but ignore them. In other words, the comments are not kept in the object, and if you edit, you won't see them. That makes sense if you edit your files on a PC to be consumed by the calculator.

2/ To have a "comment" object type, which preserves a comment in the source code, and has no effect during execution. That seems more useful on a calculator, but has the problem that RPL compiles objects, so you need a nice way to render comments.

That's where the style above is a bit problematic. While it looks nice on a PC screen, it's next to unusable on the calculator screen, for two reasons:

a) being on the right, they are rarely visible along with the code.
b) keeping the comments nicely aligned adds a lot of complexity to the editor code.

So I would like to know how you feel about the following approaches

1) Have two types of comments, one being removed at parse time, the other being preserved. I'm thinking that comments beginning with @ could be preserved and comments beginning with $ or maybe @@ would be eliminated.

2) Change the "standard" style for RPL programs where comments would be on a line on their own, aligned with the code.

This is what my code decompiler produces at the moment:

Code:


«
    → Size
    «
        Degrees ClearLCD 0 360000 
        for i
            @ Set foreground
            #1111111111111111 i 16 mod × Foreground 
            @ Build starting point
            {}
            @ X coordinate
            i sin Size × + 
            @ Y coordinate
            i cos Size × + 
            @ Build end point
            {}
            @ X coordinate
            i 2.3 × sin Size × + 
            @ Y coordinate
            i 2.5 × cos Size × + 
            @ Draw the line and wait for 1ms
            DrawLine 0.001 Wait
        next
        0 Wait Drop
    »
»

Does that sound like an acceptable trade-off?

[Raymond Del Tondo]

I think it would be nice to have the choice between EOL-comments and separate-line comments.

[rprosperi]

2 types are definitely valuable as there are (occasional) times that you absolutely want to retain comments even when compiled/on the machine.

To me, these make the most sense:

statement1 @ Comment that will not be retained

statement2 @@ Comment that WILL be retained @@ more commands possible here...

[Claudio L.]

(08-27-2023 01:29 AM)rprosperi Wrote:  2 types are definitely valuable as there are (occasional) times that you absolutely want to retain comments even when compiled/on the machine.

To me, these make the most sense:

statement1 @ Comment that will not be retained

statement2 @@ Comment that WILL be retained @@ more commands possible here...

NewRPL has those 2 cases and adds @@@ as a multiline comment that doesn't end until it finds another @@@ so it's useful to comment out entire blocks of code.

Another feature in newRPL is a flag to retain all comments. If it's not set then only @@ comments are kept (those are permanent no matter what).

[c3d]

(08-27-2023 03:56 AM)Claudio L. Wrote:  

(08-27-2023 01:29 AM)rprosperi Wrote:  2 types are definitely valuable as there are (occasional) times that you absolutely want to retain comments even when compiled/on the machine.

To me, these make the most sense:

statement1 @ Comment that will not be retained

statement2 @@ Comment that WILL be retained @@ more commands possible here...

NewRPL has those 2 cases and adds @@@ as a multiline comment that doesn't end until it finds another @@@ so it's useful to comment out entire blocks of code.

Another feature in newRPL is a flag to retain all comments. If it's not set then only @@ comments are kept (those are permanent no matter what).

Hmm. I think this is backwards from a usability perspective: on the calculator, you don't want to waste screen space with two @. It's OK to have @@ on a large computer screen, it's much more annoying on the tiny screen of a calculator.

[Gilles]

Hi all,

I don't really like the idea of comments starting with '$' because '$' is a character that can be used in object names in rpl (variables, programs...).

By the way, I saw that you used lowercase for RPL commands. Does that mean the commands are not case sensitive? I never liked the fact that standard RPL commands were in UPPERCASE (not to mention the ugly triglyphs or whatever that horrible name was!)

[Helix]

(08-26-2023 11:49 PM)c3d Wrote:  So I would like to know how you feel about the following approaches

1) Have two types of comments, one being removed at parse time, the other being preserved. I'm thinking that comments beginning with @ could be preserved and comments beginning with $ or maybe @@ would be eliminated.

2) Change the "standard" style for RPL programs where comments would be on a line on their own, aligned with the code.

I think these are good choices.
@@ would be preferable to $.

[c3d]

(08-27-2023 08:34 AM)Gilles Wrote:  Hi all,

I don't really like the idea of comments starting with '$' because '$' is a character that can be used in object names in rpl (variables, programs...).

Valid point.

Quote:By the way, I saw that you used lowercase for RPL commands. Does that mean the commands are not case sensitive? I never liked the fact that standard RPL commands were in UPPERCASE (not to mention the ugly triglyphs or whatever that horrible name was!)

Yes, at the moment, DB48X is case insensitive. The rendering can use one of four styles (which are all accepted by the parser):

* Legacy ("RKF")
* MixedCase ("InitialValueSolver")
* UPPERCASE ("INITIALVALUESOLVER")
* lowercase ("initialvaluesolver")

At the moment, variable lookup is also case insensitive, so that your 'EQ' variable can be 'eq' or 'Eq'. Some built-in variables also have alternate names, e.g. 'PPAR' can be stored in 'PlotParameters'.

[rprosperi]

(08-27-2023 03:56 AM)Claudio L. Wrote:  NewRPL has those 2 cases and adds @@@ as a multiline comment that doesn't end until it finds another @@@ so it's useful to comment out entire blocks of code.

Another feature in newRPL is a flag to retain all comments. If it's not set then only @@ comments are kept (those are permanent no matter what).

I knew I had seen this before and thought I was remembering these came from NewRPL and planned to verify so today, thanks for confirming so Cladio.

(08-27-2023 06:45 AM)c3d Wrote:  Hmm. I think this is backwards from a usability perspective: on the calculator, you don't want to waste screen space with two @. It's OK to have @@ on a large computer screen, it's much more annoying on the tiny screen of a calculator.

The extra @ on the small screen is a fair point, however I think this is outweighed by the fact that the vast majority of comments in code will be the disposable type, so it makes more sense to use the less visually-disturbing single @ most often. Also, in the PC editor, the @@ will be easier to see when scanning for those sections.

Just my 2 cents...

[John Keith]

(08-27-2023 08:34 AM)Gilles Wrote:  ...Does that mean the commands are not case sensitive? I never liked the fact that standard RPL commands were in UPPERCASE (not to mention the ugly triglyphs or whatever that horrible name was!)

"Original" RPL is case sensitive; it is a convention that global variables (including functions and commands) are upper-case and local variables are lower-case. It is just a convention though- you are free to use N as a local variable or to name a program foo. I would guess that the reason for using capital letters for globals is that lower-case letters are harder to read with the limited screen resolution, especially when using Minifont.

[John Keith]

(08-27-2023 12:08 PM)rprosperi Wrote:  The extra @ on the small screen is a fair point, however I think this is outweighed by the fact that the vast majority of comments in code will be the disposable type, so it makes more sense to use the less visually-disturbing single @ most often. Also, in the PC editor, the @@ will be easier to see when scanning for those sections.

I agree with Claudio and Bob. The flag allowing users to choose makes it a no-brainer. Since RPL is often criticized as a "write-only" language, the use of comments should be strongly encouraged.

[BruceH]

(08-26-2023 11:49 PM)c3d Wrote:  I'm thinking that comments beginning with @ could be preserved and comments beginning with $ or maybe @@ would be eliminated.

Remember that $ is already used in RPL as part of the C$ command to denote a string, so you'd need to be careful not to interfere with it. (HP50G AUR, page 3-31)