import split

Author: takev

doc/language/builtin/string.md

@@ -0,0 +1,39 @@
+# string
+
+## Big Endian layout
+
+```
+struct string {
+    u64 _data
+    u64 _size
+    u64 _capacity
+};
+
+fn is_short(let self := string) -> bool {
+    return (self._capacity & 1) == 0
+}
+
+fn capacity(let self := string) -> u64 {
+    if (self.is_short()) {
+        return 23
+    } else {
+        return self._capacity >> 1
+    }
+}
+
+fn size(let self := string) -> u64 {
+    if (self.is_short()) {
+        return 23 - (self._capacity >> 1)
+    } else {
+        return self._size
+    }
+}
+
+fn data(let self := string) -> ptr[char] {
+    if (self.is_short()) {
+        return std.address_of(char, self)
+    } else {
+        return self._ptr
+    }
+}
+```

doc/language/c_abi_compatibility.md

@@ -0,0 +1,39 @@
+# C-ABI Compatibility
+
+
+Integers
+--------
+
+Hikolang's `int` type is compatible with C-style integers,
+including layout and size in memory.
+
+The following integers are compatible with the C-API.
+
+ | hikolang-type                                     | hikolang alias | C-type
+ |:--------------------------------------------------|:---------------|:---------
+ | int[-128..=127]                                   | std.i8         | std::int8_t
+ | int[0..=255]                                      | std.u8         | std::uint8_t
+ | int[-32768..=32767]                               | std.i16        | std::int16_t
+ | int[0..=65535]                                    | std.u16        | std::uint16_t
+ | int[-2147483648..=2147483647]                     | std.i32        | std::int32_t
+ | int[0..=4294967295]                               | std.u32        | std::uint32_t
+ | int[-9223372036854775808..=9223372036854775807]   | std.i32        | std::int32_t
+ | int[0..=18446744073709551615]                     | std.u32        | std::uint32_t
+ | int[0..=255]                                      | std.c_bool     | std::bool
+ | int[0..=255]                                      | std.c_byte     | std::byte
+ |                                                   | std.c_char     | char
+ | int[-128..=127]                                   | std.c_ichar    | signed char
+ | int[0..=255]                                      | std.c_uchar    | unsigned char
+ |                                                   | std.c_ishort   | signed short
+ |                                                   | std.c_ushort   | unsigned short
+ |                                                   | std.c_iint     | signed int
+ |                                                   | std.c_uint     | unsigned int
+ |                                                   | std.c_ilong    | signed long
+ |                                                   | std.c_ulong    | unsigned long
+ |                                                   | std.c_illong   | signed long long
+ |                                                   | std.c_ullong   | unsigned long long
+ |                                                   | std.c_isize    | std::ptrdiff_t
+ |                                                   | std.c_usize    | std::size_t
+ |                                                   | std.c_ptr      | std::intptr_t
+ |                                                   | std.c_ptr      | std::uintptr_t
+ |                                                   | std.c_ptr      | _type_ *

doc/language/syntax/argument_declaration.md

@@ -2,19 +2,24 @@
 
 ## Syntax
 
-[_binding_mode_](binding_mode.md)__?__ [_name_](name.md) [_type_declaration_](type_declaration.md)__?__ _default_value_declaration_**?** __|__\
-[_binding_mode_](binding_mode.md)__?__ [_name_](name.md)`...` [_type_declaration_](type_declaration.md)__?__
+[_binding_mode_](binding_mode.md)__?__ [_name_](name.md) [_type_declaration_](type_declaration.md)__?__
+__(__ `=` [_expression_](expression.md) __)?__ __|__\
 
+[_literal_](literal.md) [_type_declaration_](type_declaration.md)__?__ __|__\
 
-### default-value-declaration
+`(` [_expression_](expression.md) `)` [_type_declaration_](type_declaration.md)__?__ __|__\
 
-`=` [_expression_](expression.md)
+[_binding_mode_](binding_mode.md)__?__ [_name_](name.md)`...` [_type_declaration_](type_declaration.md)__?__
 
 
 ## Semantics
 Declares an argument for a function or lambda with a [_name_](name.md)
 which can be used as a variable inside the function's or lambda's code-block.
 
+If the argument is a [_literal_](literal.md) or an [_expression_](expression.md)
+between `(` and `)`, then the argument is a constant. This allows functions
+to be specialized when a specific argument is passed.
+
 The type declaration is optional. If not specified, the type is inferred from
 the types passed in the [_function-call_](function_call.md). If the type is
 specified, the type-expression must be elaborated to a concrete type at

doc/language/syntax/attributes.md

@@ -2,13 +2,65 @@
 
 ## Syntax
 
-### Optional attribute
-
 [_fully_qualified_name_](fully_qualified_name.md) __(__ `(` [_argument_list_](argument_list.md) `)` __)?__
 
-### Required attribute
+## Semantics
 
-[_fully_qualified_name_](fully_qualified_name.md) __(__ `(` [_argument_list_](argument_list.md) `)` __)?__
+If the [_fully_qualified_name_](fully_qualified_name.md) is a single name,
+then this attribute is required. A required attribute must be handled by the compiler.
+If the compiler does not know how to handle the attribute it is an error.
 
-## Semantics
+If the [_fully_qualified_name_](fully_qualified_name.md) has the `std` prefix
+it is a well-known optional attribute. These attributes don't change the semantic
+meaning of the program, instead they are directives to the compiler to create
+better code.
+
+Other prefixes are attributes that are handled by specific compilers. Compilers
+should ignore any attributes that do not match their own prefix.
+
+### abi()
+Make this function available for linking with an application written in a
+different language; using a different ABI (Application Binary Interface).
+
+ - __c__: Use the C ABI.
+ - __cpp__: Use the C++ ABI.
+
+### no_return
+This function will not return.
+
+An implementation must terminate the application if the function does
+return. Or proof that the function will not return.
+
+### pre()
+Pre-condition is checked before calling the function.
+
+### post()
+Post-condition is checked after calling the function.
+
+
+### std.no_inline
+Calls to this function are never inlined.
+
+This is a strong optimization lever:
+ - It reduces code size by not inlining the code, which will reduce
+   code-cache usage.
+ - It significantly reduce register pressure, which will reduce the
+   amount of reads/writes to memory. And may in turn reduce size of the
+   code; which in turn may allow more inlining.
+
+### std.depricated, std.depricated()
+This function is depricated print a warning. A reason for deprication can
+be passed as a constant-string.
+
+### std.discard
+The return value of this function is allowed to be discarded by the caller.
+
+Discarding a return value is:
+ - The return value is not assigned to a variable.
+ - The return value is not passed to a function.
+ - The return value is not part of a larger expression.
+ - The return value is not used as an expression to a control-expression. 
+
+If this attribute isn't set on a function, the compiler must give a warning
+when the function's return value is discarded.
 

doc/language/syntax/function_definition.md

@@ -2,14 +2,11 @@
 
 ## Syntax
 
-`function` [_name_](name.md) `(` [_argument-list_](argument_list.md) `)`\
-*function-attribute*__*__ \
+`fn` [_name_](name.md) `(` [_argument-list_](argument_list.md) `)`
 [_result-type-declaration_](result_type_declaration.md)__?__\
+*attribute*__*__ \
 `{` [_statement-list_](statement_list.md) `}`
 
-### function-attribute
-`pre` `(` [_expression_list_](expression_list.md) `)` __|__\
-`post` `(` [_expression_list_](expression_list.md) `)` __|__\
 
 ## Semantics
 

doc/language/syntax/import_declaration.md

@@ -0,0 +1,5 @@
+# import-fn
+
+## Syntax
+
+`import` `fn` `c` [_name_](name.md) `(` [_argument-list_](argument_list.md) `)` [_result-type-declaration_](result_type_declaration.md) `;`

doc/language/syntax/import_fn_c.md

@@ -0,0 +1,49 @@
+# import-git
+
+## Syntax
+
+`import` `git` _git-url_ *git-rev*__?__ [_compile_condition_](compile_condition.md)__?__ `;`
+
+git-url := [_string_literal_](string_literal.md)
+
+git-rev := [_string_literal_](string_literal.md)
+
+
+## Semantics
+
+Clone a git repository into `.hkdeps/<name>-<hash>/` of the host-repository.
+Modules located in the git repository can then be imported into any module
+in the current repository.
+
+The first _string_literal_ is the URL of the git repository, and the second
+_string_literal_ is the [git-rev](https://git-scm.com/docs/git-rev-parse.html)
+to checkout.
+
+When the `.hkdeps/<name>-<hash>/` directory for a repository does not yet
+exist; the compiler will clone the repository into that directory then
+checkout the git-rev.
+
+Otherwise when the `.hkdeps/<name>-<hash>/` directory contains a clone
+of the repository and points to the same git-rev and the git-rev is a
+points to a _tag_ or a _sha_. Then this means that the correct revision
+is checked out, so nothing is changed.
+
+Otherwise when the `.hkdeps/<name>-<hash>/` directory contains a clone
+of the repository and points to a different git-rev or the git-rev points
+to a _branch_. The repository is cleaned by removing files that are not
+part of the repository, then the remote is fetched and the git-rev is
+checked out. 
+
+A failure to clone is a warning, it is possible that other checkouts may
+satisfy imported packages.
+
+A failure to update is an error, because it may mean that local
+modifications of files are conflicting with the update.
+
+A _tag_ is expected to not change and therefor no update is done. You
+can override this using the `--force-update` compiler option.
+
+A cleanup is needed when the source files are updated, as out-of-repository
+files had been created by those source files. With the `--force-clean` will
+clean these files even if the repository has not been updated.
+

doc/language/syntax/import_git.md

@@ -0,0 +1,21 @@
+# import-lib
+
+## Syntax
+
+`import` `lib` _lib-name_ [_semantic_version_]__?__ [_compile_condition_](compile_condition.md)__?__ `;`
+
+lib-name := [_string_literal_](string_literal.md)
+
+## Semantics
+
+Link any applications that imports a module or its package recrusively to
+the library named _lib-name_.
+
+The library is either a archive/static library or a dynamic/shared library 
+and is found in the library path. 
+
+The _lib-name_ is the base name, it excludes both the prefix `lib` and the
+extensions: `.so`, `.a`, `.lib`, `.dll`.
+
+An optional _semantic-version_ is used to select a specific version of a
+library.

doc/language/syntax/import_lib.md

@@ -0,0 +1,23 @@
+# import
+
+## Syntax
+
+`import` [_fully_qualified_name_](fully_qualified_name.md) __(__ `as` [_identifier_](identifier.md) __)?__
+[_compile_condition_](compile_condition.md)__?__ `;`
+
+## Semantics
+
+Imports a module, so that its functions, types and variables can be used in the
+current file.
+
+The [_fully_qualified_name_](fully_qualified_name.md) is the name of the module
+to import. The optional `as` clause allows the module to be made available under
+a shorter name to make the code more readable.
+
+If the module is located in a different repository, then the repository must be
+imported using a `git` or `zip` by at least one file in the current repository.
+Likely this in done in a `application` or `package` file.
+
+When you import a module all sub-modules are imported as well; accessible through
+the sub-names. This holds when the module is renamed through the `as` part.
+