From 20be39132946396d9d93fa936384aab6198d393d Mon Sep 17 00:00:00 2001 From: lohhiiccc <96543753+lohhiiccc@users.noreply.github.com> Date: Mon, 12 Jan 2026 16:22:13 +0100 Subject: [PATCH] docs: add documentation to each .c.md file --- includes/internal/map_internal.h.md | 6 - includes/internal/transpile_internal.h.md | 3 - srcs/cli/cli.c.md | 87 +++++++++++++ srcs/cli/help.c.md | 15 +++ srcs/io/streams.c.md | 36 ++++++ srcs/main.c.md | 33 +++++ srcs/map/core.c.md | 58 +++++++++ srcs/map/io.c.md | 118 +++++++++++++----- srcs/transpile/code.c.md | 25 ++++ srcs/transpile/core.c.md | 70 +++++++++-- srcs/transpile/fence.c.md | 32 +++++ srcs/transpile/state.c.md | 23 ++++ srcs/utils/io/read_line.c.md | 31 +++++ srcs/utils/string/extract_fence_ext.c.md | 28 +++++ srcs/utils/string/extract_file_ext.c.md | 26 ++++ .../utils/string/infer_ext_from_filename.c.md | 22 ++++ srcs/utils/string/starts_with.c.md | 25 ++++ srcs/validator/validator.c.md | 30 +++++ 18 files changed, 618 insertions(+), 50 deletions(-) diff --git a/includes/internal/map_internal.h.md b/includes/internal/map_internal.h.md index 8735b0d..e2d9bba 100644 --- a/includes/internal/map_internal.h.md +++ b/includes/internal/map_internal.h.md @@ -11,11 +11,5 @@ int8_t map_grow(t_map *map); -int8_t -write_header(FILE *f, const char *source, const char *target); - -int8_t -write_ranges(FILE *f, t_map *map); - #endif ``` diff --git a/includes/internal/transpile_internal.h.md b/includes/internal/transpile_internal.h.md index 4bb63a1..4916207 100644 --- a/includes/internal/transpile_internal.h.md +++ b/includes/internal/transpile_internal.h.md @@ -23,9 +23,6 @@ typedef struct s_state void state_init(t_state *s, FILE *in, FILE *out, const char *ext, t_map *map); -int8_t -process_line(t_state *s, char *line); - int8_t handle_fence_open(t_state *s, char *line); diff --git a/srcs/cli/cli.c.md b/srcs/cli/cli.c.md index 54f9dc5..1908983 100644 --- a/srcs/cli/cli.c.md +++ b/srcs/cli/cli.c.md @@ -1,18 +1,39 @@ +# cli.c +The command-line interface (CLI) parser for the c-md transpiler. +Handles parsing command-line arguments and populating the t_args structure. + +--- + + +### Includes ```c #include #include #include #include "cli.h" +``` +--- + +### Structs and Type Definitions + +Function pointer type for option handlers. +```c typedef void (*t_handler)(t_args *, const char *); +``` +Struct to map short options to their handlers. +```c typedef struct s_opt { int8_t short_opt; t_handler handler; } t_opt; +``` +### Forward Declarations +```c static void handle_help(t_args *args, const char *value); static void handle_ext(t_args *args, const char *value); static void handle_input(t_args *args, const char *value); @@ -20,7 +41,12 @@ static void handle_output(t_args *args, const char *value); static void handle_map(t_args *args, const char *value); static t_handler find_handler(int8_t opt); static void init_args(t_args *args); +``` +### Static Variables + +Initialize the mapping of options to their handlers. +```c static const t_opt g_opts[] = { {'h', handle_help}, {'e', handle_ext}, @@ -29,7 +55,11 @@ static const t_opt g_opts[] = { {'m', handle_map}, {0, NULL} }; +``` +Initialize the long options for getopt_long. +See `man getopt` for details. +```c static struct option g_long_opts[] = { {"help", no_argument, NULL, 'h'}, {"ext", required_argument, NULL, 'e'}, @@ -38,7 +68,23 @@ static struct option g_long_opts[] = { {"map", required_argument, NULL, 'm'}, {NULL, 0, NULL, 0} }; +``` +### Function Definitions + +### `cli_parse` +Parses command-line arguments and populates the t_args structure. + +#### Parameters +- `args`: Pointer to the t_args structure to populate. +- `argc`: Argument count. +- `argv`: argv. + +#### Return Value +Returns 0 on success, or -1 on failure. + +#### Implementation +```c int8_t cli_parse(t_args *args, int32_t argc, char **argv) { @@ -55,7 +101,16 @@ cli_parse(t_args *args, int32_t argc, char **argv) } return (0); } +``` +### `init_args` +Initializes the t_args structure with default values. + +#### Parameters +- `args`: Pointer to the t_args structure to initialize. + +#### Implementation +```c static void init_args(t_args *args) { @@ -65,7 +120,19 @@ init_args(t_args *args) args->map_path = NULL; args->show_help = 0; } +``` +### `find_handler` +Finds the handler function for a given option. + +#### Parameters +- `opt`: The short option character. + +#### Return Value +Returns the corresponding handler function, or NULL if not found. + +#### Implementation +```c static t_handler find_handler(int8_t opt) { @@ -80,32 +147,52 @@ find_handler(int8_t opt) } return (NULL); } +``` +### `handle_help` +Sets the show_help flag in t_args. +```c static void handle_help(t_args *args, const char *value) { (void)value; args->show_help = 1; } +``` +### `handle_ext` +Sets the file extension in t_args. +```c static void handle_ext(t_args *args, const char *value) { args->ext = value; } +``` +### `handle_input` +Sets the input file path in t_args. +```c static void handle_input(t_args *args, const char *value) { args->input = value; } +``` +### `handle_output` +Sets the output file path in t_args. +```c static void handle_output(t_args *args, const char *value) { args->output = value; } +``` +### `handle_map` +Sets the mapping file path in t_args. +```c static void handle_map(t_args *args, const char *value) { diff --git a/srcs/cli/help.c.md b/srcs/cli/help.c.md index 6cd6029..c5332db 100644 --- a/srcs/cli/help.c.md +++ b/srcs/cli/help.c.md @@ -1,8 +1,23 @@ +# help.c + +--- + +## Includes ```c #include #include "cli.h" +``` +## Function Descriptions +### `cli_print_help` +Prints the help message for the command-line interface. + +#### Parameters +- `progname`: Name of the program. + +#### Implementation +```c void cli_print_help(const char *progname) { diff --git a/srcs/io/streams.c.md b/srcs/io/streams.c.md index bf20c01..7c010e1 100644 --- a/srcs/io/streams.c.md +++ b/srcs/io/streams.c.md @@ -1,8 +1,35 @@ +# streams.c +Funtions for handling input and output streams. + +--- + +## Includes ```c #include #include "io.h" +``` +--- + +## Function Descriptions + +### `io_open` +Opens input and output streams based on provided file paths. +if input_path is NULL, stdin is used. +if output_path is NULL, stdout is used. + +#### Parameters +- `io`: Pointer to the t_io structure to hold the opened streams. +- `input_path`: Path to the input file, or NULL for stdin. +- `output_path`: Path to the output file, or NULL for stdout. + +#### Return Value +Returns 0 on success, or 1 on failure. +The caller is responsible for closing the streams using `io_close`. + +#### Implementation +```c int8_t io_open(t_io *io, const char *input_path, const char *output_path) { @@ -22,7 +49,16 @@ io_open(t_io *io, const char *input_path, const char *output_path) } return (0); } +``` +### `io_close` +Closes the input and output streams if they are not stdin or stdout. + +#### Parameters +- `io`: Pointer to the t_io structure containing the streams to close. + +#### Implementation +```c void io_close(t_io *io) { diff --git a/srcs/main.c.md b/srcs/main.c.md index e4eb64f..1a1d2ec 100644 --- a/srcs/main.c.md +++ b/srcs/main.c.md @@ -1,3 +1,10 @@ +# main.c + +Entry point of the c-md transpiler. + +Parse command-line arguments, validate them, and run the transpilation process. + +## Includes ```c #include #include @@ -7,10 +14,20 @@ #include "transpile.h" #include "map.h" #include "io.h" +``` +## Forward Declarations + +```c static int8_t run(t_args *args); static void print_error(int8_t code, const char *progname); +``` +## Main Function + +Program entry point: parse arguments, validate, and run transpilation. + +```c int main(int argc, char **argv) { @@ -35,7 +52,17 @@ main(int argc, char **argv) } return (run(&args)); } +``` +## Print Error Function + +print_error: Print error messages based on validation code. + +error codes: +1. Missing -e when reading from stdin +2. Missing -e when filename does not imply extension + +```c static void print_error(int8_t code, const char *progname) { @@ -45,7 +72,13 @@ print_error(int8_t code, const char *progname) fprintf(stderr, "Error: -e required (cannot infer from filename)\n"); cli_print_help(progname); } +``` +## Run Function + +Run the transpilation process with given arguments. + +```c static int8_t run(t_args *args) { diff --git a/srcs/map/core.c.md b/srcs/map/core.c.md index 58e2f31..16e7485 100644 --- a/srcs/map/core.c.md +++ b/srcs/map/core.c.md @@ -1,9 +1,31 @@ +# core.c +Core functions of the map feature. +Handles initialization, addition, freeing, and growing of the map structure. + +--- + +## Includes ```c #include #include "map.h" #include "internal/map_internal.h" +``` +--- + +## Function Descriptions + +### `map_init` +Initializes the map structure. +Every map structure must be initialized before use. +They also must be freed with `map_free` when no longer needed. + +#### Parameters +- `map`: Pointer to the map structure to initialize. + +##### Implementation +```c void map_init(t_map *map) { @@ -11,7 +33,20 @@ map_init(t_map *map) map->count = 0; map->capacity = 0; } +``` +### `map_add` +Adds a new range to the map structure. + +#### Parameters +- `map`: Pointer to the map structure. +- `src_start`: Start of the source range. +- `src_end`: End of the source range. +- `dst_start`: Start of the destination range. +- `dst_end`: End of the destination range. + +#### Implementation +```c void map_add(t_map *map, uint32_t src_start, uint32_t src_end, uint32_t dst_start, uint32_t dst_end) @@ -30,7 +65,16 @@ map_add(t_map *map, uint32_t src_start, uint32_t src_end, range->dst_end = dst_end; map->count++; } +``` +### `map_free` +Frees the resources allocated with the map structure. + +#### Parameters +- `map`: Pointer to the map structure to free. + +#### Implementation +```c void map_free(t_map *map) { @@ -39,7 +83,21 @@ map_free(t_map *map) map->count = 0; map->capacity = 0; } +``` +### `map_grow` +Grows the capacity of the map structure. +Multiplies the current capacity by 2, or sets it to an initial value if it's +zero. + +#### Parameters +- `map`: Pointer to the map structure to grow. + +#### Return Value +Returns 0 on success, or 1 on memory allocation failure. + +#### Implementation +```c int8_t map_grow(t_map *map) { diff --git a/srcs/map/io.c.md b/srcs/map/io.c.md index 984f40e..472cd80 100644 --- a/srcs/map/io.c.md +++ b/srcs/map/io.c.md @@ -1,41 +1,42 @@ +# io.c +Input/output functions for c-md mapping files. + +--- + +## Includes ```c #include #include "map.h" #include "internal/map_internal.h" +``` -int8_t -write_header(FILE *f, const char *source, const char *target) -{ - if (0 > fprintf(f, "C-MD MAP v1\n")) - return (1); - if (0 > fprintf(f, "source: %s\n", source)) - return (1); - if (0 > fprintf(f, "target: %s\n", target)) - return (1); - if (0 > fprintf(f, "---\n")) - return (1); - return (0); -} +--- -int8_t -write_ranges(FILE *f, t_map *map) -{ - size_t i; - t_range *r; +## Forward Declarations +```c +static int8_t write_header(FILE *f, const char *source, const char *target); +static int8_t write_ranges(FILE *f, t_map *map); +``` - i = 0; - while (i < map->count) - { - r = &map->ranges[i]; - if (0 > fprintf(f, "%u-%u:%u-%u\n", - r->src_start, r->src_end, r->dst_start, r->dst_end)) - return (1); - i++; - } - return (0); -} +--- +## Function Descriptions + +### `map_write` +Writes a c-md mapping file to the specified path. + +#### Parameters +- `map`: Pointer to the mapping structure. +- `path`: Pointer to the output file path string. +- `source`: Pointer to the source file name string. +- `target`: Pointer to the target file name string. + +#### Return Value +Return 0 on success, or 1 on failure. + +##### Implementation +```c int8_t map_write(t_map *map, const char *path, const char *source, const char *target) { @@ -55,3 +56,62 @@ map_write(t_map *map, const char *path, const char *source, const char *target) return (ret); } ``` + +### `write_header` +Writes the header of a c-md mapping file. (v1 format) + +#### Parameters +- `f`: Pointer to the output file. +- `source`: Pointer to the source file name string. +- `target`: Pointer to the target file name string. + +#### Return Value +Return 0 on success, or 1 on failure. + +#### Implementation +```c +int8_t +write_header(FILE *f, const char *source, const char *target) +{ + if (0 > fprintf(f, "C-MD MAP v1\n")) + return (1); + if (0 > fprintf(f, "source: %s\n", source)) + return (1); + if (0 > fprintf(f, "target: %s\n", target)) + return (1); + if (0 > fprintf(f, "---\n")) + return (1); + return (0); +} +``` + +### `write_ranges` +Writes the ranges of a c-md mapping file. + +#### Parameters +- `f`: Pointer to the output file. +- `map`: Pointer to the mapping structure. + +#### Return Value +Return 0 on success, or 1 on failure. + +#### Implementation +```c +int8_t +write_ranges(FILE *f, t_map *map) +{ + size_t i; + t_range *r; + + i = 0; + while (i < map->count) + { + r = &map->ranges[i]; + if (0 > fprintf(f, "%u-%u:%u-%u\n", + r->src_start, r->src_end, r->dst_start, r->dst_end)) + return (1); + i++; + } + return (0); +} +``` diff --git a/srcs/transpile/code.c.md b/srcs/transpile/code.c.md index e4d50f6..712e8e4 100644 --- a/srcs/transpile/code.c.md +++ b/srcs/transpile/code.c.md @@ -1,8 +1,33 @@ +# code.c +Handle a single line of code by writing it to the output file and updating the +state. + +--- + +## Includes ```c #include #include "internal/transpile_internal.h" +``` +--- + +## Function Descriptions + +### `handle_code_line` +Handle a single line of code by writing it to the output file and updating the +state. + +#### Parameters +- `s`: Pointer to the current state structure. +- `line`: Pointer to the line of code to be handled. + +#### Return Value +Return 0 on success, or 1 on failure. + +#### Implementation +```c int8_t handle_code_line(t_state *s, char *line) { diff --git a/srcs/transpile/core.c.md b/srcs/transpile/core.c.md index 99acea3..30000c1 100644 --- a/srcs/transpile/core.c.md +++ b/srcs/transpile/core.c.md @@ -1,23 +1,43 @@ +# core.c +Core funtion of the transpiler. +Handles reading lines and processing them according to the current state. + +--- + +## Includes ```c #include #include "transpile.h" #include "internal/transpile_internal.h" #include "utils.h" +``` -int8_t -process_line(t_state *s, char *line) -{ - s->src_line++; - if (0 == s->in_block && starts_with(line, "```")) - return (handle_fence_open(s, line)); - if (1 == s->in_block && starts_with(line, "```")) - return (handle_fence_close(s)); - if (1 == s->in_block) - return (handle_code_line(s, line)); - return (0); -} +--- +## Forward Declarations + +```c +static int8_t process_line(t_state *s, char *line); +``` + +## Function Descriptions + +### `transpile` +Transpiles input from a file to an output file based on the specified extension +and mapping. + +#### Parameters +- `in`: Pointer to the input file. +- `out`: Pointer to the output file. +- `ext`: Pointer to the file extension string. +- `map`: Pointer to the mapping structure. + +#### Return Value +Return 0 on success, or a non-zero error code on failure. + +#### Implementation +```c int8_t transpile(FILE *in, FILE *out, const char *ext, t_map *map) { @@ -38,3 +58,29 @@ transpile(FILE *in, FILE *out, const char *ext, t_map *map) return (ret); } ``` + +### `process_line` +Processes a single line of input based on the current state. + +#### Parameters +- `s`: Pointer to the current state structure. +- `line`: Pointer to the line of text to process. + +#### Return Value +Return 0 on success, or a non-zero error code on failure. + +#### Implementation +```c +static int8_t +process_line(t_state *s, char *line) +{ + s->src_line++; + if (0 == s->in_block && starts_with(line, "```")) + return (handle_fence_open(s, line)); + if (1 == s->in_block && starts_with(line, "```")) + return (handle_fence_close(s)); + if (1 == s->in_block) + return (handle_code_line(s, line)); + return (0); +} + diff --git a/srcs/transpile/fence.c.md b/srcs/transpile/fence.c.md index c7d42f6..e0c6143 100644 --- a/srcs/transpile/fence.c.md +++ b/srcs/transpile/fence.c.md @@ -1,3 +1,9 @@ +# fence.c +Handles opening and closing of fenced code blocks in the transpilation process. + +--- + +## Includes ```c #include #include @@ -5,7 +11,24 @@ #include "internal/transpile_internal.h" #include "utils.h" +``` +--- + +## Function Descriptions + +### `handle_fence_open` +Handles the opening of a fenced code block. + +#### Parameters +- `s`: Pointer to the current transpilation state. +- `line`: Pointer to the current line being processed. + +#### Return Value +Returns `0` on success, `1` on error. + +#### Implementation +```c int8_t handle_fence_open(t_state *s, char *line) { @@ -32,7 +55,16 @@ handle_fence_open(t_state *s, char *line) s->block_dst_start = s->dst_line + 1; return (0); } +``` +### `handle_fence_close` +Handles the closing of a fenced code block. + +#### Parameters +- `s`: Pointer to the current transpilation state. + +#### Implementation +```c int8_t handle_fence_close(t_state *s) { diff --git a/srcs/transpile/state.c.md b/srcs/transpile/state.c.md index daaa767..0f77117 100644 --- a/srcs/transpile/state.c.md +++ b/srcs/transpile/state.c.md @@ -1,6 +1,29 @@ +# state.c + +Initialize the transpilation state structure. + +## Includes ```c #include "internal/transpile_internal.h" +``` +--- + +## Function Description +### `state_init` + +Initialize the transpilation state structure. + +#### Parameters +- `s`: Pointer to the state structure to initialize. +- `in`: Input file pointer. +- `out`: Output file pointer. +- `ext`: Pointer to the extracted code fence extension string. +- `map`: Pointer to the mapping structure. + +#### Implementation + +```c void state_init(t_state *s, FILE *in, FILE *out, const char *ext, t_map *map) { diff --git a/srcs/utils/io/read_line.c.md b/srcs/utils/io/read_line.c.md index 2e3d66e..454e341 100644 --- a/srcs/utils/io/read_line.c.md +++ b/srcs/utils/io/read_line.c.md @@ -1,3 +1,12 @@ +# read_line.c + +Get a line from a file. +depends on POSIX getline + +--- + +## Includes + ```c #define _POSIX_C_SOURCE 200809L @@ -5,7 +14,29 @@ #include #include "utils.h" +``` +--- + +## Function Description + +### `read_line` + +Get a line from a file. + +#### Parameter +- `f`: Pointer to a `FILE` object representing the input file. + +#### Return Value + +Returns a pointer to the read line (dynamically allocated) or `NULL` on failure +or end of file. + +Return value must be freed by the caller. + +#### Implementation + +```c char * read_line(FILE *f) { diff --git a/srcs/utils/string/extract_fence_ext.c.md b/srcs/utils/string/extract_fence_ext.c.md index 072cdbc..544af5c 100644 --- a/srcs/utils/string/extract_fence_ext.c.md +++ b/srcs/utils/string/extract_fence_ext.c.md @@ -1,10 +1,38 @@ +# extract_fence_ext.c + +Extract the extension from a markdown code fence. + +--- + +## Includes ```c #include #include #include #include "utils.h" +``` +--- + +## Function Description + +### `extract_fence_ext` +Extracts the extension from a markdown code fence string. + +#### Parameter +- `fence`: Pointer to a null-terminated string representing the code fence. + +#### Return Value + +Returns a dynamically allocated string containing the extracted extension, or +`NULL` if no extension is found or if the input is not a valid code fence. + +Return value must be freed by the caller. + +#### Implementation + +```c char * extract_fence_ext(const char *fence) { diff --git a/srcs/utils/string/extract_file_ext.c.md b/srcs/utils/string/extract_file_ext.c.md index 2aa7e4a..3ea7724 100644 --- a/srcs/utils/string/extract_file_ext.c.md +++ b/srcs/utils/string/extract_file_ext.c.md @@ -1,8 +1,34 @@ +# extract_file_ext.c + +Get the file extension from a given file path. + +--- + +## Includes ```c #include #include "utils.h" +``` +--- + +## Function Description + +### `extract_file_ext` +Get the file extension from a given file path. + +#### Parameter +- `path`: The file path string. + +#### Return Value + +Returns a pointer to the file extension within the path string, or `NULL` if +no extension is found. + +#### Implementation + +```c const char * extract_file_ext(const char *path) { diff --git a/srcs/utils/string/infer_ext_from_filename.c.md b/srcs/utils/string/infer_ext_from_filename.c.md index f002a47..39d5dc8 100644 --- a/srcs/utils/string/infer_ext_from_filename.c.md +++ b/srcs/utils/string/infer_ext_from_filename.c.md @@ -1,8 +1,30 @@ +# infer_ext_from_filename.c +Infer file extension from filename ending with .md + +--- + +## Includes ```c #include #include "utils.h" +``` +--- + +## Function Descriptions + +### `infer_ext_from_filename` +Infer the file extension from a filename that ends with `.md`. + +#### Parameters +- `path`: Pointer to the filename string. + +#### Return Value +Returns a pointer to a static buffer containing the inferred extension, or +`NULL` if no valid + +```c const char * infer_ext_from_filename(const char *path) { diff --git a/srcs/utils/string/starts_with.c.md b/srcs/utils/string/starts_with.c.md index 0085224..d938cc7 100644 --- a/srcs/utils/string/starts_with.c.md +++ b/srcs/utils/string/starts_with.c.md @@ -1,9 +1,34 @@ +# starts_with.c + +Checks if a string starts with a given prefix. + +--- + +## Includes ```c #include #include #include "utils.h" +``` +--- +## Function Description + +### `starts_with` + +Checks if the string `str` starts with the substring `prefix`. + +#### Parameters +- `str`: The main string to check. +- `prefix`: The prefix to look for at the start of `str`. + +#### Return Value +- Returns `1` (true) if `str` starts with `prefix`. +- Returns `0` (false) otherwise. + +#### Implementation +```c int8_t starts_with(const char *str, const char *prefix) { diff --git a/srcs/validator/validator.c.md b/srcs/validator/validator.c.md index 5d4746b..2507ee5 100644 --- a/srcs/validator/validator.c.md +++ b/srcs/validator/validator.c.md @@ -1,9 +1,39 @@ +# validator.c + +Validate command-line arguments. + +--- + +## Includes ```c #include #include "validator.h" #include "utils.h" +``` +--- + +## Function Description + +### `validator_validate_args` + +Checks and validates the content of the `t_args` structure, ensuring required +file input and extension arguments are consistent. + +#### Parameter +- `args`: Pointer to a `t_args` structure containing command-line arguments. + +#### Return Codes + +| Code | Meaning | +|------|-----------------------------------------------------------------| +| 0 | Arguments are valid | +| 1 | Both input file and extension are missing | +| 2 | Extension is missing and cannot be inferred from input filename | + +#### Implementation +```c int8_t validator_validate_args(t_args *args) {