Altlib Reference

README.md

@@ -4,7 +4,9 @@ A system programming language
 
 ## Documentation
 
-[Language Reference](https://htmlpreview.github.io/?https://github.com/ParfenovIgor/alias-c/blob/main/docs/langref.html)
+[Alias Language Reference](https://htmlpreview.github.io/?https://github.com/ParfenovIgor/alias-c/blob/main/docs/langref.html)
+
+[Altlib Reference](https://htmlpreview.github.io/?https://github.com/ParfenovIgor/alias-c/blob/main/docs/altlibref.html)
 
 ## Installation
 

altlib/Makefile

@@ -1,13 +1,23 @@
 ALFLAGS=-i altlib ./
+CFLAGS=-I ../stdlib/include
 
 SRCS_AL := $(wildcard *.al)
 OBJS_AL := $(patsubst %.al, $(BUILD_DIR)/altlib/%.o, $(SRCS_AL))
 
-all: $(OBJS_AL)
+OBJS_STDLIB := $(wildcard $(BUILD_DIR)/stdlib/*.o)
+
+all: $(OBJS_AL) docs
 
 $(BUILD_DIR)/altlib/%.o: %.al make_dir
 	$(BUILD_DIR)/calias -a $(ALFLAGS) $< -o $@
 
+$(BUILD_DIR)/altlib/generate_docs: generate_docs.c
+	gcc $(CFLAGS) $< $(OBJS_STDLIB) -o $@
+
+docs: $(BUILD_DIR)/altlib/generate_docs
+	cat header.html > ../docs/altlibref.html
+	$< $(SRCS_AL) >> ../docs/altlibref.html
+
 make_dir:
 	mkdir -p $(BUILD_DIR)/altlib
 

altlib/algorithm.al

@@ -1,5 +1,11 @@
+//* algorithm
+
+//* min_
+//* Gets two integer values and returns the minimum one.
 func ^.min_(a #I, b #I) -> #I
     if (a < b) a else b
 
+//* max_
+//* Gets two integer values and returns the maximum one.
 func ^.max_(a #I, b #I) -> #I
     if (a < b) b else a

altlib/cassert.al

@@ -1,5 +1,9 @@
 include altlib."posix.al"
 
+//* cassert
+
+//* assert_
+//* Gets one integer value and stop execution with return code `3`, if the value is `0`.
 func ^.assert_(x #I) -> #V {
     eval if (not x) { eval posix_exit(3) }
 }

altlib/generate_docs.c

@@ -0,0 +1,131 @@
+#include <stdio.h>
+#include <posix.h>
+#include <stdbool.h>
+#include <string.h>
+
+const char *sections[1024];
+const char *subsections[1024][1024];
+
+void parse(int section_id, char *filename, int fd) {
+    int file = posix_open(filename, 0, 0);
+    int subsection_id = 1;
+
+    bool global_header = true;
+    bool local_header = true;
+    bool code = false;
+
+    while (true) {
+        char buffer[4096];
+        int len = 0;
+        bool bad = true;
+        int backtick = 0;
+        while (posix_read(file, buffer + len, 1)) {
+            if (buffer[len] == '\n') {
+                bad = false;
+                break;
+            }
+            if (buffer[len] == '<' && code) {
+                _strcpy(buffer + len, "&lt");
+                len += 2;
+            }
+            if (buffer[len] == '>' && code) {
+                _strcpy(buffer + len, "&gt");
+                len += 2;
+            }
+            if (buffer[len] == '`' && !code) {
+                if (backtick == 0) {
+                    _strcpy(buffer + len, "<code>");
+                    len += 5;
+                }
+                else {
+                    _strcpy(buffer + len, "</code>");
+                    len += 6;
+                }
+                backtick = 1 - backtick;
+            }
+            len++;
+        }
+        if (bad) break;
+        buffer[len] = '\0';
+        char *line = buffer;
+
+        if (!_strncmp(line, "//*", 3) && _strlen(line) >= 4) {
+            if (code) {
+                _fputs(fd, "</code></pre>\n");
+                code = false;
+            }
+            line += 4;
+            if (global_header) {
+                _fputsi(fd, "<h2 id=\"", section_id, "\">");
+                _fputs2(fd, line, "</h2>\n");
+                sections[section_id] = _strdup(line);
+                global_header = false;
+            }
+            else if (local_header) {
+                _fputsi(fd, "<h3 id=\"", section_id, ".");
+                _fputi(fd, subsection_id);
+                _fputs3(fd, "\">", line, "</h3>\n");
+                subsections[section_id][subsection_id] = _strdup(line);
+                subsection_id++;
+                local_header = false;
+            }
+            else {
+                _fputs2(fd, line, "\n");
+            }
+        }
+        else {
+            if (!code && _strlen(line) && !global_header) {
+                _fputs(fd, "<pre><code>");
+                code = true;
+                local_header = true;
+            }
+            if (code) {
+                _fputs2(fd, line, "\n");
+            }
+        }
+    }
+    if (code) {
+        _fputs(fd, "</code></pre>\n");
+        code = false;
+    }
+    posix_close(file);
+}
+
+int main(int argc, char **argv) {
+    int fd_contents[2];
+    posix_pipe(fd_contents);
+    for (int i = 1; i < argc; i++) {
+        parse(i, argv[i], fd_contents[1]);
+    }
+    posix_close(fd_contents[1]);
+    char *str = read_file_descriptor(fd_contents[0]);
+    posix_close(fd_contents[0]);
+
+    int out = STDOUT;
+
+    _fputs(out, "<body>\n");
+    _fputs(out, "<header><h1>Altlib Reference</h1></header>\n");
+    _fputs(out, "<div id=\"navigation\"><nav>\n");
+    _fputs(out, "<h2>Table of Contents</h2>\n");
+    _fputs(out, "<ul>");
+    for (int i = 1; i < 1024; i++) {
+        if (!sections[i]) break;
+        _fputsi(out, "<li><a href=\"#", i, "\">");
+        _fputs2(out, sections[i], "</a>\n");
+        _fputs(out, "<ul>\n");
+        for (int j = 1; j < 1024; j++) {
+            if (!subsections[i][j]) break;
+            _fputsi(out, "<li><a href=\"#", i, ".");
+            _fputi(out, j);
+            _fputs3(out, "\">", subsections[i][j], "</a></li>\n");
+        }
+        _fputs(out, "</ul></li>\n");
+    }
+    _fputs(out, "</ul></nav></div>\n");
+
+    _fputs(out, "<div id=\"contents-wrapper\"><main id=\"contents\">\n");
+    _fputs(out, str);
+    _fputs(out, "</main></div></body></html>\n");
+
+    return 0;
+}

altlib/header.html

@@ -0,0 +1,70 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+    <meta http-equip="Context-Type" context="text/html">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="color-scheme" content="light dark">
+    <title>Altlib Reference</title>
+    <style>
+      :root{
+         --nav-width: 26em;
+         --nav-margin-l: 1em;
+      }
+      body{
+        font-family: system-ui, -apple-system, Roboto, "Segoe UI", sans-serif;
+        margin: 0;
+        line-height: 1.5;
+      }
+
+      #contents {
+        max-width: 60em;
+        margin: auto;
+        padding: 0 1em;
+      }
+      #navigation {
+        padding: 0 1em;
+      }
+
+      @media screen and (min-width: 1025px) {
+        header {
+          margin-left: calc(var(--nav-width) + var(--nav-margin-l));
+        }
+        header h1 {
+          margin: auto;
+          max-width: 30em;
+        }
+        #navigation {
+          overflow: auto;
+          width: var(--nav-width);
+          height: 100vh;
+          position: fixed;
+          top:0;
+          left:0;
+          bottom:0;
+          padding: unset;
+          margin-left: var(--nav-margin-l);
+        }
+        #navigation nav ul {
+          padding-left: 1em;
+        }
+        #contents-wrapper {
+          margin-left: calc(var(--nav-width) + var(--nav-margin-l));
+        }
+      }
+
+      code {
+        background: #f8f8f8;
+        border: 1px dotted silver;
+        padding-left: 0.3em;
+        padding-right: 0.3em;
+      }
+      pre > code {
+        display: block;
+        overflow: auto;
+        padding: 0.5em;
+        border: 1px solid #eee;
+        line-height: normal;
+      }
+    </style>
+</head>

altlib/memory.al

@@ -1,2 +1,9 @@
+//* memory
+
+//* _memcpy
+//* Copies the data of length `sz` bytes from `src` pointer to `dest` pointer.
 proto ._memcpy(dest #1I, src #1I, sz #I) -> #1I
+
+//* _memset
+//* Sets the data of length `count` bytes to `dest` pointer with value `ch`. Important: only the lowest byte in `ch` argument is used.
 proto ._memset(dest #1I, ch #I, count #I) -> #1I

altlib/posix.al

@@ -1,3 +1,6 @@
+//* posix
+
+//* todo
 proto .posix_read(fd #I, buffer #1C, count #I) -> #I
 proto .posix_write(fd #I, buffer #1C, count #I) -> #I
 proto .posix_open(filename #1C, flags #I, mode #I) -> #I

altlib/stdio.al

@@ -2,35 +2,54 @@ include altlib."posix.al"
 include altlib."stdlib.al"
 include altlib."string.al"
 
+//* stdio
+
+//* fputs_
+//* Prints the string `str` to the descriptor `fd`. Returns length of the string printed.
 func ^.fputs_(fd #I, str #1C) -> #I
     posix_write(fd, str, strlen_(str))
 
+//* fputs2_
+//* Prints the strings `str1` and `str2` to the descriptor `fd`. Returns length of the string printed.
 func ^.fputs2_(fd #I, str1 #1C, str2 #1C) -> #I
     fputs_(fd, str1) + fputs_(fd, str2)
 
+
+//* fputs3_
+//* Prints the strings `str1`, `str2` and `str3` to the descriptor `fd`. Returns length of the string printed.
 func ^.fputs3_(fd #I, str1 #1C, str2 #1C, str3 #1C) -> #I
     fputs_(fd, str1) + fputs_(fd, str2) + fputs_(fd, str3)
 
+//* fputi_
+//* Prints the integer `n` to the descriptor `fd`. Returns length of the string printed.
 func ^.fputi_(fd #I, n #I) -> #I {
     def str := itoa_(n)
     def res := posix_write(fd, str, strlen_(str))
     eval _free(str as #1I)
     return res
 }
 
+//* fputsi_
+//* Prints the string `str1`, integer `x` and string `str2` to the descriptor `fd`. Returns length of the string printed.
 func ^.fputsi_(fd #I, str1 #1C, x #I, str2 #1C) -> #I
     fputs_(fd, str1) + fputi_(fd, x) + fputs_(fd, str2)
 
+//* puts_
+//* Prints the string `str` to the standard output descriptor. Returns length of the string printed.
 func ^.puts_(str #1C) -> #I {
     def STDOUT := 1
     return fputs_(STDOUT, str) + fputs_(STDOUT, "\n")
 }
 
+//* puti_
+//* Prints the integer `n` to the standard output descriptor. Returns length of the string printed.
 func ^.puti_(n #I) -> #I {
     def STDOUT := 1
     return fputi_(STDOUT, n) + fputs_(STDOUT, "\n")
 }
 
+//* sputs_
+//* Copies the string `src` to string `dst`. Doesn't check for the length. Returns length of the string.
 func ^.sputs_(dst #1C, src #1C) -> #I {
     def i := 0
     return while (src[i] <> '\0') {
@@ -40,6 +59,8 @@ func ^.sputs_(dst #1C, src #1C) -> #I {
     else i
 }
 
+//* sputi_
+//* Prints the integer `n` to the string `dst`. Doesn't check for the length. Returns length of the string printed.
 func ^.sputi_(dst #1C, n #I) -> #I {
     def str := itoa_(n)
     eval sputs_(dst, str)
@@ -48,11 +69,15 @@ func ^.sputi_(dst #1C, n #I) -> #I {
     return res
 }
 
+//* freadc_
+//* Reads and returns one character from the descriptor `fd`.
 func ^.freadc_(fd #I) -> #C {
     def c := '\0'
     return if (posix_read(fd, c&, 1) = 0) '\0' else c
 }
 
+//* freads_
+//* Reads a string from the descriptor `fd` to the string `dst`. Doesn't check for the length. Returns the length of the string. <b>Vulnerable function!</b>
 func ^.freads_(fd #I, dst #1C) -> #I {
     def i := 0
     def dsti := dst as #I
@@ -74,6 +99,8 @@ func ^.freads_(fd #I, dst #1C) -> #I {
     return i
 }
 
+//* freadi_
+//* Reads and returns a non-negative integer from the descriptor `fd`. Doesn't check for overflow.
 func ^.freadi_(fd #I) -> #I {
     def x := 0
     def start := 0
@@ -88,16 +115,22 @@ func ^.freadi_(fd #I) -> #I {
     else 0
 }
 
+//* readc_
+//* Reads and returns a character from the stardard input descriptor.
 func ^.readc_() -> #C {
     def STDIN := 0
     return freadc_(STDIN)
 }
 
+//* reads_
+//* Reads a string character from the stardard input descriptor to `dst`. Returns size of the string. <b>Vulnerable function!</b>
 func ^.reads_(dst #1C) -> #I {
     def STDIN := 0
     return freads_(STDIN, dst)
 }
 
+//* readi_
+//* Reads and returns an integer from the stardard input descriptor.
 func ^.readi_() -> #I {
     def STDIN := 0
     return freadi_(STDIN)

altlib/stdlib.al

@@ -1,3 +1,6 @@
+//* stdlib
+
+//* todo
 proto ._malloc(sz #I) -> #1I
 proto ._free(ptr #1I) -> #V