GeoGet

Complete geocaching solutions

User Tools

Site Tools


user:skript:varsubst

This is an old revision of the document!


VarSubst

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.

Autor

  • 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.
Pokud se Vám doplněk líbí, kliknutím na tlačítko Donate můžete přispět na jeho vývoj.

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.

Automatická instalace

Nainstalovat do GeoGetu
Instalaci doplňku spustíte kliknutím na tlačítko vlevo. Následně budete v prostředí GeoGetu provedeni instalačním procesem. Pro zajištění této funkce je třeba mít na počítači již nainstalovaný a spuštěný program GeoGet .
Kliknuli jste na tlačítko a nic se nestalo? Máte opravdu spuštěný GeoGet ? Je to potřeba! Nebo možná máte zastaralý webový prohlížeč. Nevadí, instalaci doplňku můžete jednoduše vyvolat i prostým zkopírováním (označit text → klik pravým tlačítkem → kopírovat) následujícího odkazu do schránky: https://www.geoget.cz/doku.php/user:skript:varsubst?download

Diskuze

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

Uživatelská dokumentace

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ů.

Proč knihovna existuje

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.

Co knihovna dělá

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>

Jak to knihovna dělá

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.

Jak se s knihovnou pracuje

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
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ý.)

:!: Samozřejmě chápeme, že práce se šablonami může být někdy dosti složitá. Pokud nevíte, jak získat svůj vysněný výstup, kontaktujte autora skriptu, nebo rovnou autory knihovny VarSubst. Jistě Vám rádi poradí, pokud budou mít trochu času.

Přehled možných vzorů v šabloně

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

Komentář

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

Seznam nahrazovaných proměnných

%NAME%, %WPTNAME%jméno bodu
%FAMILY%typ bodu (první 2 znaky: GC, WM, …)
%ID%, %WPTID%identifikátor bodu (GC12345)
%GUID%, %WPTGUID%plný identifikátor bodu používaný v URL na geocaching.com
%AUTHOR%autor (vlastník) bodu
%TYPE%, %WPTTYPE%typ bodu (Traditional, Multi cache, Letterbox hybrid, …)
%TYPEID%, %WPTTYPEID%jeden znak identifikace typu (T=Traditional Cache, M=Multi-cache, H=Letterbox Hybrid, C=Cache In Trash Out Event, E=Event Cache, L=Locationless (Reverse) Cache, V=Virtual Cache, W=Webcam Cache, O=Other, G=Earthcache, I=Wherigo Cache, U=Unknown Cache, Y=Lost and Found Event Cache, F=Final Location, P=Parking Area, Q=Question to Answer, S=Stages of a Multicache, T=Trailhead, R=Reference Point)
%SIZE%velikost (Micro, …)
%SIZEID%jeden znak velikost (M=Micro, S=Small, R=Regular, L=Large, V=Virtual, O=Other, N=Not chosen)
%DIFFICULTY%obtížnost (1 … 5)
%DIFFID%jeden znak obtížnosti (1,A,2,B,3,C,4,D,5)
%TERRAIN%terén (1 … 5)
%TERRID%jeden znak terénu (1,A,2,B,3,C,4,D,5)
%IDTAG%zkrácená informace (včetně “půlek”) o typu, obtížnosti, terénu a velikosti (TM2B)
%HINT%text nápovědy (dekódovaný)
%HIDDEN%datum vytvoření bodu ve tvaru DD.MM.RRRR
%COORDINATE%, %WPTCOORDINATE%souřadnice bodu ve tvaru N SS°MM.mmm E SSS°MM.mmm
%CORRECTEDCOORDINATE%korigované souřadnice bodu (=souřadnice finálky) ve tvaru N SS°MM.mmm E SSS°MM.mmm
%LAT%, %WPTLAT%zeměpisná délka ve tvaru SS,dddddd
%LON%, %WPTLON%zeměpisná šířka ve tvaru SSS,dddddd
%LATCORRECTED%korigovaná zeměpisná délka (souřadnice finálky) ve tvaru SS,dddddd
%LONCORRECTED%korigovaná zeměpisná šířka (souřadnice finálky) ve tvaru SSS,dddddd
%COUNTRY%stát, v kterém bod leží (kam patří)
%STATE%kraj (kanton, …), v kterém bod leží (kam patří)
%STATUS%stav bodu (číslice 0,1,2)
%STATUSTXT%stav bodu textově (Disabled, Archived, …)
%UPDATED%, %WPTUPDATED%datum poslední aktualizace bodu v DB ve tvaru DD.MM.RRRR
%LISTING%celý listing bodu
%LONGLISTING%dlouhý popis bodu
%SHORTLISTING%krátký popis bodu
%COMMENT%, %WPTCOMMENT%text uživatelského komentáře (poznámky)
%FOUND%datum a čas nálezu ve tvaru DD.MM.RRRR HH.MM
%LASTFOUND%datum posledního nálezu ve tvaru DD.MM.RRRR (dle logů uložených v DB)
%PQCACHEID%ID bodu podle PQ
%PQOWNERID%ID vlastníka podle PQ
%ATTACHMENTDIR%adresář pro přílohy
%RTFATTACHMENTFILE%jméno připojeného RTF souboru
%WPTPREFIXID%prefix bodu
%WPTDESCRIPTION%popis bodu

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.

Seznam globálních proměnných GeoGetu

%GGDATADIR%datový adresář GeoGetu
%GGSCRIPTDIR%adresář GeoGetu, v kterém jsou očekávány skripty
%GGDBNAME%jméno databáze GeoGetu
%GGVER%verze GeoGetu
%GGOWNER%uživatel GeoGetu
%CRLF%odřádkování

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.

Seznam logických proměnných

%HAVEFINAL%true, pokud má keš finálku
%ISDISABLED%true, pokud má bod status Disabled
%ISENABLED%true, pokud má bod status Enabled
%ISARCHIVED%true, pokud má bod status Archived
%ISFOUND%true, pokud má bod nenulové datum nálezu
%ISOWNER%true, pokud bod patří uživateli Geogetu
%HAVELISTING%true, pokud má bod neprázdný popis
%HAVEATTACHMENT%true, pokud má bod nějaký přiložený soubor
%HAVERTFATTACHMENT%true, pokud má bod nějaký přiložený *.rtf soubor
%WPTISUSERWAYPOINT%true, pokud byl WPT vytvořen či upraven uživatelem
%WPTISFINAL%true, pokud se jedná o bod s finálovými souřadnicemi
%WPTISEMPTYCOORD%true, pokud souřadnice bodu jsou nulové

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

Seznam funkcí

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 retě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 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.

:!: 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í funkcí 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 uvědomit, ž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é vzory a funkce

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.

Ukázka šablon

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://geoget.ararat.cz
# Šablona pro knihovnu VarSubst, http://geoget.ararat.cz/doku.php/user:skript:varsubst
# Součást exportu POI Garmin, http://geoget.ararat.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://geoget.ararat.cz
# Šablona pro knihovnu VarSubst, http://geoget.ararat.cz/doku.php/user:skript:varsubst
# Součást exportu POI Garmin, http://geoget.ararat.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

Poznámky, známé problémy

:!: 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 sestavena 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ý skript. 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í skript zpracovával Gordový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áváme, že těch 12 minut je údaj po zrychlovací kúře, kterou skript 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.)

Programátorská dokumentace

Funkce

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

:!: Náhrada listingu je posunuta až na konec zpracování proto, aby se co nejméně pracovalo s dlouhými texty a tím se zvýšila rychlost. Text listingu již většinou 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ý konstantní text v listingu jiným textem a to lze realizovat funkcí REPLACEFULL.

Veřejné funkce knihovny

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 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:

TGeostruktura naplněná informacemi o konkrétním bodu (keši)
TWptstruktura naplněná informacemi o doplňkovém bodu
sTemplatevstupní text s šablonou obsahující nahrazované proměnné (čeština v UTF-8). Šablona obsahuje jména proměnných a funkcí, které knihovna vyhodnocuje a nahradí je vyhodnoceným textem. (Pokud má výsledný text obsahovat znak %, musí být v šabloně vypsán jako HTML entita &perc;.)
sOutputvýstupní text, v kterém jsou proměnné nahrazeny příslušnými hodnotami. Výsledné kódování češtiny je podle proměnné bAnsi v UTF-8 nebo Win-1250.
bAnsipožadavek na překódování výstupu do kódování ANSI (Win-1250). Místo hodnot true a false lze použít jednoznačné konstanty VARSUBST_ANSI a VARSUBST_UTF.
fceuživatelem definovaná funkce, která realizuje nahrazování nad rámec knihovních funkcí
bBeforepožadavek na použití uživatelské funkce před nahrazením knihovnou (napřed bude na vstupní šablonu aplikovaná uživatelem definovaná funkce, až na její výsledek bude aplikováno standardní nahrazení knihovnou)
:!: Použití neveřejných funkcí (tedy prohlédnutí zdrojového kódu knihovny a volání funkcí, které nejsou uvedeny v seznamu výše) může vést k nečekaným výsledkům - až ke kolapsu, protože tyto funkce předpokládají nějakou 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čujeme.

Uživatelské funkce

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.

Požadavky na uživatelské funkce

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.

:!: Pokud uživatelská funkce nahrazuje nějaký text v šabloně, před vlastní náhradou by na text měla použít funkci VarSubstEncode, 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.

Registrace uživatelské funkce a použ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 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 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.

Testování a úprava šablon

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.

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

Knihovna jako Include nebo Unit

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.

Ukázka použití knihovny

Ú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 VarSubsUnit;     //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;

Nastavení a konfigurace

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.

Stažení

:!: Stáhnout aktuální verzi: varsubst-1.1.1.1.gip

Seznam dostupných verzí

FilenameFilesizeLast modified
varsubst-1.1.1.1.gip19.2 KiB2011/05/17 00:00
varsubst-1.1.1.gip19.1 KiB2011/01/24 00:00
varsubst-1.1.0.gip17.3 KiB2011/01/04 00:00

Seznam změn

1.1 (2011/01/03)

  • Úvodní verze. Pracovali jsme na ní ve volných chvílích přes půl roku.

:?: Zobrazit změny ve starších verzích

Skrýt změny ve starších verzích

user/skript/varsubst.1294151782.txt.gz · Last modified: 2011/01/04 00:00 (external edit)