5.5.3. Plik konfiguracyjny

Plik konfiguracyjny musi być poprawnym dokumentem XML. Oto przykładowa zawartość:

<?xml version="1.0" encoding="ISO-8859-2"?>

<aggregate xmlns="http://www.praterm.com.pl/IPK/aggregate" 
		xmlns:aggr="http://www.praterm.com.pl/IPK/aggregate" 
		xmlns:ipk="http://www.praterm.com.pl/SZARP/ipk"
		prefix="zamX" 
		title="Zamość">
		
	<config prefix="zamo">
		<remove xpath="//ipk:raport"/>
		<regexp xpath="//ipk:draw/@prior">s#.*#10\0#</regexp>
		<attribute xpath="//ipk:draw[not(@prior)]" name="prior"
			value="099"/>
	</config>

	<config prefix="zmk1">
		<remove xpath="//ipk:raport"/>
		<regexp xpath="//ipk:draw/@prior">s#.*#20\0#</regexp>
	</config>

	<config prefix="zmw3">
		<remove xpath="//ipk:raport"/>
		<remove xpath="//ipk:draw/@prior"/>
		<!--<regexp xpath="//ipk:draw/@prior">s#.*#30\0#</regexp>-->
	</config>

	<ipk:drawdefinable>
		<ipk:param name="Test:Bez sensu: sumaryczna temp. zewnętrzna"
				short_name="x" prec="1" unit="°C">
			<ipk:define type="DRAWDEFINABLE" 
			formula="(Sieć:Sterownik:temperatura zewnętrzna) ({zmk1} Komora KM-1:Komora:temperatura wody powrotnej) + 
({zmw3} Komora KW-1:temperatura zewnętrzna) +" />
			<ipk:draw title="TEST" min="0" max = "200" />
		</ipk:param>
	</ipk:drawdefinable>

</aggregate>

Główny element to aggregate. Powinien on zawierać deklaracje przestrzeni nazw http://www.praterm.com.pl/IPK/aggregate (aggr) i http://www.praterm.com.pl/SZARP/ipk (ipk). Zaleca się, aby ta pierwsza była przestrzenią domyślną, dzięki czemu nie trzeba będzie się do niej odwoływać w każdym elemencie.

Wymagane są także dwa atrybuty - title zawiera opisowy tytuł konfiguracji (wyświetlany w programie przeglądającym), natomiast prefix decyduje o nazwie i położeniu tworzonej konfiguracji wynikowej, w sposób opisany w poprzednim rozdziale.

Najważniejszą składową pliku są elementy config. Każdy z nich opisuje jedną konfigurację składową, o nazwie określanej przez atrybut prefix.

Pierwszy element config zawiera opis tak zwanej konfiguracji podstawowej. Parametry z tej konfiguracji nie będą podlegały przekształcaniu nazw. Pierwszy parametr z tej konfiguracji powinien być zapisywany do bazy (jest to wymaganie wynikające ze sposobu działania program SzarpDraw). Parametry statusu całej konfiguracji łączonej będą kopiowane także z niej. W związku z tym warto wybrać na konfigurację podstawową konfigurację największą, o największej pewności prawidłowej transmisji danych w ramach systemu BODAS.

Obecność elementu config z danym prefiksem oznacza włączenie do konfiguracji wszystkich parametrów z konfiguracji opisanej prefiksem. Nazwy parametrów (poza konfiguracją podstawową, pierwszą) są przekształcane do postaci {prefix} nazwa, np. parametr KM-1:Komora:Przepływ CO z konfiguracji o prefiksie zmk1 po konwersji będzie miał nazwę {zmk1} KM-1:Komora:Przepływ CO.

Jednak przed włączeniem i zmianą nazw parametry mogą być poddane przekształceniom opisanym przez elementy składowe elementu config - remove, regexp i attribute. Wszystkie te elementy mają wymagany atrybut xpath, zawierający wyrażenie XPath opisujące elementy, które mają być poddane przekształceniom. Wyrażenia XPath mają dostęp do przestrzeni nazw IPK za pomocą prefiksu ipk.

Możliwe są trzy typy przekształceń:

• Element remove powoduje usunięcie elementów wybranych elementów XML. Przykładowo, zwykle będziemy chcieli usunąć elementy raport, których i tak nie będziemy wykorzystywać:

  <remove xpath="//ipk:raport"/>

  Możemy też usunąć wybrane atrybuty:

  <remove xpath="//ipk:draw/@prior"/>

• Element regexp pozwala na przekształcenie zawartości elementu za pomocą wyrażenia regularnego (w praktyce odnosi się to tylko do zawartości atrybutów, gdyż elementy tekstowe i tak są usuwane i przeformatowywane w wynikowym dokumencie). Wyrażenie regularne podawane jest jako zawartość elementu i ma postać znaną z edytora vim lub programu sed - znak 's', potem znak oddzielający, a następnie wzorce dopasowujący i zastępujący, rozdzielone i zakończone znakiem oddzielającym. We wzorcu zastępującym możemy odwoływać się do całego wyrażenia (za pomocą \0) lub poszczególnych podwyrażeń (np. \1). Przykładowo

  <regexp xpath="//ipk:draw/@title">s#Komora(.*)#KM-1 \1#</regexp>

  spowoduje zastąpienie w atrybutach title początkowego napisu 'Komora' napisem 'KM-1'. Identyczny efekt może być uzyskany przez nieco prostsze wyrażenie regularne:

  <regexp xpath="//ipk:draw/@title">s#^Komora#KM-1#</regexp>

  Notatka: Program używa biblioteki GNU Regex i rozszerzonych wyrażeń POSIX. W starszych wersjach programu (wersje SZARP'a do 2.2.1294 włącznie) używana była biblioteka POSIX Regex i aby dokonać podstawienia cały napis (np. wartość atrybutu) musiał być dopasowany do wyrażenia. Obecnie nie jest to wymagane - podstawienie jest wykonywane na pierwszym znalezionym najdłuższym możliwym podciągu pasującym do zadanego wyrażenia.

• Element attribute pozwala na dodanie do elementu atrybutu o danej nazwie. Jeżeli istniał już atrybut o takiej nazwie, to zostanie on usunięty. Zawartość atrybutu może być ustalona na sztywno przez podanie jej w atrybucie value:

  <attribute xpath="//ipk:draw[not(@prior)]" name="prior" value="099"/>

  W powyższym przykładzie elementy draw, które nie posiadają atrybutu prior otrzymają taki atrybut, o wartości "099".

  Możliwe jest też ustalenie zawartości atrybutu przez skopiowanie innego atrybutu, podanego jako wyrażenie XPath w atrybucie copy, przy czym obliczanie wyrażenia zaczyna się od elementu docelowego (podanego jako atrybut xpath). Przykładowo:

  <attribute xpath="//ipk:param[not(@draw_name)]" name="draw_name" copy="@name"/>

  Elementy 'param' nie posiadające atrybutu 'draw_name' dostaną go z wartością skopiowaną z atrybutu 'name' tego samego elementu.

Przekształcenia są stosowane w takiej kolejności w jakiej wystąpią w pliku, można je więc łączyć aby uzyskać różnorodne efekty.

Ostatecznie, w pliku konfiguracyjnym może wystąpić element ipk:drawdefinable, zawierający dowolną ilość parametrów definiowalnych przeglądającego, w postaci dokładnie takiej, jak w dokumencie IPK. Formuły tych elementów mają dostęp do całej łączonej konfiguracji. Należy tylko pamiętać o zmianie nazw parametrów z konfiguracji składowych (poza pierwszą), oraz opatrywaniu wszystkich elementów prawidłowym prefiksem przestrzeni nazw IPK.

Następny rozdział (Sekcja 5.5.4) opisuje dodatkowy zaawansowany mechanizm, który może być wykorzystywany do tworzenia parametrów definiowalnych za pomocą szablonów.