feat: add cli flag to generate langauge reference document

Author: nos1dot618

README.md

@@ -112,9 +112,13 @@ lbd [options]
 -f, --file <filepath>   Specify input source filepath to run
 -h, --help              Show this help message and exit
 -d, --debug             Enable debug mode
--r, --repl              Run in interactive REPL mode
+-r, --repl              Run in interactive REPL node
+--docs                  Generate language-reference-document
 ```
 
+> Generate the language-reference-document by using the `--docs` flag, and use it as the source of truth for
+> native-function-signatures.
+
 ## Editor Plugins
 
 1. [GNU Emacs](./editor-plugins/emacs)
@@ -126,4 +130,4 @@ lbd [options]
 - TODO: Fix tests output in README.
 - TODO: Step debug kind of functionality in REPL. Inside REPL, while loading a file, load one expression at a time and
   provide user with some feedback and actions to perform.
-- TODO: Make a pre-commit-hook which does not allow to push to master, if the tests are failing.
+- TODO: Make a pre-commit-hook which does not allow to push to master, if the tests are failing. Additionally, test whether the `docs/SIGNATURE.txt` is up-to-date or not.

docs/SIGNATURE.md

@@ -0,0 +1,20 @@
+add: Float -> Float -> Float
+sub: Float -> Float -> Float
+mul: Float -> Float -> Float
+cmp: Float -> Float -> Float
+null: Float -> Any -> Any -> Any
+parseFloat: String -> Float
+list: Any -> []
+listSize: [] -> Float
+listGet: [] -> Float -> Any
+listRemove: [] -> Float -> Any
+listAppend: [] -> Any -> Void
+map: (Any -> Any) -> [] -> []
+transpose: [] -> []
+sort: [] -> []
+zip: [] -> []
+foldRight: (Any -> Any -> Any) -> Any -> [] -> Any
+print: Any -> Void
+slurpFile: String -> String
+lines: String -> []
+split: String -> String -> []

docs/SIGNATURE.txt

@@ -10,9 +10,10 @@ namespace cmd {
         bool showHelp = false;
         bool repl = false;
         bool debug = false;
+        bool generateDocs = false;
     };
 
-    void printHelp(std::ostream &os, const std::string &programName);
+    void printHelp(std::ostream &outputStream, const std::string &programName);
 
     Options parseArguments(int argc, char **argv, const std::string &programName);
 }

include/lbd/cmd.h

@@ -0,0 +1,7 @@
+#pragma once
+
+#include <iostream>
+
+namespace docs {
+    void dumpDocs(std::ostream &outputStream);
+}

include/lbd/docs.h

@@ -1,9 +1,9 @@
 #pragma once
 
 #include <optional>
+#include <lbd/exceptions.h>
 #include <lbd/frontend/location.h>
 #include <lbd/utils/terminal.h>
-#include <lbd/exceptions.h>
 
 namespace logs {
     struct Logger {

include/lbd/logs.h

@@ -1,13 +1,14 @@
 #include <lbd/cmd.h>
 
 namespace cmd {
-    void printHelp(std::ostream &os, const std::string &programName) {
-        os << "usage: " << programName << " [options]\n\n"
+    void printHelp(std::ostream &outputStream, const std::string &programName) {
+        outputStream << "usage: " << programName << " [options]\n\n"
                 << "options:\n"
                 << "  -f, --file <filepath>   Specify input source filepath to run\n"
                 << "  -h, --help              Show this help message and exit\n"
                 << "  -d, --debug             Enable debug mode\n"
-                << "  -r, --repl              Run in interactive REPL node" << std::endl;
+                << "  -r, --repl              Run in interactive REPL node\n"
+                << "  --docs                  Generate language-reference-document" << std::endl;
     }
 
     Options parseArguments(const int argc, char **argv, const std::string &programName) {
@@ -27,6 +28,8 @@ namespace cmd {
                 opts.debug = true;
             } else if (arg == "-r" || arg == "--repl") {
                 opts.repl = true;
+            } else if (arg == "--docs") {
+                opts.generateDocs = true;
             } else {
                 std::cerr << "unknown option: " << arg << "\n";
                 printHelp(std::cerr, programName);

src/cmd.cpp

@@ -0,0 +1,14 @@
+#include <lbd/docs.h>
+#include <lbd/runtime/builtins.h>
+#include <lbd/runtime/interpreter.h>
+
+namespace docs {
+    void dumpDocs(std::ostream &outputStream) {
+        // TODO: Use colors if in tty, show module, description, usages/examples.
+        //       Maybe add a flag to rather generate an html-document.
+        for (runtime::NativeFunction nativeFunction: runtime::builtins::getBuiltins()) {
+            std::string signature = nativeFunction.getSignature()->toString();
+            outputStream << nativeFunction.getName() << ": " << signature << std::endl;
+        }
+    }
+}

src/docs.cpp

@@ -1,20 +1,25 @@
 #include <iostream>
+#include <string>
+#include <vector>
+#include <lbd/cmd.h>
+#include <lbd/docs.h>
+#include <lbd/repl.h>
 #include <lbd/frontend/lexer.h>
 #include <lbd/frontend/parser.h>
 #include <lbd/runtime/interpreter.h>
-#include <lbd/cmd.h>
-#include <lbd/repl.h>
-#include <string>
-#include <vector>
 
 const std::string &programName = "lbd";
 
 int main(const int argc, char **argv) {
-    const auto &[filepath, show_help, repl, debug] = cmd::parseArguments(argc, argv, programName);
+    const auto &[filepath, show_help, repl, debug, generateDocs] = cmd::parseArguments(argc, argv, programName);
     if (show_help) {
         cmd::printHelp(std::cout, argv[0]);
         return EXIT_SUCCESS;
     }
+    if (generateDocs) {
+        docs::dumpDocs(std::cout);
+        return EXIT_SUCCESS;
+    }
     if (repl) {
         repl::loop(debug);
     } else {

src/main.cpp

@@ -177,10 +177,14 @@ namespace runtime::type {
                 outputStringStream << argumentType->toString() << " -> ";
             }
         }
-        if (returnType->isCallable()) {
-            outputStringStream << "(" << returnType->toString() << ")";
+        if (returnType) {
+            if (returnType->isCallable()) {
+                outputStringStream << "(" << returnType->toString() << ")";
+            } else {
+                outputStringStream << returnType->toString();
+            }
         } else {
-            outputStringStream << returnType->toString();
+            outputStringStream << "Void";
         }
         return outputStringStream.str();
     }