Jakiego stylu komentarza powinienem używać w plikach wsadowych?

Piszę kilka plików wsadowych i natknąłem się na ten podręcznik użytkownika , który był dość pouczający. Jedną rzeczą, która mi pokazała, było to, że linie można komentować nie tylko za pomocą REM, ale także za pomocą ::. To mówi:

Komentarze w kodzie wsadowym można wprowadzać za pomocą dwukropka, jest to lepsze niż użycie polecenia REM, ponieważ etykiety są przetwarzane przed symbolami przekierowania. ::<remark>nie powoduje problemów, ale rem <remark>powoduje błędy.

Dlaczego więc większość przewodników i przykładów, które widzę, używa REMpolecenia? Czy ::działa na wszystkich wersjach systemu Windows?

tl; dr: REM to udokumentowany i obsługiwany sposób osadzania komentarzy w plikach wsadowych.

::jest w zasadzie pustą etykietą, do której nigdy nie można przejść, podczas gdy REMjest to rzeczywiste polecenie, które nic nie robi. W żadnym przypadku (przynajmniej w systemie Windows 7) obecność operatorów przekierowań nie powoduje problemu.

Jednak ::wiadomo, że w pewnych okolicznościach źle się zachowuje w blokach, ponieważ jest analizowany nie jako etykieta, ale jako rodzaj litery dysku. Jestem trochę rozmyślany, gdzie dokładnie, ale to samo wystarczy, żebym używał REMwyłącznie. Jest to udokumentowany i obsługiwany sposób osadzania komentarzy w plikach wsadowych, podczas gdy ::jest jedynie artefaktem określonej implementacji.

Oto przykład, w którym ::powstaje problem w FORpętli.

Ten przykład nie działa w pliku o nazwie test.batna pulpicie:

@echo off
for /F "delims=" %%A in ('type C:\Users\%username%\Desktop\test.bat') do (
    ::echo hello>C:\Users\%username%\Desktop\text.txt
)
pause

Chociaż ten przykład będzie działał poprawnie jako komentarz:

@echo off
for /F "delims=" %%A in ('type C:\Users\%username%\Desktop\test.bat') do (
    REM echo hello>C:\Users\%username%\Desktop\text.txt
)
pause

Problem pojawia się podczas próby przekierowania danych wyjściowych do pliku. Domyślam się, że interpretuje to ::jako etykietę ucieczki :echo.

Komentarze z REM

A REMmoże zaznaczyć kompletną linię, także wieloliniowy karetkę na końcu linii, jeśli nie jest to koniec pierwszego tokena.

REM This is a comment, the caret is ignored^
echo This line is printed

REM This_is_a_comment_the_caret_appends_the_next_line^
echo This line is part of the remark

REM, po którym następują niektóre znaki, .:\/=działa nieco inaczej, nie komentuje znaku handlowego i, więc możesz użyć go jako komentarza wbudowanego.

echo First & REM. This is a comment & echo second

Jednak, aby uniknąć problemów z istniejących plików, takich jak REM, REM.batczy REM;.battylko należy stosować zmodyfikowany wariant.

REM^;<space>Comment

A dla postaci ;jest również dozwolone jedno z;,:\/=

REM jest około 6 razy wolniejszy niż ::(testowany na Win7SP1 z 100000 liniami komentarzy).
W przypadku normalnego użytkowania nie jest to ważne (58µs vs. 360µs na linię komentarza)

Komentarze z ::

::Zawsze wykonuje się daszka końcową linię.

:: This is also a comment^
echo This line is also a comment

Etykiety, a także etykieta komentarza :: mają specjalną logikę w blokach nawiasów.
Obejmują one zawsze dwie linie SO: polecenie goto nie działa .
Dlatego nie są zalecane w przypadku bloków nawiasów, ponieważ często są przyczyną błędów składniowych.

Wyświetlana ECHO ONjest REMlinia, ale nie linia komentowana::

Oba nie mogą tak naprawdę komentować reszty linii, więc proste %~spowoduje błąd składniowy.

REM This comment will result in an error %~ ...

Ale REM jest w stanie zatrzymać parser partii na wczesnym etapie, nawet przed zakończeniem fazy postaci specjalnej.

@echo ON
REM This caret ^ is visible

Możesz użyć & REM lub & ::, aby dodać komentarz na końcu wiersza poleceń. To podejście działa, ponieważ „&” wprowadza nowe polecenie w tym samym wierszu.

Komentarze ze znakami procentowymi% = komentarz =%

Istnieje styl komentarza ze znakami procentowymi.

W rzeczywistości są to zmienne, ale są rozszerzone do zera.
Ale zaletą jest to, że można je umieścić w tej samej linii, nawet bez &.
Znak równości gwarantuje, że taka zmienna nie może istnieć.

echo Mytest
set "var=3"     %= This is a comment in the same line=%

Styl procentowy jest zalecany dla makr wsadowych, ponieważ nie zmienia zachowania środowiska wykonawczego, ponieważ komentarz zostanie usunięty po zdefiniowaniu makra.

set $test=(%\n%
%=Start of code=% ^
echo myMacro%\n%
)

Inną alternatywą jest wyrażenie komentarza jako zmiennej, która zawsze rozwija się do zera.

Nazwy zmiennych nie mogą zawierać =, z wyjątkiem nieudokumentowanych zmiennych dynamicznych, takich jak
%=ExitCode%i %=C:%. Żadna nazwa zmiennej nigdy nie może zawierać znaku =po 1. pozycji. Dlatego czasami używam następujących elementów, aby dołączyć komentarze w bloku w nawiasach:

::This comment hack is not always safe within parentheses.
(
  %= This comment hack is always safe, even within parentheses =%
)

Jest to również dobra metoda wprowadzania komentarzy w linii

dir junk >nul 2>&1 && %= If found =% echo found || %= else =% echo not found

Prowadzenie =nie jest konieczne, ale podoba mi się symetria.

Istnieją dwa ograniczenia:

1) komentarz nie może zawierać %

2) komentarz nie może zawierać :

Po tym, jak zdałem sobie sprawę, że mogę używać etykiety ::do komentowania i komentowania kodu, REMwyglądało to dla mnie brzydko. Jak już wspomniano, dwukropek może powodować problemy, gdy jest używany w ()zablokowanym kodzie, ale odkryłem obejście, zmieniając etykiety ::i:space

:: This, of course, does
:: not cause errors.

(
  :: But
   : neither
  :: does
   : this.
)

To nie jest brzydkie REMi faktycznie dodaje trochę stylu do twojego kodu.

Więc poza blokami kodu używam ::i wewnątrz nich na przemian ::i :.

Nawiasem mówiąc, w przypadku dużych fragmentów komentarzy, takich jak nagłówek pliku wsadowego, można całkowicie uniknąć specjalnych poleceń i znaków, po prostu umieszczając gotokomentarze. To pozwala nam użyć dowolnej metody lub stylu znaczników, jaki chcesz, pomimo faktu, że gdyby CMDkiedykolwiek próbował przetworzyć te linie, rzuciłby syk.

@echo off
goto :TopOfCode

=======================================================================
COOLCODE.BAT

Useage:
  COOLCODE [/?] | [ [/a][/c:[##][a][b][c]] INPUTFILE OUTPUTFILE ]

Switches:
       /?    - This menu
       /a    - Some option
       /c:## - Where ## is which line number to begin the processing at.
         :a  - Some optional method of processing
         :b  - A third option for processing
         :c  - A forth option
  INPUTFILE  - The file to process.
  OUTPUTFILE - Store results here.

 Notes:
   Bla bla bla.

:TopOfCode
CODE
.
.
.

Użyj dowolnej notacji, którą chcesz *, @itp.

Ta odpowiedź jest próbą pragmatycznego podsumowania wielu świetnych odpowiedzi na tej stronie:

^{Świetna odpowiedź jeba zasługuje na specjalną wzmiankę, ponieważ naprawdę jest dogłębna i obejmuje wiele przypadków krawędzi.
W szczególności zwraca uwagę, że źle skonstruowane odwołanie do zmiennej / parametru, takie jak %~może złamać dowolne z poniższych rozwiązań - w tym REMlinie .}

Komentarze całej linii - jedyny bezpośrednio obsługiwany styl:

• REM(lub jego warianty) jest jedynym oficjalnym konstruktem komentarzy i jest najbezpieczniejszym wyborem - patrz pomocna odpowiedź Joeya .

• ::to (powszechnie stosowany) hack , który ma zalety i wady :

  • Plusy :

    • Wizualna odrębność i być może łatwość pisania.
    • Prędkość , mimo że prawdopodobnie rzadko sprawa - zobacz wielką odpowiedź Jeb za i Rob van der Woude wspaniałe blogu .

  • Wady :

    • Wewnątrz (...)bloków ::można złamać polecenie , a zasady bezpiecznego użytkowania są restrykcyjne i trudne do zapamiętania - patrz poniżej.

Jeśli nie chcesz używać:: , masz te opcje:

• Albo : Aby być bezpiecznym, zrobić wyjątek wewnątrz (...)bloków i używać REMtam, czy nie należy umieszczać komentarzy wewnątrz (...) całkowicie.
• Lub : Zapamiętaj boleśnie restrykcyjne zasady bezpiecznego korzystania z ::wnętrza(...) , które zostały streszczone w następującym fragmencie:

@echo off

for %%i in ("dummy loop") do (

  :: This works: ONE comment line only, followed by a DIFFERENT, NONBLANK line.
  date /t

  REM If you followed a :: line directly with another one, the *2nd* one
  REM would generate a spurious "The system cannot find the drive specified."
  REM error message and potentially execute commands inside the comment.
  REM In the following - commented-out - example, file "out.txt" would be
  REM created (as an empty file), and the ECHO command would execute.
  REM   :: 1st line
  REM   :: 2nd line > out.txt & echo HERE

  REM NOTE: If :: were used in the 2 cases explained below, the FOR statement
  REM would *break altogether*, reporting:
  REM  1st case: "The syntax of the command is incorrect."
  REM  2nd case: ") was unexpected at this time."

  REM Because the next line is *blank*, :: would NOT work here.

  REM Because this is the *last line* in the block, :: would NOT work here.
)

Emulacja innych stylów komentarzy - liniowy i wieloliniowy:

Pamiętaj, że żaden z tych stylów nie jest bezpośrednio obsługiwany przez język wsadowy , ale można go emulować .

Komentarze wbudowane :

<sup>* Poniższe fragmenty kodu służą verjako stand-in dla dowolnego polecenia, aby ułatwić eksperymentowanie.
* Aby SETpolecenia działały poprawnie z wbudowanymi komentarzami, dwukrotnie cudzysłów name=value; np SET "foo=bar". [1]</sup>

W tym kontekście możemy wyróżnić dwa podtypy:

• Komentarze EOL ([do-końca] wiersza), które można umieścić po poleceniu i niezmiennie rozciągają się na koniec wiersza (ponownie, dzięki uprzejmości odpowiedzi jeba ):

  • ver & REM <comment>wykorzystuje fakt, że REMjest to poprawne polecenie i &może być użyte do umieszczenia dodatkowego polecenia po istniejącym.
  • ver & :: <comment>działa również, ale tak naprawdę można go używać tylko poza (...)blokami , ponieważ jego bezpieczne użycie jest jeszcze bardziej ograniczone niż używanie ::samodzielne.

• Komentarze wewnątrz wiersza , które można umieszczać między wieloma poleceniami w wierszu lub idealnie nawet wewnątrz danego polecenia.
  Komentarze wewnątrz wiersza są najbardziej elastyczną (jednowierszową) formą i mogą z definicji być również używane jako komentarze EOL.

  • ver & REM^. ^<comment^> & verpozwala na wstawienie komentarza między poleceniami (ponownie, dzięki uprzejmości odpowiedzi jeba ), ale zwróć uwagę, jak <i >trzeba było ^przeskalować, ponieważ następujące znaki. nie można używać w stanie „tak jak jest”:< > | (podczas gdy nieskalowane &lub &&lub ||uruchomić następną komendę).

  • %= <comment> =%, jak opisano w świetnej odpowiedzi dbenham , jest najbardziej elastyczną formą , ponieważ można ją umieścić w poleceniu (wśród argumentów) .
    Korzysta ze składni rozszerzania zmiennych w sposób, który zapewnia, że ​​wyrażenie zawsze rozwija się do pustego łańcucha - tak długo, jak tekst komentarza nie zawiera %ani „:
    Like” REM, %= <comment> =%działa dobrze zarówno na zewnątrz, jak i wewnątrz (...)bloków, ale jest bardziej wyrazisty; jedyną wadą jest to, że trudniej jest pisać, łatwiej jest popełnić błąd składniowy i nie jest to powszechnie znane, co może utrudniać zrozumienie kodu źródłowego używającego tej techniki.

Komentarze do wielu linii (blok całej linii) :

• Odpowiedź Jamesa K pokazuje, jak używać gotooświadczenia i etykiety do określenia wieloliniowego komentarza o dowolnej długości i treści (który w jego przypadku wykorzystuje do przechowywania informacji o użytkowaniu).

• Odpowiedź Zee pokazuje, jak używać „etykiety zerowej”, aby utworzyć komentarz wielowierszowy, chociaż należy zachować ostrożność, aby zakończyć wszystkie linie wewnętrzne ^.

• Rob van der Woude na blogu wspomina inny nieco niejasne opcję, która pozwala zakończyć plik z dowolnej liczby linii komentarza : AN otwarcie (tylko powoduje wszystko, co przychodzi po które mają być ignorowane , o ile nie zawierają (nie ^-scaped) ), tzn. dopóki blok nie jest zamknięty .

^{[1] Używanie SET "foo=bar"do definiowania zmiennych - tj. Umieszczanie podwójnych cudzysłowów wokół nazwy i połączonej= wartości - jest konieczne w poleceniach takich , aby zapewnić, że to, co następuje po zamierzonej wartości zmiennej (w tym przypadku do następnego polecenia) pojedyncza spacja) nie przypadkowo staje się jej częścią. (Nawiasem mówiąc : nie tylko nie uniknie problemu, ale sprawi, że podwójne cudzysłowy będą częścią wartości ). Zauważ, że ten problem jest nieodłączny, a nawet dotyczy przypadkowych spacji końcowych po wartości, dlatego zaleca się, aby zawsze stosować to podejście.SET "foo=bar" & REM Set foo to bar.
SET foo="bar"
SETSET "foo=bar"}

Ta strona mówi, że użycie „::” będzie szybsze pod pewnymi ograniczeniami. Tylko jedną rzecz do rozważenia przy wyborze

dobre pytanie ... zbyt długo szukałem tej funkcjonalności ...

po kilku testach i sztuczkach wydaje się, że lepszym rozwiązaniem jest bardziej oczywiste ...

-> najlepszym sposobem, jaki znalazłem, aby to zrobić, zapobiegając awarii integralności parsera, jest ponowne użycie REM:

echo this will show until the next REM &REM this will not show

możesz także użyć multilinii ze sztuczką „NULL LABEL” ... (nie zapomnij o ^ na końcu linii dla zachowania ciągłości)

::(^
this is a multiline^
comment... inside a null label!^
dont forget the ^caret at the end-of-line^
to assure continuity of text^ 
)

James K, przepraszam, że się myliłem w sporej części tego, co powiedziałem. Test, który wykonałem, był następujący:

@ECHO OFF
(
  :: But
   : neither
  :: does
   : this
  :: also.
)

Spełnia to opis naprzemiennego, ale kończy się niepowodzeniem, gdy „) było w tej chwili nieoczekiwane”. Komunikat o błędzie.

Dzisiaj przeprowadziłem kilka testów i okazało się, że naprzemienne nie jest kluczem, ale wygląda na to, że klucz ma parzystą liczbę wierszy, nie ma żadnych dwóch wierszy z rzędu, zaczynając od podwójnych dwukropków (: :) i nie kończąc na podwójnych dwukropkach . Rozważ następujące:

@ECHO OFF
(
   : But
   : neither
   : does
   : this
   : cause
   : problems.
)

To działa!

Ale również weź to pod uwagę:

@ECHO OFF
(
   : Test1
   : Test2
   : Test3
   : Test4
   : Test5
   ECHO.
)

Wydaje się, że zasada kończenia polecenia na parzystej liczbie komentarzy nie ma zastosowania.

Niestety jest to wystarczająco wiewiórcze, że nie jestem pewien, czy chcę go użyć.

Naprawdę najlepszym rozwiązaniem i najbezpieczniejszym, o jakim mogę myśleć, jest to, że program taki jak Notepad ++ odczytuje REM jako podwójne dwukropki, a następnie zapisuje podwójne dwukropki jako instrukcje REM po zapisaniu pliku. Ale nie znam takiego programu i nie znam żadnych wtyczek do Notepad ++, które to robią.

Bardzo szczegółowa i analityczna dyskusja na ten temat dostępna jest na TEJ stronie

Ma przykładowe kody i zalety / wady różnych opcji.

Istnieje wiele sposobów komentowania w pliku wsadowym

1) Korzystanie z rem

To jest oficjalny sposób. Najwyraźniej trwa dłużej niż ::, choć najwyraźniej przestaje się analizować wcześniej, zanim zostaną przetworzone instrukcje. Wzrost procentowy następuje przed rem i ::jest identyfikowany, więc nieprawidłowe użycie procentowe, tj. %~Spowoduje błędy, jeśli procent będzie obecny. Bezpieczny w użyciu w dowolnym miejscu w blokach kodu.

2) Za pomocą etykiet :, ::lub :;etc.

Ponieważ :: comment„: komentarz” jest nieprawidłową nazwą etykiety, ponieważ zaczyna się od niepoprawnego znaku. Można jednak używać dwukropka na środku etykiety. Jeśli przestrzeń zaczyna się na początku etykiecie, jest on usuwany : labelstaje :label. Jeśli na środku etykiety pojawi się spacja lub dwukropek, reszta nazwy nie zostanie zinterpretowana, co oznacza, że ​​jeśli istnieją dwie etykiety :f:ooi :f rrobie zostaną zinterpretowane jako :fi tylko do później zdefiniowanej etykiety w pliku zostanie przeniesiona. Reszta etykiety jest faktycznie komentarzem. Istnieje wiele alternatyw ::, wymienionych tutaj . Nigdy nie można gotolub etykieta. i nie będzie działać.call::foogoto :foogoto ::foo

Działają dobrze poza blokami kodu, ale po etykiecie w bloku kodu, niepoprawnej lub nie, musi istnieć poprawny wiersz polecenia. :: commentjest rzeczywiście innym ważnym poleceniem. Interpretuje to jako polecenie, a nie etykietę; polecenie ma pierwszeństwo. Które jest poleceniem cd do ::woluminu, który zadziała, jeśli wykonałeś subst :: C:\, w przeciwnym razie nie będzie można znaleźć błędu woluminu. Dlatego :;jest prawdopodobnie lepszy, ponieważ nie można go interpretować w ten sposób, a zatem jest interpretowany jako etykieta, która służy jako prawidłowe polecenie. Nie jest to rekurencyjne, tzn. Następna etykieta nie wymaga polecenia po niej. Dlatego przychodzą dwójkami.

Musisz podać prawidłowe polecenie po etykiecie, np echo something. Etykieta w bloku kodu musi zawierać co najmniej jedno prawidłowe polecenie, więc linie występują w parach po dwie. Otrzymasz nieoczekiwany )błąd, jeśli w następnym wierszu znajduje się spacja lub nawias zamykający. Jeśli między dwiema ::liniami jest spacja , pojawi się nieprawidłowy błąd składniowy.

Możesz także użyć operatora karetki w ::komentarzu w następujący sposób:

@echo off

echo hello
(
   :;(^
   this^
   is^
   a^
   comment^
   )
   :;
)
   :;^
   this^
   is^
   a^
   comment
   :;
) 

Ale potrzebujesz podążania :;z podanego powyżej powodu.

@echo off

(
echo hello
:;
:; comment
:; comment
:;
)
echo hello

Jest w porządku, o ile jest parzysta liczba. Jest to bez wątpienia najlepszy sposób komentowania - z 4 liniami i :;. Ze :;nie dostaniesz wszelkie błędy, które muszą być tłumione za pomocą 2> nullub subst :: C:\. Możesz użyć, subst :: C:\aby błąd nie znaleziono woluminu zniknął, ale oznacza to, że będziesz musiał również wstawić C: w kodzie, aby zapobiec zmianie katalogu roboczego ::\.

Do komentarza na końcu wiersza można zrobić, command &::albo command & rem comment, ale wciąż musi być numer nawet, tak jak poniżej:

@echo off

(
echo hello & :;yes
echo hello & :;yes
:;
)

echo hello

Pierwszy echo hello & :;yesma prawidłowe polecenie w następnym wierszu, ale drugi & :;yesnie, więc potrzebuje jednego, tj :;.

3) Używanie niepoprawnej zmiennej środowiskowej

%= comment =%. W pliku wsadowym niezdefiniowane zmienne środowiskowe są usuwane ze skryptu. Umożliwia to używanie ich na końcu linii bez użycia &. Zwyczajowo używa się niepoprawnej zmiennej środowiskowej, tj. Zawierającej znak równości. Dodatkowa równość nie jest wymagana, ale sprawia, że ​​wygląda symetrycznie. Ponadto nazwy zmiennych rozpoczynające się od „=” są zarezerwowane dla nieudokumentowanych zmiennych dynamicznych. Te zmienne dynamiczne nigdy nie kończą się na „=”, więc używając „=” zarówno na początku, jak i na końcu komentarza, nie ma możliwości kolizji nazw. Komentarz nie może zawierać %lub :.

@echo off 
echo This is an example of an %= Inline Comment =% in the middle of a line.

4) Jako polecenie przekierowuję stderr na nul

@echo off
(
echo hello
;this is a comment 2> nul
;this is another comment  2> nul
)

5) Na końcu pliku wszystko po niezamkniętym nawiasie jest komentarzem

@echo off
(
echo hello
)

(this is a comment
this is a comment
this is a comment