From caecc28994c13ada71e831927f08e9d2b4483bf7 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 16 Aug 2017 22:57:17 -0400 Subject: [PATCH] Added docs --- runtime.c | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) diff --git a/runtime.c b/runtime.c index b9633e92..164b8ced 100644 --- a/runtime.c +++ b/runtime.c @@ -5680,6 +5680,12 @@ void Cyc_import_shared_object(void *data, object cont, object filename, object e } /** Read */ + +/** + * @brief Helper function to perform a buffered read from an input port + * @param p Input port + * @return Number of characters read, or 0 for EOF/error + */ int read_from_port(port_type *p) { size_t rv = 0; @@ -5700,6 +5706,12 @@ int read_from_port(port_type *p) return rv; } +/** + * @brief Helper function to raise an error from (read) + * @param data Thread data object + * @param p Input port + * @param msg Error message + */ void _read_error(void *data, port_type *p, const char *msg) { char buf[1024]; @@ -5716,6 +5728,10 @@ void _read_error(void *data, port_type *p, const char *msg) return_thread_runnable(data, &vec); } +/** + * @brief Helper function to read past a comment + * @param p Input port + */ void _read_line_comment(port_type *p) { while(1) { @@ -5733,6 +5749,10 @@ void _read_line_comment(port_type *p) } } +/** + * @brief Helper function to read past a block comment + * @param p Input port + */ void _read_multiline_comment(port_type *p) { int maybe_end = 0; @@ -5766,6 +5786,10 @@ void _read_multiline_comment(port_type *p) } } +/** + * @brief Helper function to read past whitespace characters + * @param p Input port + */ void _read_whitespace(port_type *p) { while(1) { @@ -5789,6 +5813,11 @@ void _read_whitespace(port_type *p) } } +/** + * @brief Helper function to add a character to the port's token buffer + * @param p Input port + * @param c Character to add + */ static void _read_add_to_tok_buf(port_type *p, char c) { // FUTURE: more efficient to try and use mem_buf directly?? @@ -5804,6 +5833,12 @@ static void _read_add_to_tok_buf(port_type *p, char c) p->tok_buf[p->tok_end++] = c; } +/** + * @brief Helper function to read a string + * @param data Thread data object + * @param cont Current continuation + * @param p Input port + */ void _read_string(void *data, object cont, port_type *p) { char c; @@ -5892,6 +5927,11 @@ void _read_string(void *data, object cont, port_type *p) } } +/** + * @brief Helper function to read a literal identifier + * @param data Thread data object + * @param p Input port + */ void _read_literal_identifier(void *data, port_type *p) { char c; @@ -5922,6 +5962,11 @@ void _read_literal_identifier(void *data, port_type *p) } } +/** + * @brief Helper function to read a character token + * @param data Thread data object + * @param p Input port + */ void _read_return_character(void *data, port_type *p) { p->tok_buf[p->tok_end] = '\0'; // TODO: what if buffer is full? @@ -5955,6 +6000,11 @@ void _read_return_character(void *data, port_type *p) } } +/** + * @brief Helper function to read a character token + * @param data Thread data object + * @param p Input port + */ void _read_character(void *data, port_type *p) { char c; @@ -5978,6 +6028,9 @@ void _read_character(void *data, port_type *p) } } +/** + * @brief Determine if given string is numeric + */ int _read_is_numeric(const char *tok) { int len = strlen(tok); @@ -5987,12 +6040,23 @@ int _read_is_numeric(const char *tok) ((len > 1) && (tok[1] == '.' || isdigit(tok[1])) && (tok[0] == '-' || tok[0] == '+')))); } +/** + * @brief Helper function, determine if given number is a hex digit + * @param c Character to check + */ int _read_is_hex_digit(char c) { return (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F'); } +/** + * @brief Helper function, return read number. + * @param data Thread data object + * @param p Input port + * @param base Number base + * @param exact Return an exact number if true + */ void _read_return_number(void *data, port_type *p, int base, int exact) { // TODO: validation? @@ -6008,6 +6072,13 @@ void _read_return_number(void *data, port_type *p, int base, int exact) return_thread_runnable(data, &vec); } +/** + * @brief Helper function, read number. + * @param data Thread data object + * @param p Input port + * @param base Number base + * @param exact Return an exact number if true + */ void _read_number(void *data, port_type *p, int base, int exact) { char c; @@ -6039,6 +6110,12 @@ void _read_number(void *data, port_type *p, int base, int exact) } } +/** + * @brief Helper function, return read atom. + * @param data Thread data object + * @param cont Current continuation + * @param p Input port + */ void _read_return_atom(void *data, object cont, port_type *p) { object sym; @@ -6073,7 +6150,7 @@ void _read_return_atom(void *data, object cont, port_type *p) } /** - * Helper macro for Cyc_io_read_token + * @brief Helper macro for Cyc_io_read_token */ #define _read_next_char(data, cont, p) \ if (p->mem_buf_len == 0 || p->mem_buf_len == p->buf_idx) { \ @@ -6084,6 +6161,12 @@ void _read_return_atom(void *data, object cont, port_type *p) } \ } +/** + * @brief Read next token from the input port. + * @param data Thread data object + * @param cont Current continuation + * @param port Input port + */ void Cyc_io_read_token(void *data, object cont, object port) { Cyc_check_port(data, port);