About syntax highlighting comments in batch files

[FichteFoll]

From @darkred on October 23, 2015 20:48

It's about syntax highlighting to comments batch files: currently they are highlighted just like commands, and so you can't distinguish commands from comments. Screenshot: A comment line should be gray (as a whole).

Thank you

PS. Using Sublime Text 3 in win10x64.

Copied from original issue: SublimeTextIssues/Core#1014

[FichteFoll]

Well, technically "REM" is a command that just does nothing. Iirc.

You can use :: for comments that will also be highlighted as comments.

[darkred]

I quote from this StackExchange question: Which comment style should I use in batch files?

REM is the documented and supported way to embed comments in batch files.

---

:: is essentially a blank label that can never be jumped to, whereas REM is an actual command that just does nothing. In neither case (at least on Windows 7) does the presence of redirection operators cause a problem.

However, :: is known to misbehave in blocks under certain circumstances, being parsed not as a label but as some sort of drive letter. I'm a little fuzzy on where exactly but that alone is enough to make me use REM exclusively. It's the documented and supported way to embed comments in batch files whereas :: is merely an artifact of a particular implementation.

Highlighting comments the same way in both cases is what it should be. Also, while creating new batch files, you may use ::, but when viewing existing batch files (especially large ones), currently you have to search&replace all instances of REM to ::, i.e. editing an already working ok batch file, with the possibility of making it misbehave.

[darkred]

More details on the pitfalls of using :: for comments http://www.robvanderwoude.com/comments.php http://www.experts-exchange.com/OS/Microsoft_Operating_Systems/MS_DOS/Q_21498411.html http://ss64.com/nt/rem.html

I quote from the 1st link:

---

A true pitfall are code blocks, several commands grouped between parentheses and interpreted as a single command line by CMD.EXE!

IF EXIST C:\AUTOEXEC.BAT (
    :: Comment line 1
    ECHO Do something
    :: Comment line 2
)

will result in an error message stating:

) was unexpected at this time.

and:

IF EXIST C:\AUTOEXEC.BAT (
    :: Comment line 1
    ECHO Do something
    :: Comment line 2
    :: Comment line 3
)

will result in another error message:

Do something
The system cannot find the drive specified.

The same is true for FOR loops. Try and see for yourself:

FOR %%A IN (1 2 3) DO (
    :: Comment line 1
    ECHO Do something
    :: Comment line 2
)

and:

FOR %%A IN (1 2 3) DO (
    :: Comment line 1
    ECHO Do something
    :: Comment line 2
    :: Comment line 3
)

will also result in error messages.

The errors are caused by labels being used within code blocks. Replace the double colons by REM statements and these samples will all run without a glitch. Better still, don't use comments within code blocks at all, but place them just before the code blocks instead:

:: Comment line 1
:: Comment line 2
:: Comment line 3
FOR %%A IN (1 2 3) DO (
    ECHO Do something
)

or:

REM Comment line 1
REM Comment line 2
REM Comment line 3
FOR %%A IN (1 2 3) DO (
    ECHO Do something
)

Summarizing:

• REM is the standards-compliant, documented statement to insert comments in batch files
• double colons are a non-documented and non-compliant way to insert comments
• in theory, using double colons may speed up execution of batch files when run from a slow disk drive (e.g. floppy disk), but I doubt the difference can be detected on modern computers
• for large blocks of comment, a GOTO command just before the comments, jumping to a label just after the comments, is a safer and more standards-compliant way to speed up batch execution from slow drives
• since double colons are actually labels, they should be placed at the start of a command line; leading whitespace is allowed, nothing else is
• using double colons inside code blocks violates the previous "rule" and will result in errors
• try to avoid comments inside code blocks, or use REM if you have to
• be careful when using either REM or double colons to temporarily "disable" a command line, especially when it contains piping, redirection or variables
• despite all, there is nothing wrong with using double colons for comments as long as you understand the limitations
• test, test, test and test your batch files, including comment lines

[FichteFoll]

I'm not exactly sure what you are arguing about (or why), since I'm very well aware that REM is the proper way of using comments.

That said, I noticed a few days ago that this actually works for me, so ... maybe you're on an older build. I'm on 3095 and get this:

[darkred]

But, I don't want to argue with you.. I just wanted to highlight the pitfalls that may occur by using :: for comments. I faced such errors in my batch files myself, while trying (based on your previous comment) to convert the comments from REM to ::.

Yes, I use an older build, 3083. It's nice that in build 3095 the text in the REM lines are now gray, but it would be even better if the REM part was gray too, thus helping the user focus better on the actual code, visually ignoring the comments. That's my feature request.

[FichteFoll]

That may be user preference, and luckily Sublime Text allows you to easily configure the syntax highlighting to make the REM comment-colored as well.

I'm leaning more to the "highlight a command as a command" side, but to each their own. Closing issue as fixed.

[darkred]

Could you please show me how to make the REM grayed out?

I checked https://www.sublimetext.com/docs/3/syntax.html but I'm not sure how to make this.

[FichteFoll]

Change

    - match: (?:^|\s)((?i)rem)(?:$|\s.*$)
      scope: comment.line.rem.dosbatch
      captures:
        1: keyword.command.rem.dosbatch

to

    - match: (?:^|\s)((?i)rem)(?:$|\s.*$)
      scope: comment.line.rem.dosbatch

[darkred]

Thank you for your help.

[darkred]

@FichteFoll

(Currently using ST3 build 3120) I've noticed that the REM-related code in the Batch File.sublime-syntax has been changed:

    # REM command
    # https://technet.microsoft.com/en-us/library/bb490986.aspx
    - match: \b(?i)rem\b
      scope: keyword.command.rem.dosbatch
      push:
        - meta_content_scope: comment.line.rem.dosbatch
        - match: \n
          pop: true
        - match: '[(|)]'
          scope: invalid.illegal.unexpected-character.dosbatch

i.e. there's no

      captures:
        1: keyword.command.rem.dosbatch

part now. How can I make the REM grayed out again? Could you please help me once more?

[insurgencymodscum]

Today is August 17, 2016 and this issue is still not closed. I'm using ST3 Build 3114.

Display rem as :: comments:

Filename: Batch File.sublime-syntax

    # REM
    - match: \b(?i)rem\b

      # original sublime text 3 build 3114 code:
      # scope: keyword.command.rem.dosbatch

      # fixed. highlight "rem" as a "::" comment
      scope: comment.line.colon.dosbatch

      push:
        - meta_content_scope: comment.line.rem.dosbatch
        - match: \n
          pop: true
        - match: '[(|)]'
          scope: invalid.illegal.unexpected-character.dosbatch

[FichteFoll]

@darkred, remove the scope: keyword.command.rem.dosbatch line and change meta_content_scope to meta_scope (which is should have been from the start imo).

@insurgencymodscum, not sure what your exact problem is. The issue reported in OP is fixed for me.

[darkred]

@darkred, remove the scope: keyword.command.rem.dosbatch line and change meta_content_scope to meta_scope (which is should have been from the start imo).

Thank you very much, @FichteFoll.