reader.h

Go to the documentation of this file.

/* -*- C -*-
 * Serene programming language
 * Copyright (C) 2019-2026 Sameer Rahmani <lxsameer@lxsameer.com>
 *
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#pragma once
 
/** @file
A simple sexp reader to be used with textual IR.
 
The IR types we use for the runtime have a lispy representation, and this
reader will parse symbolic expressions in a basic form and different layers
of IR can use this reader and transform the symbolic expressions to
a format that they like.
 
I wrote this parser mostly to act as an inefficient way to parse different
layers of IR without needing to have multiple parsers. Long in the future
when we have everything in place, I should write efficient parsers for only
the crucial layers of IR and avoid this generic one.
*/
 
#include <stdint.h>
 
#include "serene/rt/impl/array_list.h"
#include "serene/rt/source_manager.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "serene/rt/errors.h"
 
typedef struct srn_sexp_node_t srn_sexp_node_t;
typedef struct srn_src_location_t srn_src_location_t;
typedef struct srn_sexp_parser_t srn_sexp_parser_t;
typedef struct array_list_t array_list_t;
 
typedef enum srn_sexp_node_type_e : uint8_t {
  SRN_SEXP_ATOM,
  SRN_SEXP_CONS,
  SRN_SEXP_LIST,
  SRN_SEXP_NUM,
  SRN_SEXP_SEQ, // An array list of expressions
  SRN_SEXP_STR,
} srn_sexp_node_type_e;
 
// -----------------------------------------------------------------------------
// Atoms
// -----------------------------------------------------------------------------
typedef struct srn_sexp_atom_t {
  char *name;
} srn_sexp_atom_t;
 
[[gnu::nonnull(1, 2)]]
srn_sexp_node_t *srn_sexp_make_atom(srn_context_t *ctx, const char *name);
 
// -----------------------------------------------------------------------------
// String
// -----------------------------------------------------------------------------
typedef struct srn_sexp_str_t {
  char *data;
} srn_sexp_str_t;
 
[[gnu::nonnull(1)]]
srn_sexp_node_t *srn_sexp_make_str(srn_context_t *ctx, const char *data);
 
// -----------------------------------------------------------------------------
// Number
// -----------------------------------------------------------------------------
/// A number literal, kept as the raw text it was written with (e.g. "42", "-3.14",
/// "+1e10"). The reader only recognises the shape of a number, it does not parse it
/// into an int/float value or fix its precision, that is a later phase's job.
typedef struct srn_sexp_num_t {
  char *text;
} srn_sexp_num_t;
 
[[gnu::nonnull(1, 2)]]
srn_sexp_node_t *srn_sexp_make_num(srn_context_t *ctx, const char *text);
 
// -----------------------------------------------------------------------------
// Cons
// -----------------------------------------------------------------------------
typedef struct srn_sexp_cons_t {
  srn_sexp_node_t *head;
  srn_sexp_node_t *tail;
} srn_sexp_cons_t;
 
[[gnu::nonnull(1)]]
srn_sexp_node_t *
srn_sexp_make_cons(srn_context_t *ctx, srn_sexp_node_t *head, srn_sexp_node_t *tail);
 
// -----------------------------------------------------------------------------
// List
// -----------------------------------------------------------------------------
typedef struct srn_sexp_list_t {
  size_t len;
  srn_sexp_node_t *head;
} srn_sexp_list_t;
 
[[gnu::nonnull(1)]]
srn_sexp_node_t *srn_sexp_make_list(srn_context_t *ctx);
 
// -----------------------------------------------------------------------------
// Node
// -----------------------------------------------------------------------------
typedef struct srn_sexp_node_t {
  srn_sexp_node_type_e type;
  srn_metadata_t *metadata;
 
  union {
    srn_sexp_atom_t *atom;
    srn_sexp_list_t *list;
    srn_sexp_cons_t *cons;
    array_list_t *seq;
    srn_sexp_str_t *string;
    srn_sexp_num_t *num;
  } as;
} srn_sexp_node_t;
 
[[gnu::nonnull(1)]]
srn_sexp_node_t *srn_sexp_make_node(srn_context_t *ctx, srn_sexp_node_type_e type);
 
// -----------------------------------------------------------------------------
// Parser and tree
// -----------------------------------------------------------------------------
typedef struct srn_sexp_parser_t {
  srn_context_t *ctx;
  /// We store whatever the caller passes as reading context to pass it back
  /// later on in the parsed tree.
  void *reading_context;
 
  const srn_sm_buffer_id_t buffer_id;
  const unsigned char *buffer;
  size_t len;
 
  // This should be the same size as the srn_src_location_t.offset
  uint32_t pos;
} srn_sexp_parser_t;
 
typedef struct srn_sexp_tree_t {
  ERROR_HEADER;
  // Root nodes of the tree. Each IR has a dedicated root node
  array_list_t exprs;
  // The reading context that handed to the parser for this read.
  void *reading_context;
} srn_sexp_tree_t;
 
/**
 * Read the symbolic expressions from a buffer. `reading_context` is a piece of data
 * that the reader might provide as an identity or a piece of data that gives meaning
 * to the result. For example a namespace key.
 */
[[gnu::nonnull(1, 3)]]
srn_sexp_tree_t *
srn_sexp_read_from_string(srn_context_t *ctx, void *reading_context, const char *buf);
 
/**
 * Read the symbolic expressions from a file. `reading_context` is a piece of data
 * that the reader might provide as an identity or a piece of data that gives meaning
 * to the result. For example a namespace key.
 */
[[gnu::nonnull(1, 3)]]
srn_sexp_tree_t *
srn_sexp_read_from_file(srn_context_t *ctx, void *reading_context, const char *path);
 
// -----------------------------------------------------------------------------
// Private API, exposed for testing
// -----------------------------------------------------------------------------
typedef struct reader_fiber_arg_t {
  srn_sexp_parser_t *parser;
  srn_sexp_tree_t *tree;
} reader_fiber_arg_t;
 
srn_sexp_node_t *read_expr(srn_sexp_parser_t *parser, srn_error_t **err);
 
srn_fiber_result_t read_from_buffer(srn_context_t *ctx, void *arg);
 
/**
 * Convert the given `sexp` to a string for debugging purposes. The string will
 * contain metadata info as well.
 */
[[gnu::nonnull(1, 2)]]
const char *srn_sexp_to_debug_string(srn_context_t *ctx, srn_sexp_tree_t *tree);
 
#ifdef __cplusplus
}
#endif