# LunaConfig

LunaConfig is a configuration language build on top of python. It allows user 
to define options and the dependencies then reuse these options in their source 
code for customisable build.

Lunaix use LunaConfig to toggle various optional modules, subsystems or features
and allow parameterised kernel build.


## Design Motivation

LunaConfig is designed as an improvement over the old-school Kconfig, 
particularly to address its lack of hierarchical representation. Kconfig 
organises options into a large, flat list, even though they appear in a 
hierarchical menu structure. As a result, it can be very difficult to 
determine which menu a configuration option belongs to without diving into 
menuconfig.

## Basic Constructs

LunaConfig is presented as a file named `LConfig` and thus limited to one 
LConfig per directory. This is because LunaConfig enforce user to organise each 
directory to be a module or logical packaging of set of relavent functionalities.

Each LunaConfig files is comprised by these major constructs:

1. Config Component: `Terms` and `Groups`
2. Config Import
3. Native Python

We will describe them in details in the following sections

### Terms

> The object that hold the value for customisation

```py
def feature1() -> bool:
    return True
```

This defined an option named `feature1` with type of `bool` and the default
value of `True`.

### Groups

> The logical object that is used to organise the `terms` or other `groups`

A group is similar to term but without return type indication and return 
statement

And it is usually nested with other groups or terms.

```py
def group1():
    def feature1() -> bool:
        return True
```

### Import Mechanism

Multiple `LConfig`s may be defined across different sub-directory in large scale
project for better maintainability

LunaConfig allow you to import content of other LConfig using python's relative 
import feature:

```py
from . import module
```

This import mechanism works like `#include` directive in C preprocessor,
the `from . import` construct will be automatically intercepted by the LConfig 
interpreter and be replaced with the content from `./module/LConfig`

You can also address file in the deeper hierarchy of the directory tree, for 
example

```py
from .sub1.sub2 import module
```

This will be translated into `./sub1/sub2/module/LConfig`

It can also be used in any valid python conditional branches to support 
conditional import

```py
if condition_1:
    from . import module1
elif condition_2:
    from . import module2
```

### Native Python

Native Python code is fully supported in LunaConfig, this include everything 
like packages import, functions, and class definitions. LunaConfig has the 
ability to distinguish these code transparently from legitimate config code.

However, there is one exception for this ability. Since LunaConfig treat 
function definition as declaration of config component, to define a python 
native function you will need to decorate it with `@native`. For example:

```py
@native
def add(a, b):
    return a + b

def feature1() -> int:
    return add(1, 2)
```

If a native function is nested in a config component, it will not be affected 
by the scope and still avaliable globally. But this is not the case if it is 
nested by another native function.

If a config component is nested in a native function, then it is ignored by 
LunaConfig

## Term Typing

A config term require it's value type to be specified explicitly. The type can 
be a literal type, primitive type or composite type

### Literal Typing

A term can take a literal as it's type, doing this will ensure the value taken 
by the term to be exactly same as the given type

```py
# OK
def feature1() -> "value":
    return "value"
    # return "value2"

# Error
def feature1() -> "value":
    return "abc"
```

### Primitive Typing

A term can take any python's primitive type, the value taken by the term will 
be type checked rather than value checked

```py
# OK
def feature1() -> int:
    return 123

# Error
def feature1() -> int:
    return "abc"
```

### Composite Typing

Any literal type or primitive type can be composite together via some structure 
to form composite type. The checking on these type is depends on the composite 
structure used. 

#### Union Structure

A Union structure realised through binary disjunctive connector `|`. The term 
value must satisfy the type check against one of the composite type:

```py
def feature1() -> "a" | "b" | int:
    # value can be either:
    #  "a" or "b" or any integer
    return "a"
```

## Component Attributes

Each component have set of attributes to modify its behaviour and apperance, 
these attributes are conveyed through decorators

### Labels

> usage: `Groups` and `Terms`

Label provide a user friendly name for a component, which will be the first 
choice of the name displayed by the interactive configuration tool

```py
@"This is feature 1"
def feature1() -> bool:
    return True
```

### Readonly

> usage: `Terms`

Marking a term to be readonly prevent explicit value update, that is, manual 
update by user. Implicit value update initiated by `constrains` (more on this 
later) is still allowed. 

```py
@readonly
def feature1() -> bool:
    return True
```

### Visibility

> usage: `Groups` and `Terms`

A component can be marked to be hidden thus prevent it from displayed by the 
configuration tool, it does not affect the visibility in the code.

If the decorated target is a group, then it is inherited by all it's 
subordinates.

```py
@hidden
def feature1() -> bool:
    return True
```

### Flag

> usage: `Terms`

This is a short hand of both `@hidden` and `@readonly`

```py
@flag
def feature1() -> bool:
    return True
```

is same as

```py
@hidden
@readonly
def feature1() -> bool:
    return True
```

### Parent

> usage: `Groups` and `Terms`

Any component can be defined outside of the logical hierachial structure (i.e., 
the nested function) but still attached to it's physical hierachial structure.

```py
@parent := parent_group
def feature1() -> bool:
    return True

def parent_group():
    def feature2() -> bool:
        return False
```

This will assigned `feature1` to be a subordinate of `parent_group`. Note that 
the reference to `parent_group` does not required to be after the declaration.

It is equivalent to 

```py
def parent_group():
    def feature2() -> bool:
        return False
    
    def feature1() -> bool:
        return True
```

### Help Message

> usage: `Groups` and `Terms`

A help message will provide explainantion or comment of a component, to be used 
and displayed by the configuration tool.

The form of message is expressed using python's doc-string

```py
def feature1() -> bool:
    """
    This is help message for feature1
    """

    return True
```

## Directives

There are builtin directives that is used inside the component.

### Dependency

> usage: `Groups` and `Terms`

The dependency between components is described by various `require(...)` 
directives. 

This directive follows the python function call syntax and accept one argument 
of a boolean expression as depedency predicate.

Multiple `require` directives will be chainned together with logical conjunction 
(i.e., `and`)

```py
def feature1() -> bool:
    require (feature2 or feature3)
    require (feature5)
    
    return True
```

This composition is equivalent to `feature5 and (feature2 or feature3)`, 
indicate that the `feature1` require presences of both `feature5` and at least 
one of `feature2` or `feature3`.

If a dependency can not be satisfied, then the feature is disabled. This will 
cause it neither to be shown in configuration tool nor referencable in source 
code.

Note that the dependency check only perform on the enablement of the node but 
not visibility.

### Constrains (Inverse Dependency)

> usage: `Terms` with `bool` value type

The `when(...)` directive allow changing the default value based on the 
predicate evaluation on the value of other terms. Therefore, it can be only 
used by `Terms` with `bool` as value type.

Similar to `require`, it is based on the function call syntax and takes one 
argument of conjunctive expression (i.e., boolean expression with only `and` 
connectors).

Multiple `when` will be chained together using logical disjunction (i.e., `or`)

```py
def feature1() -> bool:
    when (feature2 is "value1" and feature5 is "value1")
    when (feature3)
```

Which means `feature1` will takes value of `True` if one of the following is 
satisfied:
 + both `feature2` and `feature5` has value of `"value1"`
 + `feature3` has value of True

Notice that we do not have `return` statement at the end as the precense of 
`when` will add a return automatically (or replace it if one exists)


## Validation

Since the language is based on Python, it's very tempting to pack in advanced 
features or messy logic into the config file, which can make it harder to 
follow—especially as the file grows in size.

LunaConfig recognises this issue and includes a built-in linter to help users 
identify such bad practices. It shows warnings by default but can be configured 
to raise errors instead.

Currently, LunaConfig detect the misuses based on these rules:

+ `dynamic-logic`: The presence of conditional branching that could lead to 
   complex logic. However, pattern matching is allowed.
+ `while-loop`, `for-loop`: The presence of any loop structure.
+ `class-def`: The presence of class definition
+ `complex-struct`: The present of complicated data structure such as `dict`.
+ `side-effect`: The presence of dynamic assignment of other config terms value.
+ `non-trivial-value`: The presence of non-trivial value being used as default 
   value. This include every things **other than**:
    + literal constant
    + template literal