@@ -10,17+10,20 @@ and allow parameterised kernel build.
## Design Motivation
## Design Motivation
-LunaConfig is designed to be an improvement over the old-school Kconfig, which in
-particular to address the issue of lacking hierchical representation. This is
-because Kconfig organise options into a big flat list, while the options are
-organised into menu which is hierachical in nature. It is very difficult to
-identify membership of a config without diving into menuconfig.
+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 Concepts
+## 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.
+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.
-In each LunaConfig files, these major concepts you will usually seen.
+Each LunaConfig files is comprised by these major constructs:
-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.
+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:
+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:
-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 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
+If a config component is nested in a native function, then it is ignored by
+LunaConfig
## Term Typing
## 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
+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
### 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
+A term can take a literal as it's type, doing this will ensure the value taken
-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.
+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
#### Union Structure
-A Union structure realised through binary disjunctive connector `|`. The term value must satisfy the type check against one of the composite type:
+A Union structure realised through binary disjunctive connector `|`. The term
+value must satisfy the type check against one of the composite type:
-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.
+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
-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.
+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.
-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.
+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.
-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`.
+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.
+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.
+Note that the dependency check only perform on the enablement of the node but
+not visibility.
-### Auto Toggling (Inverse Dependency)
+### Constrains (Inverse Dependency)
> usage: `Terms` with `bool` value type
> 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.
+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).
+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`)
Multiple `when` will be chained together using logical disjunction (i.e., `or`)
-Which means `feature1` will takes value of `True` if one of the following is satisfied:
+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
+ 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)
+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
## Validation
-For configuration language being a python superset will have a risk of abusing due to the high flexibility. This include complex logic, non-trivial operation being used in a component to derive the final value. Thus shifting the style from declarative to imperative and greatly reduce the overall reability.
+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.
-For prevention of this potential drawback, LunaConfig implemented a syntactical validator to identify these possible bad-practice and issue warning (or rise a fatal-error depending on the user setting).
+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:
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.
++ `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.
+ `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:
- + constant
- + variable reference
- + comparison between constant or variable
- + single boolean operation
- + ternary operator with constant/refernece and trivial boolean operation
++ `non-trivial-value`: The presence of non-trivial value being used as default
+ value. This include every things **other than**:
git://scm.lunaixsky.com / lunaix-os.git / commitdiff