* [string](#string)
  * [Syntax of string values](#syntax-of-string-values)
  * [Cast to string](#cast-to-string)
  * [Strings as relative paths](#strings-as-relative-paths)
* [list](#list)
* [path](#path)
  * [Special syntax for references to path symbols](#special-syntax-for-references-to-path-symbols)
  * [Strings as integers](#Strings-as-integers)


Data type values are simple dumb constants
as found in most programming languages -
just data - no behaviour.


# string


A _string_ value is a sequence of characters, as usual.

It is useful for text, of course, and for relative paths.

It is defined by:

    def string MY_STRING = "my string value"


## Syntax of string values


A string value can be written in three ways:

 * `word`
 
   If the value is just a single word, it can be written as just that word.
   
 * `'multiple words'`
 
   Single quotes allows space in values.
   But symbol references **are not** substituted.
   
 * `"multiple words and references to @[SYMBOL]@"`
 
   Double quotes allows space in values.
   Symbol references **are** substituted.


## Cast to string


All other types of values can be casted to a string:

    def list   MY_LIST        = ...
    
    def path   MY_PATH        = ...
    
    def string MY_LIST_STRING = @[MY_LIST]@
    
    def string MY_PATH_STRING = @[MY_PATH]@

Casting a list gives a string with all the elements of the list separated by
a single space.

Casting a path gives the absolute path it represents
(if it is not relative the current directory).

Values are automatically casted to a string if they appear in a string value:

   `"a string value with the list @[MY_LIST]@ and the path @[MY_PATH]@"`


## Strings as relative paths


Relative paths are represented by strings:

    def string MY_FILE = my-file.txt
    
    def string MY_DIR = my-dir
    
    def string MY_FILE_IN_MY_DIR = @[MY_DIR]@/@[MY_FILE]@

They can be used together with the default relativity of an instruction
(as in `stdout`),
or with an explicit relativity
(as in `exists`):

    stdout equals @[MY_FILE]@
    
    exists -rel-act @[MY_FILE_IN_MY_DIR]@


## Strings as integers


The string type is used for values with no corresponding type.

For example, as integers:


    def string EXIT_ERROR = 2
    
    [assert]
    
    exit-code == @[EXIT_ERROR]@

 
# list


A _list_ value is a sequence of elements that are all strings.

It is useful for arguments to the SUT, or the `run` instruction:


    [def]
    
    def list MORE_SUT_ARGUMENTS         = first second "third element"  
    
    def list CUSTOM_ASSERTION_ARGUMENTS = arg1 arg2

    [act]
    
    my-system-under-test "initial argument" @[MORE_SUT_ARGUMENTS]@

    [assert]
    
    run my-custom-assertion @[CUSTOM_ASSERTION_ARGUMENTS]@
    

But list **cannot** be used for instruction arguments
that are defined by Exactly.

A list is defined by listing the elements separated by space:

    def list MY_LIST = value1 "value 2" @[SYMBOL]@
    
Symbol references to list values are concatenated,
unless they appear in a string:

    def list TWO_ELEM_LIST   = a b
    
    def list THREE_ELEM_LIST = 1 2 3
    
    def list FIVE_ELEM_LIST  = @[TWO_ELEM_LIST]@ @[THREE_ELEM_LIST]@
    
    def list FOUR_ELEM_LIST  = "the @[TWO_ELEM_LIST]@" @[THREE_ELEM_LIST]@

Symbol references to path values are automatically casted to string values.


# path


A _path_ value is an absolute path of a file.

> There is one exception to this - if the
path is defined to be relative the current directory ("-rel-cd").
The option to do this may be removed in the future.
Relative paths are best represented by string values.

Path symbols may be used anywhere a path is expected:

    def path MY_EXPECTED_FILE = -rel-home expected.txt
    
    [assert]
    
    stdout equals @[MY_EXPECTED_FILE]@

Path symbols may also be used anywhere a string value is expected,
since a path value is automatically casted to a string value.

A path symbol may be defined in terms of string values acting as
a relative path:

    def string MY_FILE           = my-dir/my-file.txt
    
    def path   MY_FILE_UNDER_ACT = -rel-act @[MY_FILE]@
    
    def path   MY_FILE_UNDER_TMP = -rel-tmp @[MY_FILE]@

A path value may also, of course, be defined in terms of other path values:

    def path   MY_DIR           = -rel-act my-dir
    
    def path   MY_FILE_1_IN_DIR = @[MY_DIR]@/my-file-1.txt
    
    def string MY_FILE_2        = my-file-2.txt
    
    def path   MY_FILE_2_IN_DIR = @[MY_DIR]@/@[MY_FILE_2]@

The path values above does not need to be be defined using `def`
to be used. They may appear anywhere a path value is expected:

    exists @[MY_DIR]@/@[MY_FILE_2]@ : type file


## Special syntax for references to path symbols


There is a special relativity option for symbols: -rel _SYMBOL_

This is an equivalent way to write the example with `exists` above:

    exists -rel MY_DIR @[MY_FILE_2]@ : type file

It can also be used by `def`:

    def path   MY_DIR         = -rel-act my-dir
    
    def path   MY_FILE_IN_DIR = -rel MY_DIR my-file.txt

Which syntax to use is a matter of taste.