Knihovna SCANCSV.LUA Jaroslav Hajtmar

Apology English-speaking participants Sorry, but this talk is only in Czech. Due to my language skills I would probably just did not know enough to say everything important. I will try to at least the guide slideshow in English. Thanks for your understanding.

Abstrakt Při hromadném zpracování dat se často používají údaje uložené v CSV (comma separated values) souborech. V přednášce bude popsána autorova knihovna ScanCSV.lua, způsob jejího vzniku a budou předvedeny praktické ukázky jejího použití. Autor ukáže, jak lze snadno a rychle vytvářet tiskové sestavy (formuláře, hromadné dopisy, vysvědčení, pozvánky, průkazky, vizitky, oboustranné kartičky atd.) využívající externí textové CSV databáze. Data z externích CSV tabulek lze použitím Lua funkcí a TEXových maker na nich postavených, zpřístupnit uživatelům ConTEXtu MkIV (ale i LuaLATEXu a LuaTEXu) a to zajímavým a přitom velmi jednoduchým a přirozeným způsobem.

Úvod Knihovna SCANCSV.LUA : Jednoduchým způsobem zpracovává v ConTeXtu MkIV (LuaLaTeXu, LuaPlainu) textová data uložená v externích CSV souborech. Umožňuje jednoduchým a přirozeným způsobem vytvářet v ConTeXtu dokumenty, které jsou založeny na zpracování hromadných dat (jednoduchých CSV databází). Má široké využití: tisk různých formulářů, vysvědčení, pozvánek, průkazek, kartiček (i oboustranných), hromadných dopisů, pozvánek, vizitek, tabulek, animací atd. Hlavní důraz byl při tvorbě knihovny kladen na: jednoduché použití bez znalosti Lua, užívání nejen v ConTeXtu, ale i v LuaLaTeXu a LuaPlainTeXu, zpřístupnění CSV dat prostřednictvím TeXových maker postavených na knihovních funkcích (tj. bez Lua kódu), motivace dalších uživatelů k používání LuaTeXu a jazyka Lua.

CSV formát a SCANCSV.LUA Výměna dat, export do CSV (z MySQL databází), jednodušší alternativa k XLM, lze snadno zpracovávat (třídit a editovat) v tabulkových procesorech (Excel, Calc, Gnumeric, …) Popis CSV formátu obecně CSV formát vhodný pro SCANCSV.LUA: – soubor musí být kódován v UTF-8! (vyexportované XLS soubory se musí překódovat - nevýhoda) – Oddělovače polí: v podstatě libovolné, defaultně použit ‘;’ středník (tj. a la Excel) – Vymezovače polí : v podstatě libovolné levý i pravý mohou být různé (nejčastěji bývají “ uvozovky), defaultně nepoužito!!! – Parsovací algoritmus SCANCSV.LUA je velmi jednoduchý (lze jej však libovolně upravit) => omezení (pokud nastavíme vymezovače, musí být použity všude – obecně to tak být nemusí)

SCANCSV – historie vzniku, inspirace 2005 – nalezení makra scanbase.tex Petra Olšáka. Makro zpracovává textové soubory ve formátu podobném CSV Petr Olšák makro scanbase.tex zmodifikoval a zobecnil – vzniklo makro scancsv.tex – zpracovává soubory v CSV formátu. Toto makro jsem v plainTeXu používal až do r – vznik modifikace pro LaTeX (Jaromír Kuben) a pro ConTeXt (Petr Olšák). Toto makro používám v ConTeXtu MkII dodnes – začínám používat ConTeXt MkIV. Původní Olšákovo makro v MkIV nefunguje!! ConTeXt MkIV pracuje se znakovou sadou UTF-8, ale makro není schopno tuto znakovou sadu zpracovávat. Duben 2010 – seznámení se s LuaTeXem, jazykem Lua. Začínám programovat knihovnu scancsv.lua. Hlavní důvod: použití v ConTeXtu MkIV. První verze byla bohužel pro běžného uživatele prakticky nepoužitelná! Červen 2010 – první reálně použitelná verze Dnes – otestováno ostré nasazení v řadě praktických úloh, včetně agendy pro CTM a TE, vylepšování, ladění a rozšiřování funkčnosti

Princip fungování knihovny 1.Načtení knihovny scancsv.lua (jediný Lua kód ve zdrojovém textu ConTeXtu). 2.Volitelné nastavení příznaku hlavičky, separátoru a vymezovačů položek (jinak se použijí default hodnoty). 3.Otevření CSV souboru (různými způsoby). 4.Načítání řádku CSV tabulky (manuálně nebo v cyklu) 5.Rozparsování řádku (oddělení sloupcových dat). 6.Načtení sloupcových dat do TeXových maker. 7.Opakování kroků pro všechny řádky CSV tabulky. Způsob zpracování 1. řádku tabulky závisí na tom, zda je to „hlavička“ či nikoliv. Po načtení sloupcových dat do maker jsou data přístupná ConTeXtu. Řádky lze procházet „manuálně“, prostřednictvím standardních cyklů nebo knihovním makrem.

Načtení knihovny Otevření CSV souboru Pak již ve zdrojovém textu užíváme makra \cA, \cB, … (nebo \Firstname, \Lastname, … pokud 1. řádek obsahuje hlavičku). Tato makra obsahují sloupcové hodnoty aktuálního CSV řádku \nextrow – přechod na další řádek tabulky (makra \cA, \cB, … naplněna novými hodnotami) Použití v „manuálním“ režimu

Hlavní TeXová makra pro používání knihovny \setfiletoscan{CSVFile} – nastavení jména CSV souboru \setheader – nastavení příznaku hlavičky \resetheader – vrácení nastavení na defaultní hodnotu \setsep{,}, \setld{*}, \setrd{!} – nastavení oddělovače sloupců a vymezovačů sloupců na vlastní hodnotu (nedafaultní) \resetsep, \resetld, \resetrd – reset tj. zpět na default hodnotu \opencsvfile{CSVFile}, \openheadercsvfile{CSVFile} \nextrow – skok na další řádek CSV tabulky \printline, \printall – vypsání celého řádku / celé tabulky \filelineaction, \filelineaction{CSVfile}, \filelineaction{CSVfile}{to}, \filelineaction{CSVfile}{from}{to} – makra pro zpracování uživatelem definovaného makra \lineaction v cyklu

1;Petr;Novák; ;m;Nymburk;U Brány 7 2;Jan;Novotný; ;m;Praha;Uhlířská 178 3;Zuzana;Vašíčková; ;ž;Ostrava;Jánská 14 … Možnost nastavení římského číslování: \cI, \cII, \cIII, \cIV, … ( defalut UserColumnNumbering=‘XLS’ ) \cA \cB \cC \cD … \resetheader Surname;Firstname;Birthdate;Sex;City;Zipcode;Street Novák;Jan; ;m;Zbečno;27024;Farní 21 Pospíšilová;Hana; ;ž;Zábřeh;78901;Studénky 420 … \cA = \Surname \cB = \Firstname \cC = \Birthdate … \setheader no header Header (no data) data lines CSV file with Header (switch with \setheader) CSV file without Header (default option - \resetheader) TeX macros for accessing columns data

TeXová makra pro získání „systémových“ informací \csvfilename – Jméno aktuálně otevřeného CSV souboru \numcols – Počet sloupců CSV tabulky \numrows – Počet zpracovaných (vypsaných) řádků \numline – Pořadové číslo aktuálně načteného řádku \csvreport – Reportní informace o otevřeném souboru Háčky (hooks) pro zpracování dat (defaultně \relax) \blinehook, \elinehook – begin line hook, end l.h. – makra se provedou před a po zpracování řádkového makra \lineaction (tj. řádku CSV tabulky) \bfilehook, \efilehook – provedou se před a po zpracování celé CSV tabulky \bch, \ech – begin column hook, end c.h. - lze manuálně nastavit v lua kódu, kvůli nemožnosti testování maker je tato volba vypnuta TeXový IF pro test konce CSV souboru \ifEOF – TRUE, pokud se dostaneme při zpracování na konec CSV souboru \ifnotEOF – opak \ifEOF

Ve zdrojovém textu užíváme makra \cA, \cB, … nebo \Firstname, \Lastname, … (pokud 1. řádek obsahuje hlavičku) obsahující sloupcové hodnoty aktuálního CSV řádku \nextrow – přechod na další řádek tabulky (makra \cA, \cB, … naplněna novými hodnotami) Použití v „manuálním“ režimu

Modifikace funkčnosti knihovny Defaultní nastavení lze změnit editací souboru scancsv.lua – v úvodní části kódu V průběhu zpracování ConTeXtem (LuaLaTeXem) lze průběžně měnit nastavení separátoru, vymezovačů, hlavičky, … pomocí TeXových maker Možnost zpracování různých CSV souborů v jednom dokumentu (i s různými oddělovači a vymezovači sloupců) Užití „hooks“- defaultně jsou \relax

Nejdůležitější knihovní Lua funkce ParseCSVdata() -- Funkce pro "rozparsování" jednotlivých záznamů (řádků) CSV tabulky lineaction() -- vytiskne uživatelské makro \lineaction pro řádky dle zadaného rozsahu u otevřeného CSV souboru CreatePageFiles() -- vytvoří z CSV souboru dva soubory, sloužící k oboustrannému tisku kartiček, tisknutých na stránku v bloku R x C (funkce "přeskládá" CSV soubor se 2. stránkou tak, aby si přední a zadní strany kartiček odpovídaly) Filelineactioncards() – tisk 1. a 2. strany kartiček ze souborů vytvořených předchozí funkcí CSVReport() -- výpis reportových informací o otevřeném CSV souboru csvfilename() – vrátí název otevřeného CSV souboru TMN(s) -- TeX Macro Name. Název makra nesmí obsahovat zakázané znaky ar2rom() -- Převod arabských čísel na římská. Použito pro "číslování" sloupců v makrech ar2xls() -- převod čísla na název Excelovského sloupce ar2colnum() -- podle nastavení glob. proměnné vrací označení sloupce TeXového makra printline() -- vypíše aktuální řádek CSV tabulky printall() -- vypíše celou CSV tabulku printallcontext() -- vypíše celou CSV tabulku v ConTeXtové syntaxi

Testování a cykly Podmínky AND a OR (viz. Olšák TBN): % podminka A AND B \doloop{ \ifnum\Id>2 \ifnum\Id<10\lineaction \fi \ifEOF\exitloop\else\nextrow\ifEOF\exitloop\fi\fi } % Podminka A OR B \def\AorB{\lineaction} \doloop{ \ifnum\Id=1\AorB% \else\ifnum\Id>3\AorB\fi \fi \ifEOF\exitloop\else\nextrow\ifEOF\exitloop\fi\fi }

SCANCSV.LUA a cykly Příklady ConTeXtových cyklů: \dorecurse{5}{\lineaction\nextrow} - \lineaction pro následujících 5 řádků \doloop{\lineaction\nextrow\ifnum\numline>7\exitloop\fi} \doloop{\ifEOF\exitloop\else\lineaction\nextrow\fi} \doloop{\lineaction\nextrow \if\Id3 \exitloop \fi} Příklady knihovních cyklů (zatím pouze v testovací verzi SCANCSV.LUA): Makra jsou postavena na \doloop makru pro snazši použití ve zdrojovém kódu. \doloopwhile{\Trida}{3.A}{\tableaction} % Vypsat všechny splňující kriterium \doloopuntil{\Trida}{3.A}{\tableaction} % Vypisovat dokud není splněno \doloopforall{\lineaction} – pro všechny řádky provede \lineaction \doloopfromto{3}{7}{\lineaction} \doloopaction – bez parametru provede pro všechny řádky \lineaction. \doloopaction{\useraction} – provede pro všechny řádky \useraction \doloopaction{\useraction}{5} – pro prvních 5 řádků provede \useraction \doloopaction{\useraction}{5}{7} - pro řádky 5-4 provede \useraction

Praktické ukázky užití knihovny Formuláře, hromadné dopisy atd. Kartičky, vizitky, … Tabulky Metapostové animace Užití ConTeXtových cyklů, IF testy SCANCSV.LUA „úlety“ (TeXová makra v CSV souboru, změna \lineaction v průběhu zpracování CSV)

Omezení, kompatibilita, zádrhele SCANCSV.LUA nezpracovává obecné CSV soubory. Důvod: parsovací algoritmus je velmi jednoduchý. Př. Pokud sloupcová položka obsahuje separátor, běžný CSV výstup je: 1,Jan,Novotný,”U Brány 4, Praha”, … Řešení: zdokonalení parsovacího algoritmu tj. pouze úprava funkce ParseCSVdata(). Problémy s expanzí. Např. nepodařilo se mi zprovoznit SCANCSV.LUA v modulu database (\usemodule[database]) Mojca Miklavec

Možnosti vylepšení … Vylepšení a zobecnění parsovacího algoritmu Použití pro zpracování XML??? Vytvoření samostatného modulu POUZE PRO MKIV (zmizí řada omezení pro LuaLaTeX)

Poděkování Členům mail. konference za rady týkající se ConTeXtu a Lua. Knihovna by nevznikla díky jejich laskavé pomoci. Zvláštní poděkování Taco Hoekwaterovi, Hansovi Hagenovi, Wolfgangu Členům mail. konference za rady týkající se TeXu a LaTeXu. Zvláště panu Zdeňku Wagnerovi, Vítu Zýkovi, Pavlu Střížovi, Petru Pavlu Střížovi za inspiraci, testování, rady a za to, že mne „přesvědčil“ abych knihovnu dokončil a prezentoval na této konferenci.

DISKUZE