Skip to content

Geist Templates

What is a Geist template?

A Geist template is a text file without a specific extension requirement although adding a .geist extension is recommended. It is an extension of a Jinja template, therefore it follows the default Jinja delimiters:

  • {% ... %} for Statements
  • {{ ... }} for Expressions to print to the template output
  • {# ... #} for Comments not included in the template output

How to write a Geist template?

A Geist template relies on tags and filters.

Tags

Tags are used within the statements, i.e., {% ... %}. There are two types of tags, StandaloneTag and ContainerTag. While the StandaloneTag does not require a closing tag, the ContainerTag does. Besides the Jinja predefined tags (e.g., for), Geist supports the following tags:

StandaloneTag:

ContainerTag:

Custom tags can be defined through files with the use tag.

Filters

Filters are used to modify variables. Each filter can only take one variable as input. Multiple filters can be applied to a single variable in sequence. For example, {{ var|filter1|filter2|filter3 }} denotes the variable var will be processed through filter1 first, then filter2, and filter3 at the end.

Besides the Jinja predefined filters, Geist supports the following filters:

  • head: extract the first 5 rows of a Pandas data frame
  • csv2df: convert a CSV string to a Pandas data frame
  • dict2df: convert a dictionary to a Pandas data frame
  • json2df: convert a JSON string to a Pandas data frame
  • json2dict: convert a JSON string to a dictionary
  • df2json: convert a Pandas data frame to a JSON string
  • df2htmltable: convert a Pandas data frame to an HTML table
  • escape_quotes: escape both double and single quotation marks
  • process_str_for_html: preprocess a string to be displayed within an HTML document, e.g., replace < with &lt

How to execute (expand) a Geist template?

CLI

report command can expand a report (Geist template) using dataset(s).

Here are options of the report command: 

Usage: geist report [OPTIONS]

Expand a report using dataset(s)

Options:
-ifile, --inputfile FILENAME   Path of the file containing the report
                                template to expand  [required]
-oroot, --outputroot TEXT      Path of the directory to store the expanded
                                report (default: current directory)
-so, --suppressoutput BOOLEAN  Suppress output or not (default: False)
-a, --args <TEXT TEXT>...      Arguments to be passed to the report
                                 template, e.g., (arg, value) indicates that
                                 {{ arg }} in the report template will be
                                 replaced by value
--help                         Show this message and exit.

Example 1: expand a report from stdin 
geist report << END_TEMPLATE

{% create "test", datastore="rdflib", inputformat="nt", isfilepath=False %}
    <http://example.com/drewp> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .
    <http://example.com/drewp> <http://example.com/says> "Hello World" .
{% endcreate %}

{% query "test", datastore="rdflib", isfilepath=False as all_triples %}
    SELECT ?s ?p ?o
    WHERE {
        ?s ?p ?o
    }
    ORDER BY ?s ?p ?o
{% endquery %}

{% for _, row in all_triples.iterrows() %}
    Subject: {{ row["s"] }}, Predicate: {{ row["p"] }}, Object: {{ row["o"] }}.
{% endfor %}

{% destroy "test", datastore="rdflib" %}

END_TEMPLATE
Example 2: expand a report from a file 
geist report --inputfile report.geist

Here is the report.geist file: 

{% create "test", datastore="rdflib", inputformat="nt", isfilepath=False %}
    <http://example.com/drewp> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .
    <http://example.com/drewp> <http://example.com/says> "Hello World" .
{% endcreate %}

{% query "test", datastore="rdflib", isfilepath=False as all_triples %}
    SELECT ?s ?p ?o
    WHERE {
        ?s ?p ?o
    }
    ORDER BY ?s ?p ?o
{% endquery %}

{% for _, row in all_triples.iterrows() %}
    Subject: {{ row["s"] }}, Predicate: {{ row["p"] }}, Object: {{ row["o"] }}.
{% endfor %}

{% destroy "test", datastore="rdflib" %}

Example 3: expand a report from a file with external arguments 
geist report --inputfile report.geist --args sentence "Hello World" --args feeling Happy

Here is the report.geist file: 

{% create "test", datastore="rdflib", inputformat="nt", isfilepath=False %}
    <http://example.com/drewp> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .
    <http://example.com/drewp> <http://example.com/says> "{{ sentence }}" .
    <http://example.com/drewp> <http://example.com/feels> "{{ feeling }}" .
{% endcreate %}

{% query "test", datastore="rdflib", isfilepath=False as all_triples %}
    SELECT ?s ?p ?o
    WHERE {
        ?s ?p ?o
    }
    ORDER BY ?s ?p ?o
{% endquery %}

{% for _, row in all_triples.iterrows() %}
    Subject: {{ row["s"] }}, Predicate: {{ row["p"] }}, Object: {{ row["o"] }}.
{% endfor %}

{% destroy "test", datastore="rdflib" %}

Python API

report function can expand a report (Geist template) using dataset(s).

Parameters description for report():

Name Type Description Default
inputfile string A report to be expanded REQUIRED
isinputpath bool True if the inputfile is the file path, otherwise the inputfile is the content False
outputroot string Path of the directory to store the expanded report current directory, i.e., ./
suppressoutput bool True to suppress output True
args dict External arguments, e.g., {"arg1": "value1", "arg2": "value2"} denotes that {{ arg1 }} and {{ arg2 }} in the report template will be replaced by value1 and value2 respectively {}
Example 1: expand a report from a string 
import geist

report = """

{% create "test", datastore="rdflib", inputformat="nt", isfilepath=False %}
    <http://example.com/drewp> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .
    <http://example.com/drewp> <http://example.com/says> "Hello World" .
{% endcreate %}

{% query "test", datastore="rdflib", isfilepath=False as all_triples %}
    SELECT ?s ?p ?o
    WHERE {
        ?s ?p ?o
    }
    ORDER BY ?s ?p ?o
{% endquery %}

{% for _, row in all_triples.iterrows() %}
    Subject: {{ row["s"] }}, Predicate: {{ row["p"] }}, Object: {{ row["o"] }}.
{% endfor %}

{% destroy "test", datastore="rdflib" %}

"""

# Return the expanded report as a string variable named expanded_report
expanded_report = geist.report(inputfile=report)
Example 2: expand a report from a file 
import geist

# Return the expanded report as a string variable named expanded_report
expanded_report = geist.report(inputfile='report.geist', isinputpath=True)

Here is the report.geist file: 

{% create "test", datastore="rdflib", inputformat="nt", isfilepath=False %}
    <http://example.com/drewp> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .
    <http://example.com/drewp> <http://example.com/says> "Hello World" .
{% endcreate %}

{% query "test", datastore="rdflib", isfilepath=False as all_triples %}
    SELECT ?s ?p ?o
    WHERE {
        ?s ?p ?o
    }
    ORDER BY ?s ?p ?o
{% endquery %}

{% for _, row in all_triples.iterrows() %}
    Subject: {{ row["s"] }}, Predicate: {{ row["p"] }}, Object: {{ row["o"] }}.
{% endfor %}

{% destroy "test", datastore="rdflib" %}

Example 3: expand a report from a file with external arguments 
import geist

# Return the expanded report as a string variable named expanded_report
expanded_report = geist.report(
    inputfile='report.geist', 
    isinputpath=True, 
    args={
        "sentence": "Hello World", 
        "feeling": "Happy"
    }
)

Here is the report.geist file: 

{% create "test", datastore="rdflib", inputformat="nt", isfilepath=False %}
    <http://example.com/drewp> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .
    <http://example.com/drewp> <http://example.com/says> "{{ sentence }}" .
    <http://example.com/drewp> <http://example.com/feels> "{{ feeling }}" .
{% endcreate %}

{% query "test", datastore="rdflib", isfilepath=False as all_triples %}
    SELECT ?s ?p ?o
    WHERE {
        ?s ?p ?o
    }
    ORDER BY ?s ?p ?o
{% endquery %}

{% for _, row in all_triples.iterrows() %}
    Subject: {{ row["s"] }}, Predicate: {{ row["p"] }}, Object: {{ row["o"] }}.
{% endfor %}

{% destroy "test", datastore="rdflib" %}