layout layout.njk
title C Documentation - Terrace
description
  C language documentation for the Terrace programming language

Section light
  class flex flex-col md:flex-row gap-16

  Block
    class w-full lg:w-1/3
    TableOfContents

  Block
    Heading 1 Terrace C Documentation
      class -ml-2

    Markdown
      Documentation is available for the following languages:
      - [C](/docs/c/) - 75% Complete
      - [JavaScript](/docs/javascript/) - 75% Complete
      - [Python](/docs/python/) - 0% Complete

    Heading 2 Getting Started
      class mt-12 mb-6
    Markdown
      The terrace parser is distributed as a set of C header files.<br/>
      To use it, download and include the following files in your project tree:
      - [parser.h](https://git.thederf.com/thederf/Terrace/src/branch/main/packages/c/parser.h) - Core terrace parser
      - [document.h](https://git.thederf.com/thederf/Terrace/src/branch/main/packages/c/document.h) - (optional) Convenience functions for parsing of documents

      A simple example program using to read each line from stdin and output parser information, looking for a "title" key:
    CodeBlock c
      // 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;
      }

    Include ./core-api.inc.tce
    Include ./document-api.inc.tce

    Heading 2 Contributing
      class mt-12

Section dark
  Footer
    class w-full