Quick Start Guide

Installation

Install the Nim programming language to your machine. Further information are provided on the official Nim installation site.. We recommend installation of Nim via choosenim.
Install FETA via the Nimble package manager. Nimble is installed automatically for any Nim version after 0.15.0. To install FETA you can use the following command:

nimble install feta

If for some reason this does not work try:

nimble install https://github.com/FlorianRauls/feta

(Optional) After the installation process is finished, you might need to take extra steps, to use all available functionalities of the FETA language. Since FETA be used as an interface to send e-mails or to load spreadsheets from Google Sheets, some credentials have to be entered, to use these functionalities.

You can run any Nim program, which contains FETA code via:

nim c -r -d:ssl yourprogram.nim

E-Mail

SMTP-Server

You need a functioning SMTP-server to send emails via FETA. E.g., gmail allows sending messages via their SMTP-server, after creating an app password.

Experimental

Run nim c -r ~/.nimble/pkgs/feta-CURRENTVERSION/feta/setup.nims. This walks you through the setup process.

Conventional

If the automatic setup did not work, open up console userData.nim at the installation location for your feta installation. If you used nimble, this would be console ~/.nimble/pkgs/feta-CURRENTVERSION/feta/files/userData.nim under most Linux distributions. This file should look like this:

var userMail* = "" ## Insert your email-adress here
var userMailWord* = "" ## Insert your email-password here
var smtpServer* = "" ## SMTP-server you are using
var smtpServerPort* = "" ## Port of SMT-server you are using

Do be careful, that your information is stored in plain text. Keep this file save!

Google Sheets

Go to Google Cloud Platform
Go to the top bar and create a new project
Name your project
Click inside the new project on the plus sign which reads "Enable APIS and Services"
Search for "Google Sheets"
Enable the Google Sheets API
Back at the overview click on "Credentials"
Click the plus that reads "Create Credentials"
Create a new service account
Click on the service account and open the tab "Keys"
Create a new JSON-key
Move the downloaded file to console ~/.nimble/pkgs/feta-CURRENTVERSION/feta/files/
Enter the filename under console ~/.nimble/pkgs/feta-CURRENTVERSION/feta/files/userData.nim

The DSL should now have access to Google Sheets.

Getting Started

FETAs main datatype is the so called SpreadSheet. This holds a sequence of Row-objects, which in turn hold a sequence of Cell-objects. SpreadSheet also has a header, which is also a Row.

You can create a SpreadSheet via:

var spreadsheet = CREATE_SPREADSHEET:
    "Header1" | "Header2"
    "Row1_Value1" | "Row1_Value2"
    "Row1_Value1" | 14
    "Row1_Value1" | null

null is a global variable denoting an empty Cell.

Alternatively SpreadSheets can be loaded from the following sources: CSV, HTML, Google Sheets, Webcrawl(from a website) via:

var spreadsheet = LOAD:
    SOURCE:
        "filepath/googlesheetsid"

Saving goes as follows:

spreadsheet.SAVE:
    TARGET:
        "filepath/googlesheetsid"

To get a pretty-print of your SpreadSheet use SHOW spreadsheet. You can get string-values from a SpreadSheet via spreadsheet.AT(index, columnName).

A central feature of FETA is the dynamic creation of web server environments. All code that should be executed on a web server has to be placed in an ONSERVER-environment like this:

ONSERVER:
    code

A SERVER holds two different kinds of Spreadsheets. view and form. While a view is only for reading a SpreadSheet, a form can be edited and send back to the SERVER. Syntax for adding a simple form:

ONSERVER:
    ADDFORM:
        SPREADSHEET:
            spreadsheet
        AS:
            name
        ALLOWEDIT:
            @[columnName, columnName2]
        ACCEPTIF:
            condition (needs to return true/false)   
        ONACCEPT:
            code

This code will host a form under http://localhost:5000/?id=name, where column1 and column2 are editable. You can receive every SpreadSheet on a SERVER via SERVER[name].

ACCEPTIF is a function, which decides whether a form entry is valid or not. Code blocks inside the ACCEPTIF environment always receive the submitted SpreadSheet as the COOMIT parameter. ONACCEPT is a function, which gets executed if ACCEPTIF returns true. Code blocks inside the ONACCEPT environment always receive the submitted SpreadSheet as the COOMIT parameter.

A view can be added to the SERVER via:

ONSERVER:
    ADDVIEW:
        SPREADSHEET:
            spreadsheet
        AS:
            name

Another central component of FETA is the capability of sending emails. To use this feature, you have to enter your user data as described above. You might also need to configure your SMTP-server. If set up correctly, you can send emails like this:

SENDMAIL:
    TO:
        recipient@mail
    SUBJECT:
        "subject"
    TEXT:
        "text"
    ATTACHMENT:
        "filepath"

Examples

Our tests include some files called scenario1.nim-scenario4.nim, which highlight how a typical FETA-program should be written. Please note, that scenario1.nim is not executable right now, since it relies on Google Sheets. If you want it to work, you need to set up Google Sheets and a Google Sheets-sheet.

Documentation

Detailed documentation can be found here. FETA is a domain-specific language, embedded in the Nim programming language. This means, that the FETA language is an interface for an office automation library. Both the interface and the library are written in Nim and are therefore subsets of the Nim programming language. This is a list of all FETA-statements and what functionality they are interfacing:

 Value1 | Value2 | ValueN

Creates a new Row-object with n values. Values will be interpreted automatically and be saved as Cell-objects in the new Row.

row.INSERT:
    value1
    ...
    valueN

Appends all n values to the end of the row.

SHOW spreadsheet

Pretty-prints the given spreadsheet to console

CREATE_SPREADSHEET:
    Row1
    ...
    RowN

Creates a new Spreadsheet from the given rows. The first given row will automatically be interpreted as the header of the new spreadsheet.

spreadsheet.ADDROW:
    Row1
    ...
    RowN

Appends all the given rows to the spreadsheet.

spreadsheet.REMOVEROW:
    Index1
    ...
    IndexN

Removes all rows, given by index, from the spreadsheet.

spreadsheet.LENGTH

Returns the number of rows of the spreadsheet.

spreadsheet.ADDCOLUMN:
    row1
    ...
    rowN

Interprets all given row-objects as columns, and adds these columns to the spreadsheet.

spreadsheet.REMOVECOLUMN:
    name1
    ...
    nameN

Removes all columns, which names are given, from the spreadsheet.

spreadsheet.RENAMECOLUMN:
    FROM:
         old_name
    TO:
        newName

Renames the column stated under FROM, to the value under TO.

FROM_PROC:
    generic_proc() : SpreadSheet

Creates a new SpreadSheet from the generic proc. The proc can be given in the form of a passed proc(), or of a code block, which at some point returns a SpreadSheet-object. This functionality is especially useful, when working in server environments, where dynamic outputs are needed.

LOAD:
    __META-API__:
       meta_api_argument

SAVE:
    __META-API__:
       meta_api_argument

Load or save through the meta-API. Possible formats are:

CSV
HTML
GoogleSheets
Webcrawl (from website; only loading possible; still rather experimental)

Planned but not yet implemented:

Excel
XML
OpenDocument

Indirectly Possible:

JSON (read file as string --> parse to SpreadSheet)

META-API has to be substituted by the corresponding format name.

spreadsheet.JOIN:
    spreadsheet1
    ...
    spreadsheetN
    ON:
       column_name

Executes a left-join of all given spreadsheets on the given column on the spreadsheet.

spreadsheet[seq[int], seq[string]]

Creates view of spreadsheet, based on the given rows and columns.

spreadsheet.UPDATE(viewOfSpreadsheet, column)

UPDATE is a special function. If viewOfSpreadsheet shares columns with spreadsheet, it matches rows of both of them. It then proceeds to overwrite values in spreadsheet with values from viewOfSpreadsheet.

ONSERVER:
    generic_code

ADDVIEW:

ADDFORM:

SENDMAIL:
    TO:
       emailAddress
    TEXT:
       text
    SUBJECT:
       subjectText
    ATTACHEMENT:
       path_to_file

Provide feedback

Saved searches

Use saved searches to filter your results more quickly