Add prologue documentation.

takev · takev · commit b850577ba751 · 2025-06-04T16:14:16.000+02:00
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -54,6 +54,7 @@ add_library(hic_objects OBJECT
     "${CMAKE_CURRENT_SOURCE_DIR}/src/tokenizer_parse_operator.cpp"
     "${CMAKE_CURRENT_SOURCE_DIR}/src/tokenizer_parse_positional_argument.cpp"
     "${CMAKE_CURRENT_SOURCE_DIR}/src/tokenizer_parse_string.cpp"
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/tokenizer_parse_version.cpp"
     "${CMAKE_CURRENT_SOURCE_DIR}/src/utf8.cpp"
     "${CMAKE_CURRENT_SOURCE_DIR}/src/utf8.hpp"
 )
diff --git a/doc/language/syntax/application_declaration.md b/doc/language/syntax/application_declaration.md
@@ -0,0 +1,17 @@
+# module-declaration
+
+## Syntax
+
+`application` [_string_literal_](string_literal.md) __(__ `if` [_compile_condition_](compile_condition.md) __|__ `fallback` __)?__
+
+## Semantics
+
+Each file must have a `application` (or [`module`](module_declaration.md))
+declaration to give the file a executable name.
+
+The optional compile-condition is evaluated during the prologue-scan phase of compilation,
+this checks if the file should be compiled.
+
+Multiple files may have the same module-name, only if the conditional compilation is
+mutually exclusive. If a file has a `fallback` condition, it will be used if no other
+file with the same module-name is compiled.
diff --git a/doc/language/syntax/compile_condition.md b/doc/language/syntax/compile_condition.md
@@ -0,0 +1,56 @@
+# compile-condition
+
+## Syntax
+
+'`(` _compile_condition_ `)` __|__
+[_identifier_](identifier.md) __|__
+[_integer_literal_](integer_literal.md) __|__
+[_version_literal_](version_literal.md) __|__
+_compile_condition_ `<` _compile_condition_ __|__
+_compile_condition_ `>` _compile_condition_ __|__
+_compile_condition_ `<=` _compile_condition_ __|__
+_compile_condition_ `>=` _compile_condition_ __|__
+_compile_condition_ `==` _compile_condition_ __|__
+_compile_condition_ `!=` _compile_condition_ __|__
+_compile_condition_ `and` _compile_condition_ __|__
+_compile_condition_ `or` _compile_condition_ __|__
+`not` _compile_condition_
+
+## Semantics
+
+If a identifier is a `false`, then any comparison with a version-literal or integer-literal is `false` as well.
+
+Build phases:
+ - **download**: Download data before generating code.
+ - **generate**: Generate code before building.
+ - **build**: Build normal applications.
+
+Build type:
+ - **debug**: Application is build for debugging.
+ - **release**: Application is build for release.
+
+Operating systems:
+ - **windows**: (version) Build for Microsoft Windows platform. Version of Windows
+ - **macos**: (version) Build for Apple MacOS platform. Version of MacOS.
+ - **linux**: (version) Build for Linux platform. Version of Linux kernel.
+ - **ios**: (version) Mobile version of `macos`, which is also set.
+ - **android**: (version) Mobile version of `linux`, which is also set.
+
+Platform:
+ - **desktop**: 
+ - **phone**: 
+ - **watch**: 
+ - **pad**: 
+
+The CPU:
+ - **x86**: Intel x86 CPU. Integer is register size.
+ - **x86_32**
+ - **x86_64**
+ - **x86_64v1**
+ - **x86_64v2**
+ - **x86_64v3**
+ - **x86_64v4**
+ - **x86_AVX**: Intel x86 AVX feature.
+ - **arm**: Arm CPU. Integer is register size.
+ - **arm_32**
+ - **arm_64**
diff --git a/doc/language/syntax/file.md b/doc/language/syntax/file.md
@@ -0,0 +1,8 @@
+# File
+
+## Syntax
+
+[_prologue_](prologue.md)
+
+## Semantics
+
diff --git a/doc/language/syntax/import_declaration.md b/doc/language/syntax/import_declaration.md
@@ -0,0 +1,9 @@
+# import-declaration
+
+## Syntax
+
+`import` [_module_name_](module_name.md) `weak`__?__
+
+## Semantics
+
+An `import` declaration is used to import a module into the current file.
diff --git a/doc/language/syntax/literal.md b/doc/language/syntax/literal.md
@@ -8,7 +8,12 @@
 [_boolean-literal_](boolean_literal.md) __|__\
 [_null-literal_](null_literal.md) __|__\
 [_character-literal_](character_literal.md) __|__\
+[_version-literal_](version_literal.md) __|__
 
 ## Semantics
 A literal is a constant value that is directly represented in the source code.
 The literal can be an integer, float, string, boolean, null, or character.
+
+version-literal is specifically added to be used with conditional-compilation,
+to compare with operating system or library versions. This is done at a very early stage of compilation, which
+is not able to use the standard library.
diff --git a/doc/language/syntax/module_declaration.md b/doc/language/syntax/module_declaration.md
@@ -0,0 +1,17 @@
+# module-declaration
+
+## Syntax
+
+`module` [_module_name_](module_name.md) __(__ `if` [_compile_condition_](compile_condition.md) __|__ `fallback` __)?__
+
+## Semantics
+
+Each file must have a `module` (or [`application`](application_declaration.md))
+declaration to give the file a module-name.
+
+The optional compile-condition is evaluated during the prologue-scan phase of compilation,
+this checks if the file should be compiled.
+
+Multiple files may have the same module-name, only if the conditional compilation is
+mutually exclusive. If a file has a `fallback` condition, it will be used if no other
+file with the same module-name is compiled.
diff --git a/doc/language/syntax/prologue.md b/doc/language/syntax/prologue.md
@@ -0,0 +1,13 @@
+# Prologue
+
+## Syntax
+
+__(__ [_module_declaration_](module_declaration.md) __|__ [_application_declaration_](application_declaration.md) __)__ [_import_statement_](import_statement.md)__*__
+
+## Semantic
+
+The prologue of a file contains only `module`, `application` and `import` statements, this makes it easy
+to make a parser to quickly scan all the source files to create a dependency tree.
+
+During prologue scan the parser can exit early.
+
diff --git a/doc/language/syntax/version_literal.md b/doc/language/syntax/version_literal.md
@@ -0,0 +1,8 @@
+# version-literal
+
+## Syntax
+
+\[0-9\]__{1-7}__ `v` __(__ \[0-9\]__+__ __(__ `.` \[0-9\]__+__ __)?__ __)?__
+
+## Semantics
+
diff --git a/doc/language/tools/hic_toml.md b/doc/language/tools/hic_toml.md
@@ -0,0 +1,33 @@
+# hic.toml
+
+The `hic.toml` file is a configuration file used to specify the dependencies of a Hic project or package. It is written in TOML (Tom's Obvious, Minimal Language) format.
+
+## Section Structure
+
+### \[package\]
+The `[package]` section is where you define the metadata for your Hic package. This includes the name, version, and other details that describe the package.
+
+```toml
+[package]
+name = "com.example.my_package"
+description = "A sample Hic package"
+version = "1.0.0"
+```
+
+#### name
+The `name` field specifies the name of the package. It should be a valid module name, which typically follows the format `com.example.my_package`; reverse domain names are commonly used to avoid naming conflicts.
+
+All modules-names in the package must have the prefix of the package name.
+
+### \[dependencies\]
+
+The `[dependencies]` section is where you define the external packages that your Hic project depends on. Each dependency is specified with a key-value pair, where the key is the name of the package and the value is an object containing the details of the dependency.
+
+```toml
+[dependencies]
+com.example.foo = { git = "https://github.com/example/foo.git", branch = "v1.0" }
+com.example.baz = { url = "https://example.com/baz-2.3.zip"}
+com.example.qux = { path = "./local-qux" }
+com.example.bar = {}
+```
+
diff --git a/doc/language/tools/manifest.md b/doc/language/tools/manifest.md
diff --git a/src/file.cpp b/src/file.cpp
@@ -0,0 +1,42 @@
+
+#include "file.hpp"
+#include <vector>
+
+namespace hl {
+
+static std::vector<file> files;
+
+file::file(std::size_t id, std::filesystem::path const& path) : _id(id), _path(path)
+{
+    assert(not path.empty());
+    assert(path.is_absolute());
+    _path = std::filesystem::absolute(path);
+    assert(_path.is_absolute());
+    assert(_path.is_normalized());
+    assert(_path.has_filename());
+}
+
+std::size_t file::id() const noexcept
+{
+    return _id;
+}
+
+std::filesystem::path const& file::path() const
+{
+    return _path;
+}
+
+[[nodiscard]] file& make_file(std::filesystem::path const& path)
+{
+    static std::size_t next_id = 1;
+    return *new file(next_id++, path);
+}
+
+[[nodiscard]] file& get_file(std::size_t file_id)
+{
+    // In a real implementation, this would look up the file by its ID.
+    // Here we just create a dummy file for demonstration purposes.
+    return make_file(std::filesystem::path("dummy_file_" + std::to_string(file_id)));
+}
+
+} // namespace hl
diff --git a/src/file.hpp b/src/file.hpp
@@ -0,0 +1,41 @@
+
+#ifndef HL_FILE_HPP
+#define HL_FILE_HPP
+
+#indlude <filesystem>
+#include <cstddef>
+
+namespace hl {
+
+class file {
+public:
+    /** Create a file object with the given path.
+     * 
+     * @param path The absolute normalized path to the file.
+     */
+    explicit file(std::size_t id, std::filesystem::path const& path);
+
+    /** Unique identifier for the file
+     */
+    [[nodiscard]] std::size_t id() const noexcept;
+
+    /** Get the absolute normalized path to the file.
+     * 
+     * @return The absolute normalized path to the file.
+     */
+    [[nodiscard]] std::filesystem::path const& path() const;
+    
+private:
+    std::size_t _id = 0;
+
+    /** The absolute normalized path to the file.
+     */
+    std::filessystem::path _path;
+};
+
+[[nodiscard]] file& make_file(std::filesystem::path const& path);
+[[nodiscard]] file& get_file(std::size_t file_id);
+
+}
+
+#endif // HL_FILE_HPP
diff --git a/src/token.hpp b/src/token.hpp
@@ -26,6 +26,7 @@ class token {
         quote_literal,
         integer_literal,
         float_literal,
+        version_literal,
         positional_argument,
     };
 
@@ -42,6 +43,7 @@ class token {
     static constexpr kind_type quote_literal = kind_type::quote_literal;
     static constexpr kind_type integer_literal = kind_type::integer_literal;
     static constexpr kind_type float_literal = kind_type::float_literal;
+    static constexpr kind_type version_literal = kind_type::version_literal;
     static constexpr kind_type positional_argument = kind_type::positional_argument;
 
     std::size_t module_id = 0;
diff --git a/src/tokenizer.cpp b/src/tokenizer.cpp
@@ -75,35 +75,42 @@ tokenizer::tokenizer(size_t module_id, std::string_view module_text) noexcept :
             continue;
         }
 
-        if (auto const token = parse_line_comment(); token.has_error()) {
+        if (auto token = parse_line_comment(); token.has_error()) {
             return std::unexpected{token.error()};
         } else if (token.has_value()) {
-            delegate.on_token(*token);
+            delegate.on_token(std::move(token).value());
             continue;
         }
 
-        if (auto const token = parse_block_comment(); token.has_error()) {
+        if (auto token = parse_block_comment(); token.has_error()) {
             return std::unexpected{token.error()};
         } else if (token.has_value()) {
-            delegate.on_token(*token);
+            delegate.on_token(std::move(token).value());
             continue;
         }
 
         if (cp == '*' and cp2 == '/') {
             return make_error("Unexpected end of comment; found '*/' without a matching '/*'.");
         }
 
-        if (auto const token = parse_number(); token.has_error()) {
+        if (auto token = parse_version(); token.has_error()) {
             return std::unexpected{token.error()};
         } else if (token.has_value()) {
-            delegate.on_token(*token);
+            delegate.on_token(std::move(token).value());
             continue;
         }
 
-        if (auto const token = parse_string(); token.has_error()) {
+        if (auto token = parse_number(); token.has_error()) {
             return std::unexpected{token.error()};
         } else if (token.has_value()) {
-            delegate.on_token(*token);
+            delegate.on_token(std::move(token).value());
+            continue;
+        }
+
+        if (auto token = parse_string(); token.has_error()) {
+            return std::unexpected{token.error()};
+        } else if (token.has_value()) {
+            delegate.on_token(std::move(token).value());
             continue;
         }
 
@@ -113,10 +120,10 @@ tokenizer::tokenizer(size_t module_id, std::string_view module_text) noexcept :
             continue;
         }
 
-        if (auto const token = parse_positional_argument(); token.has_error()) {
+        if (auto token = parse_positional_argument(); token.has_error()) {
             return std::unexpected{token.error()};
         } else if (token.has_value()) {
-            delegate.on_token(*token);
+            delegate.on_token(std::move(token).value());
             continue;
         }
 
@@ -127,17 +134,17 @@ tokenizer::tokenizer(size_t module_id, std::string_view module_text) noexcept :
             continue;
         }
 
-        if (auto const token = parse_identifier(); token.has_error()) {
+        if (auto token = parse_identifier(); token.has_error()) {
             return std::unexpected{token.error()};
         } else if (token.has_value()) {
-            delegate.on_token(*token);
+            delegate.on_token(std::move(token).value());
             continue;
         }
 
-        if (auto const token = parse_operator(); token.has_error()) {
+        if (auto token = parse_operator(); token.has_error()) {
             return std::unexpected{token.error()};
         } else if (token.has_value()) {
-            delegate.on_token(*token);
+            delegate.on_token(std::move(token).value());
             continue;
         }
 
diff --git a/src/tokenizer.hpp b/src/tokenizer.hpp
@@ -39,7 +39,7 @@ class tokenizer {
     [[nodiscard]] std::expected<void, std::string> tokenize(delegate_type& delegate);
 
 private:
-    character_lookahead<3> _lookahead = {};
+    character_lookahead<8> _lookahead = {};
     char const* _ptr = nullptr;
     char const* _end = nullptr;
     std::size_t _module_id = 0;
@@ -86,6 +86,7 @@ class tokenizer {
     [[nodiscard]] maybe_expected<token, std::string> parse_string();
     [[nodiscard]] maybe_expected<token, std::string> parse_identifier();
     [[nodiscard]] maybe_expected<token, std::string> parse_operator();
+    [[nodiscard]] maybe_expected<token, std::string> parse_version();
     [[nodiscard]] maybe_expected<token, std::string> parse_number();
     [[nodiscard]] maybe_expected<token, std::string> parse_line_comment();
     [[nodiscard]] maybe_expected<token, std::string> parse_block_comment();
diff --git a/src/tokenizer_parse_version.cpp b/src/tokenizer_parse_version.cpp

Original file line number	Diff line number	Diff line change
`@@ -54,6 +54,7 @@ add_library(hic_objects OBJECT`
`54`	`54`	`"${CMAKE_CURRENT_SOURCE_DIR}/src/tokenizer_parse_operator.cpp"`
`55`	`55`	`"${CMAKE_CURRENT_SOURCE_DIR}/src/tokenizer_parse_positional_argument.cpp"`
`56`	`56`	`"${CMAKE_CURRENT_SOURCE_DIR}/src/tokenizer_parse_string.cpp"`
	`57`	`+ "${CMAKE_CURRENT_SOURCE_DIR}/src/tokenizer_parse_version.cpp"`
`57`	`58`	`"${CMAKE_CURRENT_SOURCE_DIR}/src/utf8.cpp"`
`58`	`59`	`"${CMAKE_CURRENT_SOURCE_DIR}/src/utf8.hpp"`
`59`	`60`	`)`