Work in progress

rudder-lang/docs/DESIGN_DECISIONS → rudder-lang/docs/compiler.adoc

@@ -1,45 +1,63 @@
-Desing decision and their reason
-================================
+= Design decisions
 
-* "as outvar" for status variables
+== Metadata
 
-The important thing in the langage is the state definition.
+We want to be able to extend the language and the generation process without changing the language.
+Moreover we want to give the user the ability to store structured data with resources.
+Hence metadata that can be anything available in the language.
+
+=== Format
+
+The first line of the file is `@format=x`, allowing to detect the current
+code format of the file.
+This will allow detecting files needing a conversion in the future,
+which will be handy for Rudder upgrades.
+
+== Language
+
+=== Use the `as outvar` for status variables.
+
+The important thing in the language is the state definition.
 State definition is done by calling a specific state on a specific resource.
 Everything else (such as variable definition) is unimportant.
-We want to deemphasise the variable defnition aspect of state definition by removing the '=' 
+We want to de-emphasize the variable definition aspect of state definition by removing the '=' 
 at the beginning of the statement. The '=' sign is very visible and signifies an affectation.
 We are not doing an affectation we are defining a state which sometimes has the side effect of defining a variable.
 
-* subresources and alias
+=== sub-resources and alias
 
-A sub resource is a part of resources. It means that changing a subresource implies changing the parent resource.
+A sub resource is a part of resources. It means that changing a sub-resource implies changing the parent resource.
 However changing the resource does not necessarily means changing the sub resource.
 For robustness of the state checker, different states of the same resource are incompatible.
 This means that a resource must be split into sub resource to make different sub states compatible.
 (ex: FileContent and FilePermission are sub resources of file and are compatible).
-This means that thing that may be perceived as states are in fact subresources.
+This means that thing that may be perceived as states are in fact sub-resources.
 
-That's why to make life easier for the user we want to also define aliases. Alases don't have the same constraint.
-There can be as many aliases as wanted for a single resource, an alias of a subresource can be interpreted by the user
-as a suplementary state of the parent resource.
+That's why to make life easier for the user we want to also define aliases. Aliases don't have the same constraint.
+There can be as many aliases as wanted for a single resource, an alias of a sub-resource can be interpreted by the user
+as a supplementary state of the parent resource.
 
 TODO since the compatibility is not the same for aliases and state, shouldn't we indicate the difference somehow.
 
 
-* json read method
+=== JSON read method
 
-* iterators
+TODO
 
-* metadata
-We want to be able to extend the language and the generation process without changing the language.
-Moreover we want to give the user the ability to store structured data with resources.
-Hence metadata that can be anything available in the language
+=== Iterators
+
+TODO
+
+=== Subtyping
 
-* subtyping
+TODO
 
-* log/return/fail
+=== log/return/fail
+
+TODO
+
+=== local order, global order
 
-* ordre local, ordre global
 Les données locales (variables) doivent être définies avant d'etre utilisée car c'est une bonne pratique
 qui permet de détcter des erreurs logiques.
 Les données globales n'ont pas a etre définies dans l'ordre car il peut être difficile de maitriser
@@ -93,10 +111,7 @@ evitons les confusions, on pourra toujours en réautoriser a posteriori
 nécessaire dans les resources et les states car nous définissons des configurations.
 Les utilisateurs s'attendent à ce qu'on leur fournisse des valeurs par défaut correspondant au cas le plus courant lorsque c'est possible.
 
-* @format=x
-Avoir une ligne strictement parsée présente en début de fichier permet de détecter de l'extérieur la version actuelle du format du code.
-A l'avenir cela permettra de détecter si on dispose du bon compilateur ou si une conversion est nécessaire.
-Pratique pour les upgrade de rudder.
+
 
 * =~ pour les enums
 On compare des variables avec des enums de type différent car il y a un mécanisme d'héritage d'enum.

rudder-lang/docs/index.adoc

@@ -94,4 +94,6 @@ We want to go back to more
 
 
 
-include::concepts.adoc[leveloffset=+1]
+include::concepts.adoc[leveloffset=+1]
+
+include::compiler.adoc[leveloffset=+1]