====== Hekate Markup Language - Mark 1 (2008) ======

**Note:** //this version is NOT supported by the [[HaDEs]] toolset!//

The is the first release of Hekate Markup Language known as HML1.

The Hekate Markup Language (HML) is based on the [[hekatedev:attributive language]], [[hekatedev:xtt development]] and [[hekatedev:ard development]] concepts.
There are the folowing subsets of the Hekate Markup Language defined: 
  * ''attml'' -- Attribute Markup Language
  * ''ardml'' -- Attribute Relationship Markup Language
  * ''xttml'' -- Rule Markup Language (not ready for deployment yet).

The languages can be used according to the following scenarios:
  - ''attml'' -- just attributes, nothing more
  - ''attml'' + ''ardml'' -- attributes and dependencies
  - ''attml'' + ''ardml'' + ''xttml'' -- attributes, dependencies and rulesin XML :!:
  - ''attml'' + ''xttml'' -- attribute and rules, ARD process is skipped

The big picture of a single HML application is as follows:

<code xml>
<hml>
  <!-- attml starts here -->
  <type_set>
    ...
  </type_set>

  <attribute_set>
    ...
  </attribute_set>
  <!-- attml ends here -->

  <!-- ardml starts here -->
  <property_set>
    ...
  </property_set>

  <tph>
    ...
  </tph>

  <ard>
    ...
  </ard>
  <!-- ardml ends here -->

  <!-- xttml starts here -->
  <xtt...TBD>
    ... TBD
  </xtt...TBD>
  <!-- xttml ends here -->
</hml>
</code>



===== DTD =====

Hekate markup language DTD: {{hml1.dtd}}.
For sytax test purposes there is example XML file: {{hml1-test.xml}} (its semantics does not make any sense though, for syntax testing only).

Important elements are indexed wit an attribute ''id''.
''id'' value has to be unique (enforced by DTD) and should start with (depending on particular element):
  * types: ''id="tpe_..."''
  * attributes: ''id="att_..."''
  * properties: ''id="prp_..."''
  * groups: ''id="grp_..."''
  * dependencies: ''id="tra_..."''
  * transformations: ''id="dep_..."''

An additional attribute (''id'') is introduced to guarantee that types, attributes, properties and groups can be uniquely referenced.
It can be forced, using DTD, that an attribute has a unique value within an XML document, it becomes a unique identifier.
Similarly, it can be forced that an attribute references an element by its unique identifier.
Making attribute names unique identifiers prevents naming a group, or type, with the same name as the attribute, since unique identifiers are unique within entire document regardless of the element they regard to.

You can validate any HML file using a validator i.e. xmlstarlet:

  xmlstarlet val -d hml1.dtd hml1-test.xml

===== ATTML =====

For information on attributes [[hekate:xtt#attributive_language|see here]],
as well as the [[hekate:bib:hekate_bibliography|gjn2008ruleapps]] FIXME.

<code xml>

  <type_set>
    <type id="tpe_0" name="Temperature" base="numeric" length="5" scale="0">
      <desc>represents a temperature</desc>
      <domain type="ordered">
        <range from="1" to="5"/>
	<value>7</value>
        <range from="20" to="22"/>
	<value>26</value>
	<value>27</value>
      </domain>
    </type>
  </type_set>
 
  <attribute_set>
    <att id="att_0" type="tpe_0" name="temp" abbrev="t1" value="single" class="ro">
      <desc>input temperature from sensor number 1</desc>
    </att>
    <att id="att_1" type="tpe_0" name="temp-aux" abbrev="t1a" value="multiple" class="ro">
      <desc>input temperature from sensor number 1, aux reading, including historic data</desc>
    </att>
 
    <group id="grp_0" name="sensors" abbrev="sns">
      <desc>temperatures from sensors</desc>
      <attref ref="att_0"/>
      <attref ref="att_1"/>
    </group>
  </attribute_set>

</code>

A group can always store multiple tuples (formed from the attributes within the group); it's non-atomic.
Atomic groups do not make any sense. 
In the example above there is an ordered set of tuples which are formed out of values of temp and corresponding temp-aux.
The group concept is similar to the relation concept in the relational Model.  
Attributes in a group are //ordered//.
--- //[[wojnicki@agh.edu.pl|Igor Wojnicki]] 2008/02/14 21:51//

''att'' tag, ''class'' attribute values: //ro,rw,wo,state//, legacy values //input,output,middle//


**question**: where to put  #digitis, #decimal point digits for numeric values?\\
**answer**: length=#of digits, scale=#of digits after the decimal point



===== ARDML =====
For ARD see [[hekate:ardplus]] FIXME
and
[[hekate:bib:hekate_bibliography#gjn2008flairs-ardformal]]
[[hekate:bib:hekate_bibliography#gjn2008flairs-ardprolog]]

<code xml>

<hml>
  <type_set>
    ...
  </type_set>

  <attribute_set>
    <att name="Thermostat" id="att_0"...>
      ...
    </att>
    <att name="Time" ...>
      ... 
    </att>
  </attribute_set>

  <property_set>
    <property id="prp_1">
      <attref ref="att_0"/>
    </property>
    <property id="prp_2">
      <attref ref="att_0"/>
      <attref ref="att_1"/>
    </property>
    <property id="prp_3">
      <attref ref="att_0"/>
    </property>
    <property id="prp_4">
      <attref ref="att_1"/>
    </property>
    <property id="prp_5">
      <attref ref="att_0"/>
    </property>
  </property_set>
 
  <tph>
    <trans id="tra_01" src="prp_1" dst="prp_2"/>
    <trans id="tra_02" src="prp_2" dst="prp_3"/>
    <trans id="tra_03" src="prp_2" dst="prp_4"/>
    <trans id="tra_04" src="prp_4" dst="prp_5"/>
  </tph>
 
  <ard>
    <dep id="dep_01" independent="prp_1" dependent="prp_2"/>
    <dep id="dep_01" independent="prp_2" dependent="prp_3"/>
    <dep id="dep_01" independent="prp_3" dependent="prp_4"/>
    <dep id="dep_01" independent="prp_2" dependent="prp_4"/>
  </ard>

  ...
  ...
</hml>

</code>

==== Defining Properties ====

Basic syntax:
<code xml>
<property_set>
          <property id="prp_1">
               <attref ref="att_0"/>
               ...
               <attref ref="att_ad003"/>
          </property>
		...
		<property id="prp_2">
               <attref ref="att_44"/>
               ...
               <attref ref="att_2"/>
          </property>
</property_set>
</code>

  * Properties are defined in ''<property_set>...</property_set>'' section. This section must contain all properties which are being used in an ARD diagram.
  * Single property is defined by ''<property>'' tag
  * Single property contains any number of attributes. A list of attributes is defined by ''<attref>''

==== Defining TPH Diagram  ====
Basic syntax:

<code xml>
     <tph>
          <trans src="prp_1" dst="prp_2"/>
          <trans src="prp_2" dst="prp_3"/>
          <trans src="prp_2" dst="prp_4"/>
		...
          <trans src="prp_n" dst="prp_m"/>
     </tph>
</code>


  * TPH diagram is definied in ''<tph>...</tph>'' section. TPH diagram contains relationships called transformations.
  * A transformation is defined with the ''<trans>'' tag and it describes a transformation between a source (''src'') and destination (''dst'') properties.

==== Defining Dependencies ====
**Basic syntax:**

<code xml>
<ard>
     <dep independent="prp_1" dependent="prp_2"/>
     <dep independent="prp_2" dependent="prp_3"/>
     ...
     <dep independent="prp_x" dependent="prp_y"/>
     ...
     <dep independent="prp_x" dependent="prp_z"/>
</ard>
</code>

  * Dependencies begin with the  ''<ard>'' tag. The tag does not have attributes. Each dependence is defined with a a pair of properties: an ''independent'' and a ''dependent'' one.






===== XTTML =====

For information on the XTT itself [[hekate:xtt|see here]],
for the XTTML [[hekate:xtt#rule_syntax|the rule syntax part]] is especially important.

The following is just a proposal, subject to verification/discussion etc.
There is no visual data regarding spatial distribution of XTT tables in XTTML.

<code xml>
  <xtt>
    <xtt_table id="xtt_1">
      <schema>
	<independent>
	    <attref ref="att_0"/>	  
	</independent>
	<dependent>
	    <attref ref="att_1"/>
	</dependent>
      </schema>
      <rule id="rul_1">
	<condition>
	  <logop name="in">
	    <attref ref="att_0"/>
	    <domain>
	      <range from="1" to="5"/>
	      <value>8</value>
	    </domain>
	  </logop>
	</condition>
	<decision>
	  <modop name="assign">
	    <attref ref="att_1"/>
	    <evalop name="add">
	      <attref ref="att_0"/>
	      <domain>
		<value>1</value>
	      </domain>
	    </evalop>
	  </modop>
	  <modop name="assign">
	    <attref ref="att_1"/>
	    <evalop name="add">
	      <domain>
		<value>5</value>
	      </domain>
	      <evalop name="sin">
		<attref ref="att_0"/>
	      </evalop>
	    </evalop>
	  </modop>
	</decision>
	<link xtt="xtt_1"/>
      </rule>

    </xtt_table>

  </xtt>
</code>

An XTT diagram (''xtt'' element) consists of some number of XTT tables (''xtt_table'' element).
The above example can be read as:

<code>
xtt_1:
rule_1: if att_0 in <1,5>u{8} then att_1 = att_0 + 1 and att_1 = 5 + sin(att_0)
</code>

==== Schema ====

Element ''schema'' describes dependent and independent attributes that are allowed to be used in a particular XTT table.
There are dependent (''dependent'') and independent (''independent'') attributes.
The schema is generated by the ARD->XTT transition algorithm directly from ARD.

==== Rule ====

A rule (''rule'') consists of a condition (''condition'') part and a decision part (''decision'').
The condition part uses logical operators (''logop'') which evaluate as true or false.

The decision part applies a modification operator (''modpop'') in order to change the attribute value.
The value can be given explicitly (as numeric, or symbol) or it can calculated as a result of an evaluative operator ''evalop''.

Each rule can explicitly select the next table to be investigated if fired.

===== Implementation =====

  * [[hekatedev:Hekate Markup Language Prolog]] -- implementation of a parser for HML (for developers only for now...).
  * [[hekatedev:hekate markup transformations|XSLT transformations]]