Formatting Results

KosmicTask Help

Formatting Results

Result window document

The result window document format popup control enables the result text to be displayed in a number of formats.

Text Format

Text formatting displays the result as styled formatted text, however the exact formatting of the result depends upon how the result data is structured. Tasks can return results either as simple text or as structured data. In many cases returning simple text is sufficient if the result is intended as a simple message. If however the result contains a number of distinct items or a hierarchy of items then a structured result is preferable as it enables the result to be automatically formatted for display. Structured results can also be manipulated into different formats which is very useful when saving results to disk or when using them as input data for other tasks.

Simple Text Result

A simple text result consists of a single block of text. A task often generates a result of this kind using a simple print statement. The following simple Bash script, named Planets 1, simply prints a list of the planets:
# Planets 1
echo "Mercury"
echo "Venus"
echo "Earth"
echo "Mars"
echo "Jupiter"
echo "Saturn"
echo "Uranus"
echo "Neptune"
echo "Pluto"

The simple text result that is generated by the above script is displayed as follows:

Result document simple

Structured Text Result

We can easily modify out planets script to produce a structured result instead. In this case we will structure our result so that the individual planets appear as members of a list.

# Planets 2
echo "---"
echo "- Mercury"
echo "- Venus"
echo "- Earth"
echo "- Mars"
echo "- Jupiter"
echo "- Saturn"
echo "- Uranus"
echo "- Neptune"
echo "- Pluto"

The structured text result that is generated by the script Planets 2 is displayed as follows:

Result document structured

List items in structured results are automatically styled with alternating colour rows. Structured results can also be explicitly styled using CSS style strings. In the next script, Planets 3, we structure our result as a a keyed list (also known as a dictionary, map, hash or associative array). The keys are used to identify data elements and the styling that is to be applied to those elements.

# Planets 3
echo "---"
echo "kosmicData:"
echo " - Mercury"
echo " - Venus"
echo " - kosmicData: Earth"
echo "   kosmicStyle: 'color:blue;'" 
echo " - Mars"
echo " - Jupiter"
echo " - Saturn"
echo " - Uranus"
echo " - Neptune"
echo " - Pluto"
echo "kosmicStyle: 'color:red;'"

The styled text result that is generated by the script Planets 3 is displayed as follows:

Result document styled

In the above examples the structuring of the result has obvious presentational effects. But structuring the result also permits the result to be displayed, sorted and outlined in a result list view. In addition, structured results can be formatted in various ways either for viewing or for saving to disk. Selecting the list format for the Planets 3 result displays the result structure and permits sorting of the keys and values.

Result list styled

Plist Format

Plist formatting displays the result as a plist. A plist or property list is an OS X standard format for storing structured data. KosmicTask supports formatting of task data in the XML plist format. Both simple and structured text results can be formatted as plists but structured results will generally prove more useful when expressed as plists. Selecting the plist format for the Planets 3 result gives the following output:

Result document plist

Results can also be saved directly as plists by selecting the property list file format in the Save As sheet.

XML Format

Plists as described above are XML but the layout of the actual XML is particular to OS X. The alternative XML format option renders structured results using a different XML scheme that may be more readily interpreted by applications on other operating systems. The Planets 3 result formats as an XML plist as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>kosmicData</key>
	<array>
		<string>Mercury</string>
		<string>Venus</string>
		<dict>
			<key>kosmicData</key>
			<string>Earth</string>
			<key>kosmicStyle</key>
			<string>color:blue;</string>
		</dict>
		<string>Mars</string>
		<string>Jupiter</string>
		<string>Saturn</string>
		<string>Uranus</string>
		<string>Neptune</string>
		<string>Pluto</string>
	</array>
	<key>kosmicStyle</key>
	<string>color:red;</string>
</dict>
</plist>

The alternative XML option produces the following output:

<?xml version="1.0" encoding="UTF-8"?>
<results>
    <dictionary>
        <kosmicData>
            <array>
                <text>Mercury</text>
                <text>Venus</text>
                <dictionary>
                    <kosmicData>
                        <text>Earth</text>
                    </kosmicData>
                    <kosmicStyle>
                        <text>color:blue;</text>
                    </kosmicStyle>
                </dictionary>
                <text>Mars</text>
                <text>Jupiter</text>
                <text>Saturn</text>
                <text>Uranus</text>
                <text>Neptune</text>
                <text>Pluto</text>
            </array>
        </kosmicData>
        <kosmicStyle>
            <text>color:red;</text>
        </kosmicStyle>
    </dictionary>
</results>

This XML format utilises the following tags:

  • results. The XML document root.
  • text. A text string element.
  • number. A number element of type real.
  • integer. A number element of type integer.
  • bool. A number element of type boolean. 0 = false. 1 = true.
  • date. A date element.
  • data. A data element.
  • array. An array container. Child elements are members of the array.
  • dictionary: A dictionary container. Child elements are keys containing sub elements.

Results can also be saved directly in this XML format by selecting the XML file format in the Save As sheet.

YAML Format

In the examples above we generated our structured result by directly outputting YAML. In this case we will generate our structured result using an AppleScript record (a record is an associative storage type also known as a dictionary). KosmicTask can accept native objects as results for certain scripting languages including AppleScript. Returning native objects as results is often much more convenient that having to explicitly output YAML as arbitrarily complex native objects can be manipulated by the script and then returned as results in their entirety. The Planets 3 script can be rewritten in AppleScript like so:

-- Planets 3
on KosmicTask()
  try		
    -- create the inner planets
    set myResult to {"Mercury", "Venus"}
		
    -- add earth
    set end of myResult to {kosmicData:"Earth", kosmicStyle:"color:blue;"}
		
    -- add the outer planets
    set thePlanets to {"Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto"}
    repeat with planet in thePlanets
			
      -- planet is a reference hence we ask for its contens
      set end of myResult to contents of planet
    end repeat
		
    -- return result record
    return {kosmicData:myResult, kosmicStyle:"color:red;"}
		
  on error errorMessage number errorNumber
    return {kosmicError:errorMessage}
  end try	
end KosmicTask

This script produces exactly the same result as the bash variant of the Planets 3 script. Selecting the YAML format for the result displays the following:

kosmicData:
- Mercury
- Venus
- kosmicData: Earth
  kosmicStyle: color:blue;
- Mars
- Jupiter
- Saturn
- Uranus
- Neptune
- Pluto
kosmicStyle: color:red;

This AppleScript generated result is identical to the result returned more directly by the bash script. YAML was chosen for use in KosmicTask because of the qualities on display in these examples. YAML is human readable, largely due to the absence of tags and a reliance on indenting to define structure. YAML is also easy to generate from a wide range of languages. In addition many scripting languages have access to libraries that make it possible to easily express native data objects as YAML.