Documentation
   Overview
   Why Clearsilver?
   Clearsilver Basics
     HDF Dataset
     Template Syntax
       Expressions
       Macros
       Functions
     CGI Kit
       Config Vars
     FAQ
   API Reference
     API Concepts
     C API
     Python API
       Introduction
     Perl API
     Java API
   Tools
     odb.py
   Comparison with PHP, ASP, JSP
   Comparison with XML/XSLT

The dataset and HDF Files

It is often convenient to load elements of a dataset from disk. Normally data is loaded from a ClearSilver file format called HDF, although it could easily be loaded from XML or another format. HDF stands for Hierarchical Data Format (yes, another HDF). It supports two different syntax for representing the dataset hierarchy which can be intermixed arbitrarily. The first is a simple dotted path scheme:

Page.Name = My Index
Page.URL = /myindex.html
Page.Menu.0 = Home
Page.Menu.1 = Preferences
Page.Menu.2 = Help
Page.Menu.3 = Support

The second is a nested elements scheme:

Page {
  Name = My Index
  URL = /myindex.html
  Menu {
    0 = Home
    1 = Preferences
    2 = Help
    3 = Support
  }
}

The hierarchy within an HDF file can be arbitrarily nested and contain any data elements desired. For instance, to extend the format of the Menu above, we could add:

Page {
  Menu {
    0 {
      Name = Home
      URL = /
    }
    1 {
      Name = Preferences
      URL = /prefs
    } 
    2 {
      Name = Help
      URL = /help.html
    }
    3 {
      Name = Support
      URL = /feedback/
    }
  }
}

Because APIs for HDF support reading and writing files in these formats, HDF can serve as a great configuration or persistence language. However, its primary purpose here is to load static elements into the dataset for use in a ClearSilver template.

When a ClearSilver template is rendering, it can reference specific variables in the dataset or iterate over all of the elements at a specific point in the dataset hierarchy. For example, a CS template which was rendering the HDF dataset above might iterate over Page.Menu, rendering each menu item's .Name and .URL elements.

There are two more important parts of the HDF file syntax.

A name can copy the contents of another name by using a colon instead of an equals sign. For example,
```
Page.Name : Page.Menu.0.Name
```
This means that Page.Name is the same as Page.Menu.0.Name. Note that Page.Menu.0.Name has to be defined before you can copy it into Page.Name.
A name can be set to a multi-line string value. This uses a syntax similar to standard UNIX shell/Perl syntax. For example:
```
Page.Name << EOM
This is my multi-line page name.
Isn't it spiffy?
EOM
```