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í, dohadování se s Medwynem (to je obcas horší než něco naprogramovat )
• Medwyn_cz , Medwyn_cz - nápad, specifikace, kibicování. 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. 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.

Voláním knihovních funkcí (viz níže) dojde k náhradě proměnných ve tvaru %JMENO% přišlusnou 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. 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

Náhrada listingu je posunuta až na koncec zpracování proto, aby se co nejméně pracovalo s dlouhými texty a tím se zvýšila rychlost. Text listingu již není třeba dál zpracovávat, takže vlastně ani není důvod k tomu, aby se to dělalo dříve. Jediné, co by snad mohlo být potřeba udělat, je nahradit nějaký konstatntní text v listingu jiným textem a to lze realizovat funkcí REPLACEFULL.

Použití knihovny spočívá ve volání nekteré 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 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:

Použití neveřejných funkcí může vést k nečekaným výsledkům - až ke kolapsu, protože tyto funkce předpokládají nejakou inicializaci, sekvenci volání a podobně, což je zajištěno jen použitím veřejných funkcí. Důrazně volání neveřejných funkcí nedoporučuji.

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 script. Pokud se opravdu ukáže potřeba náhrady neobsluhované proměnné, lze k tomu účelu využít uživatelské funkce.

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 finalní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ězy 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 parametem 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 stringů 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í implementovaná.

Zejména při vnořování funkcí a jejich rekurzi je velmi důležité dát pozor na použití uvozovek. Každý textový řetěz vstupující do funkce jako parametr musí být uzavřen v uvozovkách. Pokud není, bude chápán jako číslo, a to může způsobit v nejlepším případě nečekaný výsledek, v horším případě neprovedení náhrady nebo možná i kolaps. Vnořování funcí do parametrů jiných funkcí je možné, ale přehlednost parametrů s každým vnořením dramaticky klesá. Je důležité si uvedomit, že funkce se vyhodnocují od poslední funkce a podle toho také kontrolovat uvozovky u textových parametrů. Je-li parametrem výsledek vnořené funkce, musí být celá funkce uzavřena v uvozovkách.

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

Vidíte, že na první a zřejmě ani na druhý pohled není zcela patrné, k čemu se které uvozovka vztahuje.

Uživatelské funkce slouží k tomu, aby si uživatel 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.

Oproti přímé obsluze voláním vlastní funkce uvnitř svého scriptu 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 scriptu a jeho snadnější údržba.

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

Pokud uživatelská funkce nahrazuje nějaký text v šabloně, před vlastní náhradou by na text měla použít funkci VarSubsEncode, která převede nebezpečné znaky tak, aby nebránily následnému správnému zpracování. Ale pozor, tato funkce nesmí být použita na celou šablonu, protože nahrazuje mj. i uvozovky, takže následující zpracování by správně nerozeznalo parametry funkcí jako %IF(..)% a další. Pokud bude uživatelská funkce volaná až po náhradách knihovnou, není třeba funkci VarSubstEncode volat.

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:TStrins;bBefore:boolean):boolean;
function VarSubstAddFunctiondReplaceWpt(fce:VarSubst_TypeReplaceFuncWpt;aText:TStrins;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 registrovana 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 stadnardní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 scriptu 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 scriptu.

K testování š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. 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.

Formulář umožňuje měnit text šablony a změněnou šablonu uložit do souboru.

Jestliže mají být aplikovány i uživatelské funkce, je třeba je registrovat před voláním funkce pro robrazení formuláře.

Součástí instalace knihovny je i jednoduchý script, který pouze zavolá knihovní funkci pro zobrazení formuláře. Běžný uživatel tak má možnost upravit si šablonu dodávanou jako součást jiného scriptu svým potřebám. 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.

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 např. zvětšit pole s popisem vkládaného vzoru proměnné tak, aby byl vidět celý.)

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 je automaticky upraven HTML soubor, s kterým byl spuštěn prohlížeč, a pak stačí v prohlížeči jen aktualizovat zobrazený soubor.

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;

Výhodou unit je bezproblémová práce s formulářem.

Musíme odlišit použití knihovny běžným uživatelem a programátorem. Běžný uživatel knihovnu využívá zprostředkovaně a jediné, co může potřebovat, je úprava šablony. K tomuto účelu slouží makra dodávaná s makry, které knihovnu využívají. Takové makro není součástí instalace knihovny a to zejména z toho důvodu, že dost dobře není možné jím registrovat uživatelské funkce, které jsou tvůrcům knihovny neznámé. Bez registrace funkcí by činnost knihovny nebyla úplná, proto je rozumné to nechat na autorech scriptů.

Programátor má úlohu obtížnější. Musí, kromě činností běžných pro exportní scripty, zajistit následující činnosti:

1. začlenit knihovnu do svého scriptu (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 exportního scriptu volat knihovní funkce pro aplikaci náhrad na šablonu nebo šablony
5. měl by vytvořit makro, které uživateli umožní upravit a otestovat šablonu

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

//uses VarSubsUnit;     //pouziti knihovny jako unit - zatim nefunguje pro problem s CRLF
{$I VarSubst.lib.pas}   //vlozeni knihovniho souboru pro preklad soucasne se scriptem
 
var sTemplateGeo:string;
...
function MyReplace(input:string): string;
begin
  ...
  Result:=ReplaceString(input,'%MY_TEXT%',VarSubstEncode('nahrazujici text'));
  ...
end;
...
procedure PluginStart;
begin
  ...  
  //registrace funkce
  if not VarSubstAddFunctionGeo(@MyReplace,true) then
    ShowMessage('Chyba registrace uzivatelske funkce'); 
  //nacteni sablony
  sTemplate:=FileToString(sPathFile);
  ... 
end; 
...
procedure PluginWork;
var iErr:Integer;
begin
  ... 
  //volani knihovni funkce pro nahradu promennych
  if not VarSubstGeo(gc,sTemplate,VARSUBST_ANSI,sOutput) then iErr:=iErr+1;
  ... 
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í.

Zásadním problémem je použití uvozovek. Uvozovky omezují textové parametry, ale uvnitř těchto parametrů mohou být další proměnné či funkce, které opět mohou obsahovat v parametrech textové řetězy ohraničené uvozovkami, … Po nahrazení sice vždy uvozovky zmizí, ale pro identifikaci funkcí a jejich parametrů jsou velmi důležité. Je proto třeba jim věnovat zvýšenou pozornost.

Je důležité konstruovat šablonu s ohledem na pořadí nahrazování proměnných a vyhodnocování funkcí. Pokud bude šablona sestaveny chybně, nedojde ke správnému vyhodnocení a ve výsledku zůstanou vidět podivné konstrukce.

Čas - ano, zpracování pomocí knihovny je nepochybně pomalejší než jednoúčelově na míru ušitý script. Ovsem produktivita programátorských prací dle našeho mínění minimálně vyváží časovou ztrátu způsobenou pomalejším zpracováním exportu. Příkladem budiž export POI Garmin. Dříve napsaný speciální script zpracovával mých asi 24000 keší + 5000 waymarků přibližně 12 minut. Předěláním exportu na použití této knihovny se sice zpracování prodloužilo na cca 14 minut, ale kterýkoli uživatel si snadnou úpravou šablony může export upravit sobě na míru. Z uživatelského hlediska použití knihovny přináší větší hodnotu než je ztráta způsobená delším zpracováním. (Pro přesnost dodám, že těch 12 minut je údaj po zrychlovací kúře, kterou script prodělal. Verze, která byla rozšířena mezi uživateli, tutéž dávku zpracovávala cca 25 minut, takže i s použitím šablony je to vlastně časová úspora. Všechno se dá zdůvodnit.)

• Úvodní verze