Knihovna zjednodušuje sestavování textů obsahujících informace o bodu uloženém v databázi GeoGetu. Zajišťuje náhradu definovaných proměnných ve vstupním textu (jakési šabloně) konkrétními textovými hodnotami. Knihovna umí využívat i podmíněné nahrazování typu Pokud toto platí, pak tam dej TEXT_A, když to neplatí, dej tam TEXT_B. Největší uplatnění najde knihovna zřejmě při tvorbě exportních maker.

• gord , Gord - specifikace, programování, dokumentace, dohadování se s Medwynem (to je občas horší než programování )
• Medwyn_cz , Medwyn_cz - nápad, specifikace, kibicování, dokumentace. Na konci vývoje si i trochu ušpinil ruce od Pascalu.

Peníze na PayPal by přišly pouze Medwynovi, a to není fér. Oba autoři na knihovně tvrdě makali. Raději nám napište email a domluvíme se na jiném způsobu příspěvku, třeba převodu na účet.

Diskuze o tomto skriptu se nachází na stránkách Geocaching.cz.

Tato část textu je určena především pro uživatele GeoGetu. Respektive pro uživatele těch skriptů GeoGetu, které využívají funkcí knihovny VarSubst. Odstavce jsou však povinnou četbou i pro programátory skriptů.

Knihovna je odpovědí na poptávku po úžasně konfigurovatelných exportech. Každý by chtěl ve své navigaci vidět něco jiného, jinak seřazeného, jinak nadepsaného, jinak obarveného… (a to nejčastěji v závislosti na lunární fázi měsíce a velikosti bot autora keše ). Programátoři exportních skriptů však nemohou tyto požadavky vyslyšet a vyhovět každému. Posláním knihovny je umožnit maximální možnou konfiguraci s minimálním množstvím práce na obou frontách. Každý uživatel si nakonfiguruje výstup sám. A autor exportního skriptů má (relativní) klid.

Knihovna dokáže prohledat text, najít v něm nějaké vzory a přetransformovat je do vzorů jiných. V podstatě jde o nahrazování proměnných (Variables Substitution, VarSubst).

Vysvětlíme si to raději na příkladu.

Chtěli bychom do popisu bodu v navigaci generovat text “Bod typu Traditional Cache od autora Novoročník založen dne 1.1.2001”.

Knihovně tedy předáme přibližně takto formátovaný text, říkejme mu šablona:

  Bod typu <b>%TYPE%</b> od autora <b>%AUTHOR%</b> založen dne <b>%HIDDEN%</b>

Kromě textu je knihovně předán i GC kód keše, ale o to se uživatel většinou nemusí starat.

Knihovna vrátí text upravený do tvaru:

  Bod typu <b>Traditional Cache</b> od autora <b>Novoročník</b> založen dne <b>1.1.2001</b>

Knihovna zná nějaká klíčová slova (viz dále, přehled možných vzorů), na která vnitřní logika reaguje a zpracuje je. Zpracování probíhá pomocí vyhledávání vzorů, jejich interpretace a nahrazování. Taková sranda něco stojí, v našem případě je to čas. A možná trocha oxidu uhličitého, který produkují elektrárny při výrobě elektřiny.

Uživatelé nepracují přímo s knihovnou, ale spíše se skriptem, který knihovnu využívá.

Skripty většinou používají nějaké šablony uložené v textových souborech. Šablony obsahují příkazy pro knihovnu VarSubst. Při spuštění skriptu je šablona načtena a pro každý skriptem zpracovávaný bod jsou provedeny náhrady vzorů z šablony za skutečné hodnoty. Takto zpracované výstupy jsou pak skriptem dále zpracovány (třeba zapsány do GPX souboru určeného pro navigaci).

Pokud si chce uživatel skriptu změnit formát výstupu, stačí mu najít tu správnou šablonu a upravit si ji. Nic mu nebrání takové úpravy dělat v jeho oblíbeném textovém editoru, ale protože se jedná o častý úkon, připravili jsme pro něj grafický editor šablon, který takové úpravy hodně zjednodušuje.

V každém skriptu může být editor vyvoláván různými způsoby. Nejjednodušší cestou je přidat volbu na otevření editoru do menu pluginy přímo v GeoGetu. Skript POI Garmin tak například publikuje do menu pluginy položku POI Garmin - editor šablon.

Ukázka editoru

V levé části okna je vidět šablona, v pravé potom výstup po jejím zpracování. Šablonu lze postupně upravovat, prohlížet si výstup na různých bodech a následně si ji, pokud se úpravy povedly, uložit.

Náhled ovšem nezobrazuje přesně výsledek tak, jak je vidět na cílovém zařízení, ale jen text, který je cílovému zařízení předán. Uživatel se tedy musí alespoň v základech orientovat v příslušném formátu dat.

Výsledek práce šablony je možné jediným tlačítkem zobrazit ve webovém prohlížeči. Při každé další aplikaci knihovny na upravenou šablonu (tlačítko Obnovit) je automaticky upraven HTML soubor, se kterým byl spuštěn prohlížeč, a pak stačí v prohlížeči jen znovu načíst zobrazený soubor (tlačítko Obnovit, F5).

ID definuje ID bodu (keše nebo WPT), jehož hodnoty budou použity pro vyhodnocení šablony. To, zda se jedná o ID bodu nebo WPT, knihovna rozlišuje sama podle toho, zda se jí příslušné ID podaří najít mezi body - pokud ne, hledá ID mezi doplňkovými body.

Při úpravách šablon je možné využít seznamu, vybrat z něj požadovanou proměnnou nebo funkci a její kostru vložit do šablony. (Velikost formuláře lze plynule měnit a tím lze zvětšit i pole s popisem vkládaného vzoru proměnné tak, aby byl vidět celý.)

Následuje výčet možných vzorů, které mohou šablony obsahovat a které dokáže knihovna zpracovat a nahradit.

Všechny řádky začínající znakem # jsou považovány za komentář a jsou ignorovány. Ve výstupu nebudou zahrnuty.

Jak je vidět z předchozího výčtu, nahrazované proměnné odpovídají položkám, které databáze GeoGetu uchovává k jednotlivým bodům. To je důležité si uvědomit zejména při tvorbě šablony. Ne všechny položky jsou k dispozici pro všechny typy bodů (keš versus doplňující waypoint). Nicméně při náhradě pro WP knihovna vyhledá i mateřský bod (keš) a pokud je to třeba, použije příslušné hodnoty z jeho definice. Pokud se však budete snažit použít proměnnou %WPT*% na mateřském bodě (keši), logicky k náhradě nedojde, jelikož pro keš není taková proměnná definována.

Existují ještě dvě vnitřní proměnné knihovny. Obě proměnné jsou na konci činnosti knihovny nahrazeny příslušným znakem.

&CRLF& bude nahrazeno znaky pro odřádkování. Znaky nového řádku používá knihovna vnitřně. Proto všechny tyto znaky v šabloně jsou na začátku práce knihovny nahrazeny tímto textem a na konci zase vráceny zpět. Je možné, že uživatel bude potřebovat někam vložit zalomení řádku a k tomu může využít právě této konstanty.

&uvozovky& bude nahrazeno uvozovkami. Jak je zmíněno na více místech tohoto návodu, uvozovky slouží jako omezovač parametrů ve funkcích. Proto by uvozovky mimo tento účel být neměly. Pokud má výsledek obsahovat uvozovky, je třeba je v šabloně nahradit právě tímto textem.

Knihovna nahrazuje jen ty proměnné, jejichž použití může mít v šablonách nějaký přínos. Zdaleka tedy nejsou k dispozici všechny globální proměnné GeoGetu, které může použít skript. Pokud se opravdu ukáže potřeba náhrady neobsluhované proměnné, lze k tomu účelu využít uživatelské funkce. Anebo nás přesvědčit, abychom náhradu proměnné přidali přímo do knihovny.

Logické proměnné vracejí text true nebo false jako string. Tento string je možné testovat v podmíněném nahrazování.

Obsluha funkcí je aplikovaná až po všech prostých náhradách, může tedy využívat jejich výsledku. Je možné například testovat existenci finálních souřadnic a v závislosti na tom souřadnice vypsat nebo místo nich napsat nějaký jiný text.

Všechny parametry použité ve funkcích jsou textové řetězce a je nutné je uzavřít do uvozovek. Oddělovačem parametrů je oproti běžným zvyklostem středník. Obecný tvar volání funkcí je

%FUNKCE("par1"; "par2";...)%

Je-li parametrem operátor porovnání, není uzavřen v uvozovkách a ani není oddělen středníky od ostatních parametrů. Mezery (obecně bílé znaky) mezi parametry jsou nevýznamné.

Knihovna poskytuje následující funkce:

%TAG("kategorie")%

• náhrada hodnotami TAGu zadané kategorie

%IFTAG("kategorie"; "hodnota"; "text při existenci"; "text při neexistenci")%

• náhrada textem podle toho, zda bod má nastavený TAG příslušné kategorie a hodnoty nebo nemá

%IF("str1" op "str2"; "pravdivý text"; "nepravdivý text")%

• náhrada textem podle platnosti zadané podmínky. Funkce test vyhodnocuje porovnáním řetězců s ohledem na velikost písmen. Jako operátor op mohou být použity =, <>, >=, ⇐.

%ROT13("str")%

• zakóduje vstupní string způsobem obvyklým při kódování hintu

%REVERSE("str")%

• obrátí pořadí znaků ve stringu

%REPLACE("str";"vzor";"náhrada")%

• každý výskyt vzor ve vstupním textu str nahradí textem náhrada. Funkce je vyhodnocována po aplikaci standardních náhrad (viz tabulky pořadí zpracování na začátku)

%REPLACEFULL("str";"vzor";"náhrada")%

• funkce je identická s předchozí funkcí, ale volá se až úplně na konci zpracování jako poslední funkce před návratem

Funkce REPLACE a IF mohou být do sebe vnořeny (funkce může obsahovat samu sebe, tzv. rekurze), vyhodnocují se vždy od poslední k první. U ostatních funkcí postrádá rekurze smyslu, proto není implementována.

%IF("str1"<>"str2"; "%IF(int1=int2;"platí vnější i vnitřní test"; "platí vnější, neplatí vnitřní test")%"; "neplatí vnější test")%

Kromě základních vzorů a funkcí, o kterých píšeme výše, může být funkcionalita knihovny rozšířena i o další vzory. Knihovna totiž poskytuje programátorovi možnost přidat ke standardním vzorům i své vzory vlastní.

Jelikož každý skript si může vložit vzory různé, není možno zde vypsat přesný seznam dostupných funkcí. Ten by měl být k dispozici na stránkách skriptů, nikoliv zde.

Přesto je však možno zjistit, o jaké vzory byla knihovna rozšířena. V grafickém editoru šablon, ve vysouvacím seznamu vzorů, jsou na konci zobrazeny i rozšiřující vzory přidané programátorem volajícího skriptu.

Takto může vypadat relativně pokročilá šablona, která je použitelná se skriptem POI Garmin. Kromě standardních knihovních funkcí využívá i vlastní vzory.

Listing bodu:

point.description.poigarmin.varsubst.template.txt

# GeoGet, http://www.geoget.cz
# Šablona pro knihovnu VarSubst, http://www.geoget.cz/doku.php/user:skript:varsubst
# Součást exportu POI Garmin, http://www.geoget.cz/doku.php/user:skript:poigarmin
#
# Autor: medwyn_cz, http://www.geocaching.com/profile/?u=medwyn_cz
#
# Šablonu můžete libovolně upravovat. Při aktualizacích exportu na vyšší verze jsou přepisovány
# šablony uložené v adresáři "templates_bundled". Žádná šablona z adresáře "templates" NEBUDE
# aktualizací ovlivněna. Nemusíte se tedy bát, že aktualizací přijdete o své změny.
#
########## Varování o důležitých skutečnostech - začátek listingu
Bod typu <b>%TYPE%</b> od autora <b>%AUTHOR%</b> založen dne <b>%HIDDEN%</b><hr>
%IF("%ISOWNER%"="true";"<font color=BLUE><b>Jste vlastník tohoto bodu!</b></font><br><br>";"")%
%IF("%ISFOUND%"="true";"<font color=#038914><b>Bod jste již našel (%FOUND%).</b></font><br><br>";"")%
%IF("%ISARCHIVED%"="true";"<font color=RED><b>Bod je archivovaný.</b></font><br><br>";"%IF("%ISDISABLED%"="true";"<font color=RED><b>Bod je dočasně nepřístupný.</b></font><br><br>";"")%")%
%IF("%LOGSTATHASISSUES%"="true";"<font color=RED><b>Od posledního nálezu bylo na bodu několik podezřelých logů:</b></font> (%LOGSTAT%).<br><br>";"")%
%IF("%CONTAINSHIGHLIGHTWORD%"="true";"<font color=RED><b>V listingu byla zvýrazněna definovaná klíčová slova!</b></font><br><br>";"")%
<b>ID:</b> %ID%<br>
### Pro keše vypíšeme více informací
%IF("%FAMILY%"="GC";"<b>Obtížnost:</b> %DIFFICULTY%<br><b>Terén:</b> %TERRAIN%<br><b>Velikost:</b> %SIZE%<br>";"")%
### Výpis obsahu tagů, pokud existují
%IFTAG("favorites";"";"<b>Oblíbená:</b> %TAG("favorites")%x<br>";"")%
%IFTAG("Elevation";"";"<b>Nadmořská výška:</b> %TAG("Elevation")% m.n.m.<br>";"")%
%IFTAG("Hodnoceni";"";"<b>Hodnocení:</b> %TAG("Hodnoceni")% (%TAG("Hodnoceni-Pocet")%)<br>";"")%
%IFTAG("attribute";"";"<b>Atributy:</b> %TAG("attribute")%<br>";"")%
%IFTAG("Bookmark";"";"<b>Bookmarky:</b> %TAG("Bookmark")%<br>";"")%
%IFTAG("BestOf";"";"<b>BestOf:</b> %TAG("BestOf")%<br>";"")%
%IFTAG("CWG";"";"<b>CWG:</b> %TAG("CWG")%<br>";"")%
%IFTAG("PocketQuery";"";"<b>PocketQuery:</b> %TAG("PocketQuery")%<br>";"")%
%IFTAG("FTF";"";"<b>FTF:</b> %TAG("FTF")%<br>";"")%
%IFTAG("import";"";"<b>Importováno z:</b> %TAG("import")%<br>";"")%
<b>Aktualizováno:</b> %UPDATED%<br>
%IF("%FAMILY%"="GC";"<b>Naposledy nalezena:</b> %LASTFOUND%";"")%
### Poznámka z GeoGetu.
%IF("%COMMENT%"<>"";"<br><b>Poznámka:</b><br>%REPLACE("%COMMENT%";"&CRLF&";"<br>")%";"")%
%IF("%HINT%"<>"";"<br><b>Hint:</b> %REVERSE("%REPLACE("%HINT%";"&CRLF&";"<br>")%")%";"")%
########## Listing keše
#### Pro WM předřadíme Visit Instructions
%IF("%FAMILY%"="WM";"<hr><b>Podmínky logu:</b> %WMVISITINSTRUCTIONS%";"")%
#### A nyni samotný listing
%IF("%HAVELISTING%"="true";"<hr>%SHORTLISTING%<br>%LONGLISTING%";"")%
########## Seznam waypointů
%IF("%HAVEWAYPOINT%"="true";"<hr>%WAYPOINTS%";"")%
########## Poslední logy na keši
%IF("%HAVELOG%"="true";"<hr>%LOGS%";"")%

Jméno bodu:

point.name.poigarmin.varsubst.template.txt

# GeoGet, http://www.geoget.cz
# Šablona pro knihovnu VarSubst, http://www.geoget.cz/doku.php/user:skript:varsubst
# Součást exportu POI Garmin, http://www.geoget.cz/doku.php/user:skript:poigarmin
#
# Autor: medwyn_cz, http://www.geocaching.com/profile/?u=medwyn_cz
#
# Šablonu můžete libovolně upravovat. Při aktualizacích exportu na vyšší verze jsou přepisovány
# šablony uložené v adresáři "templates_bundled". Žádná šablona z adresáře "templates" NEBUDE
# aktualizací ovlivněna. Nemusíte se tedy bát, že aktualizací přijdete o své změny.
#
#
%REPLACEFULL("%IF("%FAMILY%"="GC";"%TYPEID%%SIZEID%%DIFFID%%TERRID% ";"")%%IF("%ISOWNER%"="true";"O";"")%%IF("%ISFOUND%" = "true";"F";"")%%IF("%ISARCHIVED%" = "true";"A";"%IF("%ISDISABLED%" = "true";"D";"")%")% %NAME%";"  ";" ")%
#
# Celé jméno je obaleno ve funkci REPLACEFULL. Jejím úkolem je odstranit dvojité mezery,
# které by mohly ve jménu vzniknout

Voláním knihovních funkcí (viz níže) dojde k náhradě proměnných ve tvaru %JMENO% příslušnou textovou hodnotou. Proměnné jsou vyhodnocovány podle hodnot v instanci třídy TGeo (informace o bodu - keši) nebo TWpt (informace o doplňkovém bodu - final, parkoviště, …) a podle globálních proměnných GeoGetu (např. GEGOGET_DATADIR má proměnnou %GGDATADIR%).

Všechny řádky začínající znakem # jsou považovány za komentář a ignorovány.

Všechny vstupní texty (šablona, databázové hodnoty) jsou v kódování UTF-8, výstup je volitelně v UTF-8 nebo Win-1250. Případné zaregistrované uživatelské funkce musí mít výstup kódován v UTF-8.

Knihovna zpracovává vstupní text následujícím způsobem:

1. volá všechny uživatelské funkce, které byly registrované s příznakem bBefore
2. nahradí proměnné (s výjimkou proměnných pro listing)
3. nahradí logické proměnné
4. provede funkce REPLACE
5. nahradí TAGy (funkce TAG, IFTAG)
6. provede funkce ROT13 a REVERSE
7. zpracuje podmíněné nahrazení funkcí IF
8. volá všechny uživatelské funkce, které byly registrované bez příznaku bBefore
9. náhrada proměnných pro listing (LISTING, LONGLISTING, SHORTLISTING)
10. provede funkci REPLACEFULL

Použití knihovny spočívá ve volání některé z knihovních funkcí. Těch obsahuje knihovna celou řadu, ale jen některé z nich jsou určené k volání mimo knihovnu (veřejné funkce). Seznam veřejných funkcí:

function VarSubstGeo(geo:TGeo; sTemplate:string; bAnsi:boolean; var sOutput:string): boolean;

• Nahrazuje proměnné hodnotami z hlavního bodu (keš, waymark)

function VarSubstWpt(wpt:TWpt; sTemplate:string; bAnsi:boolean; var sOutput:string): boolean;

• Nahrazuje proměnné hodnotami z WPT bodu (parkoviště, stage of multi=cache, …)

function VarSubstAddFunctionReplaceGeo(fce:VarSubst_TypeReplaceFunc;bBefore:boolean):boolean;

• Registruje uživatelskou funkci pro nahrazování proměnných podle TGeo.

function VarSubstAddFunctionReplaceWpt(fce:VarSubst_TypeReplaceFunc;bBefore:boolean):boolean;

• Registruje uživatelskou funkci pro nahrazování proměnných podle TWpt.

function VarSubstDelFunctionReplace(fce:VarSubst_TypeReplaceFunc):boolean;

• Ruší registraci uživatelské funkce

procedure VarSubstDlgTemplateFile(sCaption, ID, sPathFileTemplate, startDir:string);

• Poskytuje formulář pro testování šablony.

procedure VarSubstDlgTemplateString(sCaption, ID, sTemplate, startDir:string);

• Poskytuje formulář pro testování šablony.

function VarSubstDlgTemplateStringNoSave(caption,id,sTemplate: string) : String;

• Funkce, která zobrazí formulář na editaci a testování šablony. Návratovou hodnotou je nově upravená šablona. Ve formuláři jsou skryty ovládací prvky pro přímé ukládání do souboru.

function VarSubstEncode(str:string):string;

• Nahrazuje nebezpečné znaky, které brání správnému zpracování funkcí. Funkce najde uplatnění v uživatelských funkcích.

Ve funkcích jsou použity následující parametry:

Uživatelské funkce slouží k tomu, aby si programátor mohl definovat vlastní funkce, které budou použity při nahrazování. Může tedy definovat obsluhu vlastních proměnných, specifické zacházení s texty (např. omezení délky výstupního textu) a další pro něj užitečné funkce, které nezajišťuje knihovna.

Vlastní funkce si programátor zaregistruje u knihovny, a ta je poté bude v patřičných okamžicích volat.

Oproti přímé obsluze voláním vlastní funkce uvnitř svého skriptu mají uživatelské funkce tu výhodu, že jsou aplikovány na šablony současně s ostatními knihovními funkcemi. Přínosem by měla být lepší čitelnost kódu skriptu a jeho snadnější údržba. Rovněž takováto struktura umožňuje uživatelům skriptů používat grafický editor šablon včetně rozšíření a zjednodušuje tak práci na všech frontách.

Knihovna definuje dva typy uživatelských funkcí:

  VarSubstGeo_TypeFuncReplace=function(geo:TGeo;sTemplate:string): string;
  VarSubstWpt_TypeFuncReplace=function(wpt:TWpt;sTemplate:string): string;

Oba typy se liší jen typem bodu se vstupními daty pro aplikaci dat na šablonu. Z deklarace typu je zřejmé, že funkce musí vracet string (v kódování UTF-8), který je výsledkem její činnosti na vstupní šabloně (rovněž v kódování UTF-8). Funkce tedy aplikuje své postupy na vstupní string sTemplate a výsledek vrátí. S tímto výsledkem pak bude volaná případná další uživatelská funkce.

Uživatelská funkce většinou bude realizovat nějakou náhradu uživatelem definované textové konstanty. Nejčastěji tak budou v implementaci uživatelské funkce používány funkce k nahrazení textu textem jiným - ReplaceString, RegexReplace.

Příklad jednoduché uživatelské funkce:

{Funkce nahrazuje vzor %MYOWNLISTING% za listing zpracovaný funkcí MyOwnEditation}
function UzivatelskaFunkce(geo:TGeo;sTemplate:string): string;
begin
  Result:=sTemplate;
  if(pos('%MYOWNLISTING%',Result)>0) //testování, zda je je v šabloně obsažen vzor. VÝRAZNĚ urychluje zpracování 
    then Result:=ReplaceString(Result,'%MYOWNLISTING%',VarSubstEncode(MyOwnEditation(geo.LongDescription))); //Náhrada všech výskytů vzoru cílovou hodnotou . POZOR, jakýkoliv vkládaný text musí být v kódování UTF-8!
end;

Je velmi vhodné, aby tato textová konstanta dodržela formát %JMENO% a v případě funkce %JMENO_FUNKCE()%. Není to sice nezbytně nutné, ale udrží se tím alespoň jakási čitelnost šablony a navíc tento formát umožní v editačním formuláři vkládat tento text výběrem ze seznamu vzorů. Pokud formát dodržen nebude, konstanta a její popis sice v seznamu zobrazen bude, ale nebude možné ji do šablony vložit.

Každá uživatelská funkce, která má být použita, musí být napřed knihovnou registrována. K registraci slouží jedna z funkcí

function VarSubstAddFunctiondReplaceGeo(fce:VarSubst_TypeReplaceFuncGeo;aText:TStrings;bBefore:boolean):boolean;
function VarSubstAddFunctiondReplaceWpt(fce:VarSubst_TypeReplaceFuncWpt;aText:TStrings;bBefore:boolean):boolean;

Z názvu funkcí jasně vyplývá, že se samostatně registrují funkce obsluhující hlavní bod (keš, waymark, …) a funkce obsluhující doplňkové body (WPT). Protože struktury obsahující příslušná data jsou pro oba typy bodů odlišné, je nutné je registrovat samostatně. Chybná registrace způsobí kolaps.

Vysvětleme si druhý parametr: jedna registrovaná funkce může obsluhovat několik proměnných nebo funkcí. Protože formulář pro úpravu šablony nabízí seznam proměnných a funkcí pro snadné vložení jakéhosi vzoru, je třeba jako informaci o uživatelské funkci předat i tento vzor a popis tak, aby uživatel mohl vybrat správný řádek. Proto seznam všech funkcí nahrazovaných proměnných a jejich popis je součástí 2. parametru. Řekněme, že máme funkci, která obsluhuje proměnné %TEST1% a %TEST2%. Pak funkce bude registrována takto:

var  fUser:VarSubstGeo_TypeFuncReplace;
...
function UzivatelskaFunkce(geo:TGeo;sTemplate:string): string;
begin
  Result:=sTemplate;
  ...
end;
 
  ...
  fUser:=@UzivatelskaFunkce;
  aPopis.Add('%TEST1% - testovaci funkce');
  aPopis.Add('%TEST2%');
  VarSubstAddFunctionReplaceGeo(fUser,aPopis,false);

Třetí parametr informuje knihovnu o tom, zda registrovaná funkce má být volaná před nebo po standardních náhradách knihovními funkcemi.

V nečetných případech může být užitečné registraci funkce zrušit. K tomu slouží funkce

function VarSubstDelFunctionReplaceGeo(fce:VarSubst_TypeReplaceFunc):boolean;
function VarSubstDelFunctionReplaceWpt(fce:VarSubst_TypeReplaceFunc):boolean;

Po jejich použití již nebude knihovna příslušnou uživatelskou funkci volat a popis jí obsluhovaných konstant %JMENO% zmizí i ze seznamu nabízeném ve formuláři pro úpravu šablony.

Pokud se v průběhu práce volajícího skript nemění uživatelské funkce, není třeba rušit registrace uživatelských funkcí. K odregistraci dojde automaticky ukončením nadřízeného volajícího skriptu.

K testování a úpravě šablon poskytuje knihovna dvě procedury.

procedure VarSubstDlgTemplateFile(sCaption, ID, sPathFileTemplate, startDir:string);
procedure VarSubstDlgTemplateString(sCaption, ID, sTemplate, startDir:string);

Obě procedury zobrazí formulář, na kterém je současně zobrazena šablona i výsledek aplikace knihovních a registrovaných uživatelských funkcí na šablonu. Procedury se liší jedině vstupním parametrem, který předává buďto cestu a jméno souboru se šablonou nebo přímo šablonu.

Knihovna je připravena ve dvou verzích. Je možné prostě includovat soubor

{$include VarSubst.lib.pas}

nebo je možné knihovnu použít jako unit příkazem

uses VarSubstUnit;

na prvním řádku klientského skriptu.

Výhodou unit je bezproblémová práce s formulářem, je tedy doporučeno používat tuto cestu.

Úlohou programátora, který chce používat tuto knihovnu, je:

1. začlenit knihovnu do svého skriptu (příkazem uses nebo include)
2. vytvořit potřebnou šablonu nebo šablony
3. pokud je to nutné, vytvořit a registrovat uživatelské funkce
4. v kódu skriptu volat knihovní funkce pro aplikaci náhrad na šablonu nebo šablony
5. vytvořit skript či jinak publikovat přístup k formuláři, který uživateli umožní upravit a otestovat šablonu

Za velmi jednoduchou ukázku nechť slouží následující kód

uses VarSubstUnit;     //pouziti knihovny jako unit
//{$I VarSubst.lib.pas}   //vlozeni knihovniho souboru pro preklad soucasne se skriptem
 
var sTemplateGeo:string;
var iErr:Integer;
...
function MyReplace(input:string): string;
begin
  ...
  if(pos('%MY_TEXT%',Result)>0)
    then Result:=ReplaceString(input,'%MY_TEXT%',VarSubstEncode('nahrazujici text')); 
    //POZOR, jakykoliv vkladany text musi byt v kodovani UTF-8!
  ...
end;
...
procedure PluginStart;
begin
  ...  
  //registrace funkce
  if not VarSubstAddFunctionGeo(@MyReplace,true) then
    ShowMessage('Chyba registrace uzivatelske funkce'); 
  //nacteni sablony
  sTemplate:=FileToString(sPathFile);
  ...
  iErr := 0; 
end; 
...
procedure PluginWork;
begin
  ... 
  //volani knihovni funkce pro nahradu promennych
  if not VarSubstGeo(gc,sTemplate,VARSUBST_ANSI,sOutput) then iErr:=iErr+1;
  ... 
end;
 
procedure PluginStop;
begin
  if iErr > 0 then ShowMessage('Pri zpracovani sablon doslo k chybe'); 
end; 

Knihovna neobsahuje žádné konfigurační parametry, které by měly být uživatelsky přístupné. Obsahuje ale některé konstanty, které nastavují velikosti polí. Jejich velikost jsme zvolili jako rozumné maximum, ale může se ukázat, že pro speciální použití některá hodnota nebude dostatečná. Ve zdrojovém kódu je na začátku knihovny definice konstant a uživatel si může pro svoji potřebu tyto hodnoty upravit. Rozhodně by k tomu nemělo docházet nějak houfně - to by spíš ukazovalo na chybný algoritmus použití knihovny nebo na naši špatnou implementaci některé z funkcí. Pokud pocítíte potřebu si tyto konstanty pro své použití upravovat, raději nás kontaktujte s dotazem.

Pokud jste narazili na skript, který knihovnu používá, ale není zde uveden, kontaktujte, prosím, autory.

1.1.1.1 (2011/05/17)

• Opravena drobná chyba, která měla za následek problém při použití příkazů %COORDINATE%, %CORRECTEDCOORDINATE% a %WPTCOORDINATE%, pokud bylo jako výstupní formátování použito UTF8.