﻿NFORenum -- Příkazy v komentářích
=================================

NFORenum lze ovládat vložením příkazů popsaných v tomto textu do kódu
analyzovaného NFO souboru. Všechny tyto příkazy musí obsahovat prefix "@@".
Příkazy jsou efektivní ihned, ale nemají vliv na řádky, které jim předchází.
Příkazy nelze vkládat doprostřed pseudo-spritů. V případě, že takto učiníte,
NFORenum umístí zbytek pseudo-spritu do komentáře.
Některé příkazy lze také zadat na příkazové řádce. Výstup příkazu "renum -?"
obsahuje více informací o tom, který parametr odpovídá kterému příkazu.

Na příkazové řádce lze použít znaky + a - jako alternativu pro ON a OFF. Takto
můžete použít např. "-l-" k vypnutí kontroly kódu nebo "-b+" k zapnutí auto-
matického formátování.

V příkazech lze místo mezer či tabulátorů také použít rovnítka "="; tato
alternativa existuje pro ulehčení specifikace jejich ekvivalentů na příkazové
řádce (např. -b setcookie=686031766).

Od verze 2.8.6 NFORenum nerozlišuje velikost znaků v názvu příkazů, ale velká
písmena jsou považována za standard.

Jestliže není jinak uvedeno, za každý příkaz lze přidat argument NOPRESERVE.
V případě, že tak učiníte, bude tento příkaz po provedení z NFO souboru
odstraněn. V opačném případě je příkaz vložen do výsledného NFO.


@@PRESERVEMESSAGES
@@REMOVEMESSAGES

Tyto příkazy způsobí zachování/odstranění starých zpráv NFORenumu z NFO.
Standardní chování je odstranit tyto zprávy.

@@BEAUTIFY [parametr [hodnota]]

Tato sbírka příkazů ovládá formátování kódu - beautifier. Parametry, jejich
rozsah a standardní hodnoty jsou uvedeny v následujícím textu.

ON|OFF
Vypíná a zapíná beautifier. Standardní hodnota je OFF, ale beautifier bude
automaticky zapnut při nastavení kteréhokoliv jiného parametru (včetně
GETCOOKIE).

CONVERTONLY ON|OFF (standardně OFF)
Když je tento parametr zapnut, tak se NFORenum pokusí co nejlépe zachovat
formát vstupních spritů když provádí změny dle parametrů HEXGRFID, QUOTEUTF8 a
QUOTEHIGHASCII. Dále také při zapnutém parametru CONVERTONLY ignoruje hodnotu
parametrů LEADINGSPACE, LINEBREAKS a MAXLEN.

HEXGRFID ON|OFF (standardně OFF)
Když je tento parametr zapnut, tak budou veškerá GRFID vypsána jako šestnáctková
čísla. Když je vypnut, tak jsou první znaky vypsány jako řetězec (jsou-li
tisknutelné) a zbylé dva jsou vypsány jako šestnáctková čísla. Znak FF není
v GRFID považován za tisknutelný znak, takže GRFID FF FF FF FF bude vypsáno
celé v šestnáctkové soustavě.

LEADINGSPACE <num-beaut1>[,<num-beaut2>[,<num-linelen>]]
  (rozsah 1..32 pro každou hodnotu, standardně 5,8,11)
Tento parametr specifikuje počet mezer, jež budou přidány na začátek nové řádky.
<num-beaut1> se používá v místech, kde je obvyklé menší odsazení (např. po 00
v akci 4), <num-beaut2> pro větší odsazení (např. po OD v řetězcích) a
<num-linelen> v řádcích, které bylo nutno rozdělit, protože byly příliš dlouhé.
Jestliže zadáte hodnotu 0, použije NFORenum původní hodnotu parametru.
Jestliže některou hodnotu nezadáte, tak NFORenum automaticky použije hodnotu
o 3 větší než je hodnota předchozí (a nebo původní hodnota, je-li to 0).
(Takže LEADINGSPACE 1 a LEADINGSPACE 1, 4, 7 jsou ekvivalentní.)
Zadání hodnoty vyšší než 32 způsobí chybu programu.

LINEBREAKS <num> (0..3, standardně 2)
Tento parametr ovládá frekvenci vytváření nových řádek. Hodnota 0 představuje
nejnižší frekvenci, což znamená, že nový řádek bude vytvořen dle parametru
MAXLEN. Hodnota 3 představuje frekvenci nejvyšší, kdy NFORenum vytváří nové
řádky skoro všude.

MAXLEN <num> (0..255, standardně 78)
Nejvyšší povolený počet znaků na jednom řádku. Úvod spritu (0 * 0 ...) se
bere jako šestnáct znaků. Když zadáte hodnotu 0, tak bude nové řádky vytvářet
jen beautifier.

QUOTEHIGHASCII ON|OFF (standardně ON)
Když je tento parametr vypnut, tak jsou znaky z vyšší poloviny ASCII tabulky
(kódy 80..FF) vždy vypsány jako šestnáctková čísla. Když je zapnut, NFORenum
vypisuje tyto znaky přímo do řetězců. Bez ohledu na hodnotu tohoto parametru
nebudou znaky 00..1F, 7B..A0, AA, AC, AD, AF a B4..B8 nikdy vypsány pokud
nejsou v sekvenci UTF-8. Vypisování znaků z vyšší poloviny ASCII tabulky
obsažených v UTF-8 řetězcích ovládá následující parametr.

QUOTEUTF8 ON|OFF (standardně ON)
Když je tento parametr vypnut, sekvence UTF-8 obsažené v řetězcích budou vždy
vypsány jako šestnáctková čísla. V opačném případě jsou tyto znaky vypisovány
přímo do řetězců. Vypisování znaků z vyšší poloviny ASCII tabulky neobsažených
v řetězcích UTF-8 (řetězce začínající znakem U+00DE - Þ) ovládá předchozí
parametr.

GETCOOKIE
Příkaz bude nahrazen "@@BEAUTIFY SETCOOKIE <cookie>", kde <cookie> je stávající
tzv. "magic cookie" - hodnota představující kompletní nastavení beautifieru.
Zadání parametru "-b getcookie" nebo jeho ekvivalentu na příkazové řádce způsobí
zaslání příkazu SETCOOKIE na standardní výstup.

SETCOOKIE <cookie>
Tento příkaz obnoví nastavení všech předchozích parametrů do stavu, ve kterém
byly když příkaz GETCOOKIE zapsal hodnotu <cookie>. Hodnota <cookie> nemá žádné
jiné použití.


@@CLEARACTION2

Tento příkaz způsobí, že se analyzér akcí 1/2/3 zachová jako by narazil na konec
souboru. Analyzér vydá varování o všech dosud nepoužitých skupinách spritů
z přecházejících akcí 1. Analyzér dále provede veškeré kontroly nevyužitých
cargo ID, které jsou obvykle prováděny na konci souboru, a poté označí všechna
cargo ID jako nedefinovaná.


@@CLEARACTIONF

Tento příkaz funguje podobně jako příkaz CLEARACTION2, s tím rozdílem, že
ovlivňuje funkci analyzéru akcí F a názvů měst.


@@DEFINEID2 <feature> <id>

Označí <id> pro <feature> jako definované. Kontrola nevyužitých předcházejících
definicí v tomto případě neprobíhá.
Hodnoty <feature> a <id> musí obě obsahovat 2 šestnáctkové číslice.


@@DIFF

Tento příkaz uzpůsobí výstup programu k usnadnění porovnání rozdílů a tvorby
tzv. diffů. Obsahuje v sobě také funkci příkazů @@REMOVEMESSAGES a @@SANITY OFF.
Každý sprite v NFO souboru bude očíslován číslem -1 a jeho délka bude nastavena
na 0. Sprite č. 0 bude hlásit 0 spritů a NFORenum nebude již nebude do
výstupního souboru vypisovat žádné další zprávy.

Tento příkaz nikdy nebude zapsán zpět do NFO souboru.


@@LET <prom> [=] <výraz>

Tento příkaz se hodí pro přiřazení hodnoty proměnné před použitím ve výpočtech
v real-spritech. Výrazy v real-spritech mají stejný formát jako výrazy v příkazu
@@LET.
Název proměnné <prom> je jakýkoliv platný identifikátor jazyka C (první znak
musí být A..Z, a..z nebo _, všechny další musí být A..Z, a..z, 0..9 nebo _).
<výraz> je jedno z:
1) RPN výraz, uzavřený v závorkách. (Více detailů v README.RPN.cz.txt)
2) celé číslo se znaménkem.


@@LINT {OFF|NONE|FATAL|ERROR|WARNING(1-4)}

Tento přepínač slouží k ovládání funkcí kontroly kódu. Použití parametru OFF
vypne kontrolu kódu až do konce stávajícího souboru. Parametr NONE potlačí
veškeré zprávy, ale kontrola pokračuje. Další parametry potlačují zprávy
důležitosti nižší, než je hodnota parametru. Kritická chyba nastane, když systém
kontroly kódu nemůže, nebo nemá zájem, pokračovat v analýze spritu. Chyby
nastanou v případech, že analýza může pokračovat, avšak výsledný kód by nebyl
akceptován TTDPatchem. Varování se týkají spritů, které by TTDPatch přijal, ale
stejně jsou asi špatně. Standardní hodnota je WARNING3.
Přepínač LINT neovlivňuje chybová hlášení způsobená chybou analýzy kódu, které
varují o věcech, které GRFCodec nepřijme.


@@LOCATEID2 [<feature>] <id>

Tento příkaz způsobí vypsání zprávy ve formátu "//!!LOCATEID2 <feature> <id>:
<spritenum>", kde <spritenum> je číslo spritu obsahujícího poslední přecházející
definici <id>, a <feature> odpovídá hodnotě feature asociované s <id>.
Jestliže byla poslední definice <id> provedena příkazem @@DEFINEID2, hodnota
<spritenum> není definována.
<feature> (jestliže je zadána) a <id> musí obě obsahovat 2 šestnáctkové číslice.
Hodnota <feature> není nutná. Jestliže je přítomna, a je validní, bude
odstraněna.

@@REALSPRITES {RPNON|RPNOFF|COMMENTON|COMMENTOFF}

Tento přepínač ovládá kontrolu real-spritů.
Parametry RPNON/RPNOFF zapínají a vypínají vyhodnocování RPN výrazů. Parametr
RPNOFF také automaticky nastaví COMMENTOFF. Tuto funkci lze potlačit zadáním
příkazu "@@REALSPRITES COMMENTON" ihned po příkazu "@@REALSPRITES RPNOFF".
Jestliže metadata obsahují RPN výraz a je nestavena jak hodnota RPNOFF, tak
hodnota COMMENTOFF, NFORenum nevydá žádné chybové hlášení.
Parametry COMMENTON/COMMENTOFF zapínají a vypínají funkci přesunutí neanalyzo-
vatelných metadat real-spritů do komentáře. Real-sprity, kterým zdánlivě chybí
název souboru, budou vždy přesunuty; analyzovat je by znamenalo riskovat ztrátu
dat v případech, že to je jen pokračování pseudo-spritu obsahujícího chybný
znak.

@@TESTID2 [<feature>] <id>

Zkontroluje, jestli je <id> definováno, ale neoznačí jej jako použité.
<feature> (jestliže je zadána) a <id> musí obě obsahovat 2 šestnáctkové číslice.
Hodnota <feature> není nutná. Jestliže je přítomna, a je validní, bude
odstraněna.


@@USEID2 [<feature>] <id>

Jestliže je <id> definováno, NFORenum jej označí jako použité.
<feature> (jestliže je zadána) a <id> musí obě obsahovat 2 šestnáctkové číslice.
Hodnota <feature> není nutná. Jestliže je přítomna, a je validní, bude
odstraněna.


@@USEOLDSPRITENUMS {ON|OFF}

Zapnutím tohoto přepínače přepnete NFORenum do módu, kdy nebude upravovat čísla
spritů, ale bude vypisovat původní hodnoty. Příkaz @@DIFF toto chování anuluje.


@@USESET <skupina>

Tento příkaz slouží jako náhradní řešení pro neschopnost NFORenumu správně
analyzovat akci 6. Použitím tohoto příkazu potlačíte chybová hlášení o nepou-
žitých skupinách spritů pro dané id skupiny až do další akce 1.
Hodnota <skupina> musí obsahovat 2 šestnáctkové číslice. V ostatních případech
je chování programu nedefinováno.


@@VERSIONCHECK <ver> <název>

Použitím tohoto příkazu vložíte do NFO souboru kód pro kontrolu verze TTDPatche.
<ver> může být v jednom z následujících formátů:
1) Desítková čísla oddělená tečkou, např. 2.0.10.640 pro verzi 2.0.1 alpha 64.
2) Osmiznakový kód verze, nejlépe získaný ze souboru switches.xml.
3a) "Hovorové" číslo verze, buď s tečkou nebo bez (201a<číslo>, 2.0.1a<číslo>,
    25b<číslo> nebo 2.5b<číslo>) např. 201a66 pro 2.0.1 alpha 66
3b) "Hovorové" číslo verze, buď s tečkou nebo bez (2<minor>r<rev> nebo
    2.<minor>r<num>), pro verze TTDPatche r418 a novější.
Formát 3a nelze použít k uvedení verze, která není v sérii 2.0.1 alpha nebo
2.5 beta, stejně jako číslo neoficiální verze. Pro čísla verze 2.5 beta 6
a novější, NFORenum vyhledává odpovídající čísla revizí v datovém souboru
versions.dat. Jestliže tento soubor nebyl upraven po vydání nové verze 2.5 beta
kterou chcete zjistit, musíte použít formátu 3b.
<název> je pro člověka čitelný název verze TTDPatche, buď jako skupina bytů,
nebo jako řetězec. Jestliže to je řetězec, NFORenum sám přidá koncový byte 00.
Následující řádky ukazují několik možností, jak kontrolovat verzi TTDPatche
2.0.1 alpha 63 a vyšší:
//@@VERSIONCHECK 020A0276 "2.0.1 alpha 63"
//@@VERSIONCHECK 2.0.10.630 32 2e 30 2e 31 20 61 6c 70 68 61 20 36 33
//@@VERSIONCHECK 201a63 "2.0.1 alpha 63"
//@@VERSIONCHECK 2.0.1a63 "2.0.1 alpha 63"

Tento příkaz nikdy nebude vypsán zpět do výstupního NFO souboru.

@@WARNING {ENABLE|DEFAULT|DISABLE} <číslo>

Tento příkaz umožňuje ovládání zobrazování specifických chybových hlášení
systému kontroly kódu. Parametr ENABLE zapne zobrazování daného chybového
hlášení bez ohledu na stávající úroveň varování. Parametr DISABLE vypne zobra-
zování daného chybového hlášení bez ohledu na stávající úroveň varování.
Parametr DEFAULT buď zapne nebo vypne zobrazování dle posledního nastavení
příkazem @@SANITY.
<číslo> je číslo chybového hlášení, a najdete jej zapsané ve zprávě, např.
"Varovani (<číslo>):" nebo "Chyba (<číslo>):". Hlášení kritických chyb nelze
vypnout, pouze zapnout.
Upozornění: Chybové hlášení odpovídající určitému číslu se může v různých
            verzích programu NFORenum měnit.
