Terrace C Documentation

Getting Started

// Provides getline() for reading from stdin
#include <stdio.h>
// Provides free() for deallocating the lines from getline()
#include <stdlib.h>
// Provides document API for interacting with Terrace files
#include "document.h"

// Custom userData struct. Stores information needed
// by read_line below.
typedef struct read_line_container_s {
  size_t bufsize;
} read_line_container_t;

// A user-supplied function to read lines from stdin (or whichever data source you choose)
int read_line_from_stdin(char** line, void* userData) {
  read_line_container_t* lineContainer = (read_line_container_t*) userData;
  // Uses getline from the C stdlib to read the next line from stdin.
  int num_chars_read = getline(line, &lineContainer->bufsize, stdin);
  // Change trailing newline to null char. Terrace doesn't use trailing newlines
  if (num_chars_read > 0) (*line)[num_chars_read - 1] = '\0';
  // Return the number of charaters read to the document parser.
  return num_chars_read;
}

int main(int argc, char *argv[]) {
  read_line_container_t read_line_information = { .bufsize = 64 };
  // Initialize the terrace document with the line reader function created above.
  terrace_document_t doc = terrace_create_document(' ', &read_line_from_stdin, &read_line_information);
  
  // Loop over every line in the document.
  while(terrace_next(&doc, -1)) {
    // > Replace with your custom line handling code.
    
    // Print the line and level to demonstrate the terrace_level and terrace_line functions.
    printf("| level %u | line %s |", terrace_level(&doc), terrace_line(&doc, -1));
    // If one of the lines starts with "title", output it.
    if (terrace_match(&doc, "title")) {
      printf("Title: %s |", terrace_tail(&doc));
    }
  };
  
  // Free allocated line memory
  free(line);
  
  return 0;
}

Core API

terrace_linedata_t

// Holds the parsed information from each line.
typedef struct terrace_linedata_s {
  // Which character is being used for indentation. Avoids having to specify it on each terrace_parse_line call.
  char indent;
  // How many indent characters are present in the current line before the first non-indent character.
  unsigned int level;
  // The number of characters before the start of the line's "head" section.
  // (Normally the same as `level`)
  unsigned int offsetHead;
  // The number of characters before the start of the line's "tail" section.
  unsigned int offsetTail;
} terrace_linedata_t;

terrace_create_linedata()

// Call Signature
terrace_linedata_t terrace_create_linedata(const char indent)

terrace_parse_line()

// Call Signature
void terrace_parse_line(const char* line, terrace_linedata_t* lineData)

Document API

terrace_document_t

// Type Definition
typedef struct terrace_document_s {
  // == Internal State == //
  unsigned int _repeatCurrentLine;
  // Current line being read
  char* _currentLine;
  
  // == External Information == //
  // Embedded line data struct. Holds information about the current parsed line
  terrace_linedata_t lineData;
  // Custom data passed to the readline function
  void* userData;
  /**
  * Line reader function, provided by the user
  * Needed to get the next line inside of `terrace_next(doc)`
  * @param {char**} line First argument is a pointer to `_currentLine`, above
  * @param {void*} userData Second argument is `userData`, above
  * @returns {int} The number of characters read, or -1 if no characters were read.
  */
  int (*reader)(char** line, void* userData);
} terrace_document_t;

terrace_create_document()

// Call Signature
terrace_document_t terrace_create_document(const char indent, int (*reader)(char** line, void* userData), void* userData)

terrace_next()

// Call Signature
char terrace_next(terrace_document_t* doc, int levelScope)

// Usage
while(terrace_next(doc, -1)) {
  // Do something with each line.
}

terrace_level()

block
  block
  block
      block

// Call Signature
unsigned int terrace_level(terrace_document_t* doc)

// Usage
while(terrace_next(doc, -1)) {
  printf("Indent Level: %u", terrace_level(doc));
}

terrace_line()

root
    sub-line

// Call Signature
char* terrace_line(terrace_document_t* doc, int startOffset)

// Usage
while(terrace_next(doc, -1)) {
  printf("Line with indent characters: %s", terrace_line(doc, 0));
  printf("Line without indent characters: %s", terrace_line(doc, -1));
}

terrace_head_length()

title An Important Document

// Call Signature
unsigned int terrace_head_length(terrace_document_t* doc)

// Usage
while(terrace_next(doc, -1)) {
  printf("Head length: %u", terrace_head_length(doc));
}

terrace_tail()

title An Important Document

// Call Signature
char* terrace_tail(terrace_document_t* doc)

// Usage
while(terrace_next(doc, -1)) {
  printf("Line tail: %s", terrace_tail(doc));
}

terrace_match()

title An Important Document

// Call Signature
char terrace_match(terrace_document_t* doc, const char* matchHead)

// Usage
while(terrace_next(doc, -1)) {
  printf("Does the line start with 'title': %d", terrace_match(doc, "title"));
}

Recipes

Parse a single line

#include "parser.h"

int main(int argc, char *argv[]) {
  char* line = "example line";
  // Create the line_data struct
  terrace_linedata_t line_data;
  // Set the indent character to a space
  line_data.indent = ' ';
  // Populates line_data level, offsetHead, and offsetTail from line
  terrace_parse_line(line, &line_data);
  
  printf(
    "level %u | indent %c | offsetHead %u | offsetTail %u\n",
    line_data.level,
    line_data.indent,
    line_data.offsetHead,
    line_data.offsetTail
  );
  
  return 0;
}

Parse all lines from stdin

#include "parser.h"
// Depends on several cstdlib functions
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>

int main(int argc, char *argv[]) {
  // Pointer to start of line
  char *line = NULL;
  // Initial size of the buffer to read into
  // getline() will resize as needed
  size_t bufsize = 128;
  // How many characters have been read
  ssize_t chars_read = 0;
  
  // Create the line_data struct
  terrace_linedata_t line_data;
  // Set the indent character to a space
  line_data.indent = ' ';
  
  while (chars_read = getline(&line, &bufsize, stdin)) {
    // If chars_read is -1, we've reached end of file.
    if (chars_read == -1) break;
    // getline returns lines with a trailing newline
    // terrace_parse_line expects no trailing newline
    // strip it off using strtok()
    // (An odd solution, probably leaks memory)
    char *terrace_line = strtok(line, "\n");
    terrace_parse_line(terrace_line, &line_data);
    
    printf(
      "level %u | indent %c | offsetHead %u | offsetTail %u\n",
      line_data.level,
      line_data.indent,
      line_data.offsetHead,
      line_data.offsetTail
    );
  };
  
  // Free the buffer allocated by getline().
  free(line);
}

Contributing