user:skript:varsubst
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
user:skript:varsubst [2011/01/03 14:46] – gord | user:skript:varsubst [2021/10/10 10:14] (current) – mikrom | ||
---|---|---|---|
Line 3: | Line 3: | ||
===== Autor ===== | ===== Autor ===== | ||
- | * **[[http:// | + | * **[[http:// |
- | * **[[http:// | + | * **[[http:// |
| Pokud se Vám doplněk líbí, kliknutím na tlačítko Donate můžete přispět na jeho vývoj. | ~~PAYPAL business=" | | Pokud se Vám doplněk líbí, kliknutím na tlačítko Donate můžete přispět na jeho vývoj. | ~~PAYPAL business=" | ||
- | 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, | + | 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, |
===== Automatická instalace ===== | ===== Automatická instalace ===== | ||
Line 14: | Line 14: | ||
===== Diskuze ===== | ===== Diskuze ===== | ||
- | Diskuze o tomto skriptu se nachází na stránkách [[http:// | + | Diskuze o tomto skriptu se nachází na stránkách [[http:// |
- | ===== Funkce | + | ===== Uživatelská dokumentace |
- | Voláním knihovních funkcí (viz níže) dojde k náhradě proměnných ve tvaru **%JMENO%** | + | Tato část textu je určena |
- | Všechny | + | <WRAP round important> |
+ | Protože se jedná o knihovnu, není možné ji použít samostatně. Jako každá jiná knihovna i tato slouží programátorům (v tomto případě programátorům skriptů pro GeoGet) k tomu, aby zjednodušila jejich práci. Programátor | ||
+ | </ | ||
- | 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 | + | ==== Proč knihovna existuje ==== |
+ | Knihovna je odpovědí na poptávku po //úžasně konfigurovatelných exportech// | ||
+ | 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 | ||
- | Knihovna | + | ==== Co knihovna dělá ==== |
- | - volá všechny uživatelské funkce, které byly registrované s příznakem bBefore | + | Knihovna |
- | - nahradí proměnné (s výjimkou proměnných pro listing) | + | |
- | - nahradí logické proměnné | + | |
- | - provede funkce REPLACE | + | |
- | - nahradí TAGy (funkce TAG, IFTAG) | + | |
- | - provede funkce ROT13 a REVERSE | + | |
- | - zpracuje podmíněné nahrazení funkcí IF | + | |
- | - volá všechny uživatelské funkce, které byly registrované bez příznaku bBefore | + | |
- | - náhrada | + | |
- | - 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, | + | Vysvětlíme si to raději na příkladu. |
- | ===== Veřejné funkce knihovny ===== | + | 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**" |
- | 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í: | + | |
- | < | + | Knihovně tedy předáme přibližně takto formátovaný text, říkejme mu šablona: |
+ | < | ||
+ | Bod typu < | ||
+ | </ | ||
- | * Nahrazuje proměnné hodnotami z hlavního bodu (keš, waymark) | + | Kromě textu je knihovně předán i GC kód keše, ale o to se uživatel většinou nemusí starat. |
- | <code delphi> | + | Knihovna vrátí text upravený do tvaru: |
- | | + | < |
+ | | ||
+ | </ | ||
- | <code delphi> | + | ==== Jak to knihovna dělá ==== |
- | * Registruje uživatelskou funkci pro nahrazování | + | 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, | ||
- | <code delphi> | + | ==== Jak se s knihovnou pracuje ==== |
- | * Registruje uživatelskou funkci pro nahrazování proměnných podle TWpt. | + | Uživatelé nepracují přímo s knihovnou, ale spíše se skriptem, který knihovnu využívá. |
- | <code delphi> | + | 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. |
- | * Ruší registraci uživatelské funkce | + | Takto zpracované výstupy jsou pak skriptem dále zpracovány (třeba zapsány do GPX souboru určeného pro navigaci). |
- | <code delphi> | + | 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. |
- | * Poskytuje formulář pro testování | + | |
- | <code delphi> | + | 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 [[poigarmin|POI Garmin]] tak například publikuje do menu pluginy položku **POI Garmin - editor |
- | * Poskytuje formulář pro testování | + | |
- | <code delphi> | + | |{{:user:skript: |
- | * Nahrazuje nebezpečné znaky, které brání správnému zpracování funkcí. Funkce najde uplatnění v uživatelských funkcích. | + | | **Ukázka editoru** |
- | Ve funkcích jsou použity následující parametry: | + | 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. | ||
- | <box 95% right #f8f8f8 #f8f8f8 #f8f8f8 # | + | Náhled ovšem nezobrazuje přesně výsledek tak, jak je vidět na cílovém zařízení, |
- | |TGeo|struktura naplněná informacemi o konkrétním bodu (keši)| | + | |
- | |TWpt|struktura naplněná informacemi o doplňkovém bodu| | + | 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) |
- | |sTemplate|vstupní 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 najradi | + | |
- | |sOutput|výstupní text, v kterém jsou proměnné nahrazeny | + | **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. |
- | |bAnsi|požadavek | + | |
- | |fce|uživatelem definovaná funkce, která realizuje nahrazování nad rámec knihovních funkcí| | + | 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. |
- | |bBefore|požadavek na použití uživatelské funkce před nahrazením knihovnou | + | |
- | </box> | + | <WRAP round info> |
+ | 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. | ||
+ | </WRAP> | ||
- | <box round 95% # | + | ==== Přehled možných vzorů v šabloně ==== |
- | :!: 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, | + | Následuje výčet možných vzorů, které mohou šablony obsahovat |
- | </ | + | |
- | ===== Seznam nahrazovaných proměnných ===== | + | === 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 === |
+ | <WRAP round box> | ||
|%NAME%, %WPTNAME%|jméno bodu| | |%NAME%, %WPTNAME%|jméno bodu| | ||
|%FAMILY%|typ bodu (první 2 znaky: GC, WM, ...)| | |%FAMILY%|typ bodu (první 2 znaky: GC, WM, ...)| | ||
|%ID%, %WPTID%|identifikátor bodu (GC12345)| | |%ID%, %WPTID%|identifikátor bodu (GC12345)| | ||
- | |%GUID%, %WPTGUID%|plný | + | |%GUID%, %WPTGUID%|plný |
|%AUTHOR%|autor (vlastník) bodu| | |%AUTHOR%|autor (vlastník) bodu| | ||
|%TYPE%, %WPTTYPE%|typ bodu (Traditional, | |%TYPE%, %WPTTYPE%|typ bodu (Traditional, | ||
- | |%TYPEID%, %WPTTYPEID%|jeden znak identifikace typu (T=traditional, M=multi, H=letterbox hybrid, C=CITO, E=event, L=locationless, V=virtual, W=webcam, O=Other, G=Earth, I=Wherigo, U=mystery/Unknown, Y=Lost and Found Event Cache, F=Final, P=Parking, Q=Question | + | |%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 |
|%SIZE%|velikost (Micro, ...)| | |%SIZE%|velikost (Micro, ...)| | ||
- | |%SIZEID%|jeden znak velikost (M=mikro, S=small, R=regular, L=large, V=virtual, O=jiná, N=neurčeno)| | + | |%SIZEID%|jeden znak velikost (M=Micro, S=Small, R=Regular, L=Large, V=Virtual, O=Other, N=Not chosen)| |
|%DIFFICULTY%|obtížnost (1 ... 5)| | |%DIFFICULTY%|obtížnost (1 ... 5)| | ||
|%DIFFID%|jeden znak obtížnosti (1, | |%DIFFID%|jeden znak obtížnosti (1, | ||
Line 101: | Line 104: | ||
|%HIDDEN%|datum vytvoření bodu ve tvaru DD.MM.RRRR| | |%HIDDEN%|datum vytvoření bodu ve tvaru DD.MM.RRRR| | ||
|%COORDINATE%, | |%COORDINATE%, | ||
- | |%CORRECTEDCOORDINATE%|korigované souřadnice bodu (=souradnice | + | |%CORRECTEDCOORDINATE%|korigované souřadnice bodu (=souřadnice |
|%LAT%, %WPTLAT%|zeměpisná délka ve tvaru SS,dddddd| | |%LAT%, %WPTLAT%|zeměpisná délka ve tvaru SS,dddddd| | ||
|%LON%, %WPTLON%|zeměpisná šířka ve tvaru SSS,dddddd| | |%LON%, %WPTLON%|zeměpisná šířka ve tvaru SSS,dddddd| | ||
Line 123: | Line 126: | ||
|%WPTPREFIXID%|prefix bodu| | |%WPTPREFIXID%|prefix bodu| | ||
|%WPTDESCRIPTION%|popis bodu| | |%WPTDESCRIPTION%|popis bodu| | ||
- | </box> | + | </WRAP> |
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. | 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. | ||
Line 133: | Line 136: | ||
**& | **& | ||
- | ===== Seznam globálních proměnných GeoGetu | + | === Seznam globálních proměnných GeoGetu === |
- | < | + | <WRAP round box> |
|%GGDATADIR%|datový adresář GeoGetu| | |%GGDATADIR%|datový adresář GeoGetu| | ||
- | |%GGSCRIPTDIR%|adresář GeoGetu, v kterém jsou očekávány | + | |%GGSCRIPTDIR%|adresář GeoGetu, v kterém jsou očekávány |
|%GGDBNAME%|jméno databáze GeoGetu| | |%GGDBNAME%|jméno databáze GeoGetu| | ||
|%GGVER%|verze GeoGetu| | |%GGVER%|verze GeoGetu| | ||
|%GGOWNER%|uživatel GeoGetu| | |%GGOWNER%|uživatel GeoGetu| | ||
|%CRLF%|odřádkování| | |%CRLF%|odřádkování| | ||
- | </box> | + | </WRAP> |
- | 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 | + | 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 |
- | ===== Seznam logických proměnných | + | === Seznam logických proměnných === |
- | < | + | <WRAP round box> |
|%HAVEFINAL%|**true**, | |%HAVEFINAL%|**true**, | ||
|%ISDISABLED%|**true**, | |%ISDISABLED%|**true**, | ||
Line 155: | Line 158: | ||
|%HAVELISTING%|**true**, | |%HAVELISTING%|**true**, | ||
|%HAVEATTACHMENT%|**true**, | |%HAVEATTACHMENT%|**true**, | ||
- | |%HAVERTFATTACHMENT%|**teue**, pokud má bod nějaký přiložený *.rtf soubor| | + | |%HAVERTFATTACHMENT%|**true**, pokud má bod nějaký přiložený *.rtf soubor| |
|%WPTISUSERWAYPOINT%|**true**, | |%WPTISUSERWAYPOINT%|**true**, | ||
|%WPTISFINAL%|**true**, | |%WPTISFINAL%|**true**, | ||
- | |%WPTISEMPTYCOORD%|**true**, | + | |%WPTISEMPTYCOORD%|**true**, |
- | </box> | + | </WRAP> |
Logické proměnné vracejí text **true** nebo **false** jako string. Tento string je možné testovat v podmíněném nahrazování. | 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í | + | === Seznam funkcí === |
- | Obsluha funkcí je aplikovaná až po všech prostých náhradách, | + | Obsluha funkcí je aplikovaná až po všech prostých náhradách, |
- | Všechny parametry použité ve funkcích jsou textové | + | Všechny parametry použité ve funkcích jsou textové |
< | < | ||
Line 172: | Line 175: | ||
</ | </ | ||
- | Je-li parametem | + | Je-li parametrem |
Knihovna poskytuje následující funkce: | Knihovna poskytuje následující funkce: | ||
Line 182: | Line 185: | ||
* náhrada textem podle toho, zda bod má nastavený TAG příslušné kategorie a hodnoty nebo nemá | * náhrada textem podle toho, zda bod má nastavený TAG příslušné kategorie a hodnoty nebo nemá | ||
- | < | + | < |
- | | + | * náhrada textem podle platnosti zadané podmínky. Funkce test vyhodnocuje porovnáním |
- | </ | + | |
- | * náhrada textem podle platnosti zadané podmínky. Funkce test vyhodnocuje porovnáním | + | |
< | < | ||
Line 193: | Line 194: | ||
* obrátí pořadí znaků ve stringu | * obrátí pořadí znaků ve stringu | ||
- | < | + | < |
* každý výskyt //vzor// ve vstupním textu //str// nahradí textem // | * každý výskyt //vzor// ve vstupním textu //str// nahradí textem // | ||
- | < | + | < |
* funkce je identická s předchozí funkcí, ale volá se až úplně na konci zpracování jako [[user: | * funkce je identická s předchozí funkcí, ale volá se až úplně na konci zpracování jako [[user: | ||
- | 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á. | + | 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. |
- | <box round 100% #DEE7EC> | + | <WRAP round important> |
- | :!: 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í | + | 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í |
- | < | + | < |
- | %IF(" | + | |
+ | 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 [[poigarmin|POI Garmin]]. Kromě standardních knihovních funkcí využívá i vlastní vzory. | ||
+ | |||
+ | **Listing bodu:** | ||
+ | <code none point.description.poigarmin.varsubst.template.txt> | ||
+ | # GeoGet, http:// | ||
+ | # Šablona pro knihovnu VarSubst, http:// | ||
+ | # Součást exportu POI Garmin, http:// | ||
+ | # | ||
+ | # Autor: medwyn_cz, http:// | ||
+ | # | ||
+ | # Šablonu můžete libovolně upravovat. Při aktualizacích exportu na vyšší verze jsou přepisovány | ||
+ | # šablony uložené v adresáři " | ||
+ | # 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 < | ||
+ | %IF(" | ||
+ | %IF(" | ||
+ | %IF(" | ||
+ | %IF(" | ||
+ | %IF(" | ||
+ | < | ||
+ | ### Pro keše vypíšeme více informací | ||
+ | %IF(" | ||
+ | ### Výpis obsahu tagů, pokud existují | ||
+ | %IFTAG(" | ||
+ | %IFTAG(" | ||
+ | %IFTAG(" | ||
+ | %IFTAG(" | ||
+ | %IFTAG(" | ||
+ | %IFTAG(" | ||
+ | %IFTAG(" | ||
+ | %IFTAG(" | ||
+ | %IFTAG(" | ||
+ | %IFTAG(" | ||
+ | < | ||
+ | %IF(" | ||
+ | ### Poznámka z GeoGetu. | ||
+ | %IF(" | ||
+ | %IF(" | ||
+ | ########## Listing keše | ||
+ | #### Pro WM předřadíme Visit Instructions | ||
+ | %IF(" | ||
+ | #### A nyni samotný listing | ||
+ | %IF(" | ||
+ | ########## Seznam waypointů | ||
+ | %IF(" | ||
+ | ########## Poslední logy na keši | ||
+ | %IF(" | ||
</ | </ | ||
- | Vidíte, že na první a zřejmě ani na druhý pohled není zcela patrné, k čemu se které uvozovka vztahuje. | + | **Jméno bodu:** |
- | </box> | + | <code none point.name.poigarmin.varsubst.template.txt> |
+ | # GeoGet, http:// | ||
+ | # Šablona pro knihovnu VarSubst, http:// | ||
+ | # Součást exportu POI Garmin, http:// | ||
+ | # | ||
+ | # Autor: medwyn_cz, http:// | ||
+ | # | ||
+ | # Šablonu můžete libovolně upravovat. Při aktualizacích exportu | ||
+ | # šablony uložené v adresáři " | ||
+ | # aktualizací ovlivněna. Nemusíte | ||
+ | # | ||
+ | # | ||
+ | %REPLACEFULL(" | ||
+ | # | ||
+ | # Celé jméno je obaleno ve funkci REPLACEFULL. Jejím úkolem je odstranit dvojité mezery, | ||
+ | # které by mohly ve jménu vzniknout | ||
+ | </code> | ||
+ | ==== Poznámky, známé problémy ==== | ||
+ | <WRAP round important> | ||
+ | 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. | ||
+ | </ | ||
- | ===== Uživatelské funkce ===== | + | <WRAP round important> |
- | 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 | + | Je důležité konstruovat šablonu s ohledem na pořadí nahrazování proměnných |
+ | </ | ||
- | Oproti | + | <WRAP round help> |
+ | Čas - ano, zpracování pomocí knihovny je nepochybně pomalejší než jednoúčelově na míru ušitý skript. Ovšem 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 [[user: | ||
+ | </ | ||
- | ==== Požadavky na uživatelské funkce | + | ===== 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ě, | ||
+ | |||
+ | 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: | ||
+ | - volá všechny uživatelské funkce, které byly registrované s příznakem bBefore | ||
+ | - nahradí proměnné (s výjimkou proměnných pro listing) | ||
+ | - nahradí logické proměnné | ||
+ | - provede funkce REPLACE | ||
+ | - nahradí TAGy (funkce TAG, IFTAG) | ||
+ | - provede funkce ROT13 a REVERSE | ||
+ | - zpracuje podmíněné nahrazení funkcí IF | ||
+ | - volá všechny uživatelské funkce, které byly registrované bez příznaku bBefore | ||
+ | - náhrada proměnných pro listing (LISTING, LONGLISTING, | ||
+ | - provede funkci REPLACEFULL | ||
+ | |||
+ | <WRAP round info> | ||
+ | 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, | ||
+ | </ | ||
+ | |||
+ | ==== 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í: | ||
+ | |||
+ | <code delphi> | ||
+ | * Nahrazuje proměnné hodnotami z hlavního bodu (keš, waymark) | ||
+ | |||
+ | <code delphi> | ||
+ | * Nahrazuje proměnné hodnotami z WPT bodu (parkoviště, | ||
+ | |||
+ | <code delphi> | ||
+ | * Registruje uživatelskou funkci pro nahrazování proměnných podle TGeo. | ||
+ | |||
+ | <code delphi> | ||
+ | * Registruje uživatelskou funkci pro nahrazování proměnných podle TWpt. | ||
+ | |||
+ | <code delphi> | ||
+ | * Ruší registraci uživatelské funkce | ||
+ | |||
+ | <code delphi> | ||
+ | * Poskytuje formulář pro testování šablony. | ||
+ | |||
+ | <code delphi> | ||
+ | * Poskytuje formulář pro testování šablony. | ||
+ | |||
+ | <code delphi> | ||
+ | * 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. | ||
+ | |||
+ | <code delphi> | ||
+ | * 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: | ||
+ | |||
+ | <WRAP round box> | ||
+ | |TGeo|struktura naplněná informacemi o konkrétním bodu (keši)| | ||
+ | |TWpt|struktura naplněná informacemi o doplňkovém bodu| | ||
+ | |sTemplate|vstupní 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 & | ||
+ | |sOutput|vý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.| | ||
+ | |bAnsi|pož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**.| | ||
+ | |fce|uživatelem definovaná funkce, která realizuje nahrazování nad rámec knihovních funkcí| | ||
+ | |bBefore|pož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)| | ||
+ | </ | ||
+ | |||
+ | <WRAP round important> | ||
+ | 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, | ||
+ | </ | ||
+ | |||
+ | ==== 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, | ||
+ | |||
+ | 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í: | Knihovna definuje dva typy uživatelských funkcí: | ||
Line 226: | Line 389: | ||
</ | </ | ||
- | 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. | + | 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**, | ||
+ | |||
+ | Příklad jednoduché uživatelské funkce: | ||
+ | <code delphi> | ||
+ | {Funkce nahrazuje vzor %MYOWNLISTING% za listing zpracovaný funkcí MyOwnEditation} | ||
+ | function UzivatelskaFunkce(geo: | ||
+ | begin | ||
+ | Result: | ||
+ | if(pos(' | ||
+ | then Result: | ||
+ | end; | ||
+ | </ | ||
- | 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 %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í |
- | :!: 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 // | + | <WRAP round info> |
+ | 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 // | ||
+ | </ | ||
- | ==== Registrace funkce a použití | + | === Registrace |
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í | 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í | ||
<code delphi> | <code delphi> | ||
- | function VarSubstAddFunctiondReplaceGeo(fce: | + | function VarSubstAddFunctiondReplaceGeo(fce: |
- | function VarSubstAddFunctiondReplaceWpt(fce: | + | function VarSubstAddFunctiondReplaceWpt(fce: |
</ | </ | ||
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.** | 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é '' | + | 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é '' |
<code delphi> | <code delphi> | ||
Line 250: | Line 428: | ||
begin | begin | ||
Result: | Result: | ||
+ | ... | ||
end; | end; | ||
- | ... | + | |
fUser: | fUser: | ||
aPopis.Add(' | aPopis.Add(' | ||
Line 259: | Line 438: | ||
</ | </ | ||
- | Třetí parametr informuje knihovnu o tom, zda registrovaná funkce má být volaná **před** nebo **po** | + | Třetí parametr informuje knihovnu o tom, zda registrovaná funkce má být volaná **před** nebo **po** |
V nečetných případech může být užitečné registraci funkce zrušit. K tomu slouží funkce | V nečetných případech může být užitečné registraci funkce zrušit. K tomu slouží funkce | ||
Line 270: | Line 449: | ||
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. | 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 | + | Pokud se v průběhu práce volajícího |
- | ===== Testování šablon | + | ==== Testování |
- | K testování šablon poskytuje knihovna dvě procedury. | + | K testování |
<code delphi> | <code delphi> | ||
Line 280: | Line 459: | ||
</ | </ | ||
- | 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. | + | 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. |
- | + | ||
- | 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í, | + | |
- | + | ||
- | 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č, | + | |
+ | <WRAP round important> | ||
+ | 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 jako Include nebo Unit ==== |
Knihovna je připravena ve dvou verzích. Je možné prostě includovat soubor | Knihovna je připravena ve dvou verzích. Je možné prostě includovat soubor | ||
Line 308: | Line 478: | ||
</ | </ | ||
- | Výhodou unit je bezproblémová práce s formulářem. | + | na prvním |
- | ===== Ukázka použití knihovny ===== | + | Výhodou unit je bezproblémová práce s formulářem, je tedy doporučeno používat tuto cestu. |
- | 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: | + | ==== Ukázka použití knihovny ==== |
+ | Úlohou programátora, který chce používat tuto knihovnu, je: | ||
- | - začlenit knihovnu do svého | + | - začlenit knihovnu do svého |
- vytvořit potřebnou šablonu nebo šablony | - vytvořit potřebnou šablonu nebo šablony | ||
- pokud je to nutné, vytvořit a registrovat uživatelské funkce | - pokud je to nutné, vytvořit a registrovat uživatelské funkce | ||
- | - v kódu exportního scriptu | + | - v kódu skriptu |
- | - měl by vytvořit | + | - vytvořit |
Za velmi jednoduchou ukázku nechť slouží následující kód | Za velmi jednoduchou ukázku nechť slouží následující kód | ||
<code delphi> | <code delphi> | ||
- | + | uses VarSubstUnit; // | |
- | //uses VarSubsUnit; // | + | //{$I VarSubst.lib.pas} |
- | {$I VarSubst.lib.pas} | + | |
var sTemplateGeo: | var sTemplateGeo: | ||
+ | var iErr: | ||
... | ... | ||
function MyReplace(input: | function MyReplace(input: | ||
begin | begin | ||
... | ... | ||
- | Result: | + | |
+ | then Result: | ||
+ | //POZOR, jakykoliv vkladany text musi byt v kodovani UTF-8! | ||
... | ... | ||
end; | end; | ||
Line 345: | Line 517: | ||
//nacteni sablony | //nacteni sablony | ||
sTemplate: | sTemplate: | ||
- | ... | + | ... |
+ | iErr := 0; | ||
end; | end; | ||
... | ... | ||
procedure PluginWork; | procedure PluginWork; | ||
- | var iErr: | ||
begin | begin | ||
... | ... | ||
Line 357: | Line 529: | ||
end; | end; | ||
+ | procedure PluginStop; | ||
+ | begin | ||
+ | if iErr > 0 then ShowMessage(' | ||
+ | end; | ||
</ | </ | ||
- | |||
- | ===== Instalace ===== | + | ==== Nastavení a konfigurace |
- | /* V případě potřeby je možno tuto sekci vymazat a neuvádět ji. */ | + | Knihovna neobsahuje žádné konfigurační parametry, které by měly být uživatelsky |
- | Poznámky | + | |
- | ===== Nastavení a konfigurace | + | ===== Seznam skriptů, které používají tuto knihovnu |
- | 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í. | + | {{topic> |
- | ===== Poznámky, známé problémy ===== | + | Pokud jste narazili |
- | :!: 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í. | + | |
- | + | ||
- | :?: Čas - ano, zpracování pomocí knihovny je nepochybně pomalejší než jednoúčelově | + | |
===== Stažení ===== | ===== Stažení ===== | ||
- | /* Povinná sekce */ | + | <WRAP round download> |
- | <box round 95% #DEE7EC> | + | Stáhnout aktuální verzi: ~~DOWNLOAD varsubst-*.gip highest~~ |
- | :!: Stáhnout aktuální verzi: ~~DOWNLOAD varsubst-*.gip highest~~ | + | </WRAP> |
- | </box> | + | |
- | + | ||
- | /* V této sekci není třeba nic měnit, pokud se budete držet následujících pravidel: | + | |
- | * - skript musí být distribuován v podobě balíčku [[: | + | |
- | * - balíček musí být pojmenován jako varsubst-čísloverze.gip | + | |
- | * - čísloverze obsahuje pouze číslice a tečky (např. 2.11.0.1) | + | |
- | * - balíček je uložen jako příloha ke stránce. POZOR! Balíček Je nutno uložit do jmenného prostoru stránky, tedy user: | + | |
- | */ | + | |
==== Seznam dostupných verzí ==== | ==== Seznam dostupných verzí ==== | ||
- | /* Povinná sekce */ | ||
{{filelist> | {{filelist> | ||
- | |||
- | /* V této sekci rovněž není třeba nic měnit, pokud se budete držet výše vypsaných pravidel */ | ||
===== Seznam změn ===== | ===== Seznam změn ===== | ||
- | /* Povinná sekce */ | + | ** 1.1.1.1 (2011/05/17) ** |
- | === 1.1 (2011/01/03) === | + | |
- | | + | |
- | /* Pokud je seznam změn již moc dlouhý */ | ||
<hidden onHidden=":?: | <hidden onHidden=":?: | ||
- | === 0.9 (Datum) === | + | ** 1.1.1 (2011/01/24) ** |
- | * Případné dřívější verze. Pokud je seznam změn příliš dlouhý, je vhodné starší verze skrýt pomocí tagu hidden. Pro jejich zobrazení bude muset uživatel kliknout na tlačítko | + | * Přidána nová funkce |
- | </ | + | * Editační formulář - Přidána možnost skrýt pravé výstupní podokno |
+ | * Přesunuto do podsložky \lib\VarSubst | ||
- | /* Seznam tagů. Tagy můžete stránce | + | * Oprava implementace |
- | {{tag>skript ggp lib ggc gge}} | + | * Opravena chyba v implementaci nahrazování proměnné %GGSCRIPTDIR% |
+ | * Editační formulář - při zavírání se zobrazí dotaz, zda si přejete upravenou šablonu uložit | ||
+ | * Další drobné úpravy a opravy | ||
+ | |||
+ | ** 1.1 (2011/01/03) ** | ||
+ | * Úvodní verze. Pracovali jsme na ní ve volných chvílích přes půl roku. | ||
+ | </hidden> | ||
+ | {{tag> |
user/skript/varsubst.1294062407.txt.gz · Last modified: 2011/01/03 00:00 (external edit)