Tabular-C++: Overview and Guide

Matthew Smith

Getting Started

We now present a short guide for you to write your first C++ program using Tabular-C++.

Step 1: Downloading Tabular C++ and Making it Accessible

The first step will be to download the latest version from the GitHub repository. Since the Tabular-C++ package is purely C++ headers, (.hpp), Python modules (.py) and bash scripts (.sh), there is no extra building required. We do however recommend that you run the configure.sh script, which will:

• Create a new environment variable TABCPP_ROOT and set it to the root directory of your version of Tabular-C++
• Add the value of TABCPP_ROOT to PATH
• Add TABCPP_ROOT/include to the system's include paths

All this is to ensure maximal convenience. There are other ways to get Tabular-C++ working with your projects, which we shall mention when relevant.

Step 2: Creating a New Project

The next step shouldn't present any issues, and this is down to personal taste in workflow.

Step 2.1 (Optional): Importing Tabular-C++ Into Your Project

However if you did not make Tabular-C++ globally accessible, you are recommended to adopt the following project structure:

example (root)
├── bin
│   └── compiled-binaries
├── include
│   ├── external
│   │   └── external-headers
│   └── example
│       └── project-headers
├── lib
│   └── libraries-to-link
├── src
│   └── project-sources
└── Makefile 

Now go to the root of your Tabular-C++ installation, and execute:

If you have done this correctly, you should find in your example folder.

• A bash script tabcpp.sh
• Two Python files: construct_table.py and tabcpp.py

Step 3: Create a Header File

With basic setup out of the way, we are ready to write the first component of our test program.

//FILE: example/include/example/example.hpp
#pragma once

#include<iostream>
#include<tabc/tabcpp.hpp>

typedef enum 
{
    COLOUR_RED, COLOUR_GREEN, COLOUR_BLUE,
    COLOUR_YELLOW, COLOUR_PINK, COLOUR_PURPLE,
    COLOUR_ORANGE, COLOUR_OTHER
} Colour;

//TABLE_BEGIN People
//TABLE_END People            

The comments //TABLE_BEGIN and //TABLE_END comments are crucial here. They will in time contain the code defining a table which we call People.

Step 4: Construct the Table

The recommended way to create a Tabular-C++ table, is by defining said table with a Python module.

//FILE: example/include/example/people_table.py
from tabcpp import *

tables = [
    {
        'name': 'People',
        'fields': [
            field('std::string', 'name'),
            field('int', 'age'),
            field('float', 'height'),
            field('Colour', 'favouriteColour')
        ],
        'key': key('auto', 'short', 'id')
    }
]

Now run the following command from the root example:

 $ tabcpp.sh load include/example example.hpp people_table 

Upon reloading example.hpp you shoud find, inserted between the aforementioned comments, some extra code. This code defines our table, and is now ready for use.

Step 5: Write the Main Source and Run

We are finally ready to write a program.

#include<example/example.hpp>

#include<tabc/tabcpp.hpp>

int main()
{
    //initialise an empty table
    People people;
    //adding a row to the table
    people.add("Jenifer", 32, 1.6, A);
    //adding a row and getting its unique (automatically generated) key
    short john_id = people.add("John", 22, 1.8, A);
    //giving the key a name for access convenience
    people.makeLabel(john_id, "JOHN");
    people.add("Harold", 69, 1.7, A);
    //getting data via a label
    float john_height = people.height.get(people.labels["JOHN"]); 
    std::cout << "John's height is " << john_height << " metres" << std::endl; 
    return 0;
} 

Hopefully most of what's going on at a hight level here is fairly intuitive. If not, there will be plenty of opportunity to understand this code when we go over using tables in detail.

Our program is ready for building, and if you do things correctly you should get the following output upon execution:

John's height is 1.8 metres

Previous: Introduction ; Next: More About Table Construction