From 8ccc314d05a9cfc917f2c8f40cd72d92f886b0e3 Mon Sep 17 00:00:00 2001 From: cdelaunay Date: Tue, 28 Jan 2020 14:41:17 +0100 Subject: [PATCH 1/3] fixed some class comments --- Cinic-Core.package/Cinic.class/README.md | 8 ++++---- Cinic-Core.package/Cinic.class/properties.json | 2 +- Cinic-Core.package/CinicSection.class/README.md | 5 ++++- Cinic-Core.package/CinicSection.class/properties.json | 2 +- Cinic-Core.package/CinicStep.class/README.md | 4 +++- Cinic-Core.package/CinicStep.class/properties.json | 2 +- Cinic-Core.package/CurrentCinic.class/README.md | 3 ++- Cinic-Core.package/CurrentCinic.class/properties.json | 2 +- 8 files changed, 17 insertions(+), 11 deletions(-) diff --git a/Cinic-Core.package/Cinic.class/README.md b/Cinic-Core.package/Cinic.class/README.md index 324ad2c..a8c41fa 100644 --- a/Cinic-Core.package/Cinic.class/README.md +++ b/Cinic-Core.package/Cinic.class/README.md @@ -3,7 +3,7 @@ I'm a Configuration holding access to static and dynamic configuration elements. Loading ======= - config := Configuration readFileNamed: 'config.json'. + config := Cinic readFileNamed: 'config.json'. config apply. Global use: @@ -15,7 +15,7 @@ A configuration can be made globally available by issuing Code can then access - Confguration default + Cinic default Script usage ============ @@ -35,8 +35,8 @@ In-Image usage Components can be annotated using pragmas myConfiguration - - ^ ConfigurationStep new + + ^ CinicStep new group: #server; action: [ :config | MyServer port: config port ]. diff --git a/Cinic-Core.package/Cinic.class/properties.json b/Cinic-Core.package/Cinic.class/properties.json index fd7d8df..a8ee179 100644 --- a/Cinic-Core.package/Cinic.class/properties.json +++ b/Cinic-Core.package/Cinic.class/properties.json @@ -1,5 +1,5 @@ { - "commentStamp" : "NorbertHartl 4/23/2019 16:56", + "commentStamp" : "cdelaunay 1/28/2020 14:31", "super" : "Object", "category" : "Cinic-Core", "classinstvars" : [ diff --git a/Cinic-Core.package/CinicSection.class/README.md b/Cinic-Core.package/CinicSection.class/README.md index bbc10ee..dbc0210 100644 --- a/Cinic-Core.package/CinicSection.class/README.md +++ b/Cinic-Core.package/CinicSection.class/README.md @@ -1 +1,4 @@ -I'm a ConfigurationSection. I hold one level of properties and I can be nested. I'm reflecting a hierarchical configuration format like JSON where every JSON object maps to an instance of my class. I'm a subclass to dictionary therefor \ No newline at end of file +I'm a Configuration Section. +I hold one level of properties and I can be nested. +I'm reflecting a hierarchical configuration format like JSON where every JSON object maps to an instance of my class. +I'm a subclass to dictionary therefor \ No newline at end of file diff --git a/Cinic-Core.package/CinicSection.class/properties.json b/Cinic-Core.package/CinicSection.class/properties.json index 522a5d5..ca184d4 100644 --- a/Cinic-Core.package/CinicSection.class/properties.json +++ b/Cinic-Core.package/CinicSection.class/properties.json @@ -1,5 +1,5 @@ { - "commentStamp" : "NorbertHartl 4/23/2019 16:57", + "commentStamp" : "cdelaunay 1/28/2020 14:32", "super" : "OrderedDictionary", "category" : "Cinic-Core", "classinstvars" : [ ], diff --git a/Cinic-Core.package/CinicStep.class/README.md b/Cinic-Core.package/CinicStep.class/README.md index 5d973ce..e53af7f 100644 --- a/Cinic-Core.package/CinicStep.class/README.md +++ b/Cinic-Core.package/CinicStep.class/README.md @@ -1 +1,3 @@ -I'm a ConfguratinStep. I reify a single action that needs to be executed in order to configure an image. I'm collect by the root configuration to prepare a list of configuration actions \ No newline at end of file +I'm a Configuration Step. +I reify a single action that needs to be executed in order to configure an image. +I'm collected by the root configuration to prepare a list of configuration actions \ No newline at end of file diff --git a/Cinic-Core.package/CinicStep.class/properties.json b/Cinic-Core.package/CinicStep.class/properties.json index cb10c44..5bae14e 100644 --- a/Cinic-Core.package/CinicStep.class/properties.json +++ b/Cinic-Core.package/CinicStep.class/properties.json @@ -1,5 +1,5 @@ { - "commentStamp" : "NorbertHartl 4/23/2019 16:59", + "commentStamp" : "cdelaunay 1/28/2020 14:37", "super" : "Object", "category" : "Cinic-Core", "classinstvars" : [ ], diff --git a/Cinic-Core.package/CurrentCinic.class/README.md b/Cinic-Core.package/CurrentCinic.class/README.md index 8be7828..e8a5f79 100644 --- a/Cinic-Core.package/CurrentCinic.class/README.md +++ b/Cinic-Core.package/CurrentCinic.class/README.md @@ -1 +1,2 @@ -I'm a dynamic variable to acquire configuration objects in code. I'm used in all nesting actions when sections are used. \ No newline at end of file +I'm a dynamic variable to acquire configuration objects in code. +I'm used in all nesting actions when sections are used. \ No newline at end of file diff --git a/Cinic-Core.package/CurrentCinic.class/properties.json b/Cinic-Core.package/CurrentCinic.class/properties.json index 98aebd5..d64dfbf 100644 --- a/Cinic-Core.package/CurrentCinic.class/properties.json +++ b/Cinic-Core.package/CurrentCinic.class/properties.json @@ -1,5 +1,5 @@ { - "commentStamp" : "NorbertHartl 4/23/2019 16:58", + "commentStamp" : "cdelaunay 1/28/2020 14:39", "super" : "DynamicVariable", "category" : "Cinic-Core", "classinstvars" : [ ], From 289c675f286f0d2e88e6fed556b72a75b4917198 Mon Sep 17 00:00:00 2001 From: cdelaunay Date: Tue, 28 Jan 2020 16:25:31 +0100 Subject: [PATCH 2/3] small comment adjustement --- Cinic-Core.package/Cinic.class/README.md | 2 +- Cinic-Core.package/Cinic.class/properties.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Cinic-Core.package/Cinic.class/README.md b/Cinic-Core.package/Cinic.class/README.md index a8c41fa..7e1fb35 100644 --- a/Cinic-Core.package/Cinic.class/README.md +++ b/Cinic-Core.package/Cinic.class/README.md @@ -37,7 +37,7 @@ Components can be annotated using pragmas myConfiguration ^ CinicStep new - group: #server; + section: #server; action: [ :config | MyServer port: config port ]. In order to apply the configuration to the image you need to evaluate diff --git a/Cinic-Core.package/Cinic.class/properties.json b/Cinic-Core.package/Cinic.class/properties.json index a8ee179..c039d5b 100644 --- a/Cinic-Core.package/Cinic.class/properties.json +++ b/Cinic-Core.package/Cinic.class/properties.json @@ -1,5 +1,5 @@ { - "commentStamp" : "cdelaunay 1/28/2020 14:31", + "commentStamp" : "cdelaunay 1/28/2020 16:24", "super" : "Object", "category" : "Cinic-Core", "classinstvars" : [ From fae608b49ccb7e21e22f68af5ecc51dcea0d7e23 Mon Sep 17 00:00:00 2001 From: Cyrille Delaunay <36200206+bocasti@users.noreply.github.com> Date: Tue, 28 Jan 2020 17:52:54 +0100 Subject: [PATCH 3/3] Updated readme --- README.md | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 165 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 09a30de..25ac9af 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,167 @@ -# pharo-configuration [![Build Status](https://travis-ci.org/zweidenker/Configurator.svg?branch=master)](https://travis-ci.org/zweidenker/Configurator) + +# Installation: + +Cinic is a [Pharo](https://pharo.org/) library that aims to help managing external configuration files. +It can be loaded into a pharo image with: + +```smalltalk +Metacello new + repository: 'https://github.com/zweidenker/Cinic:0.2’; + baseline: 'Cinic'; + load +``` + + +While the model of Cinic is format-agnostic, +the current implemented parser expects a configuration to comes in the form of a JSON file. +The parser could later be extended to other formats if needed. + + +Here is a contents example of such a configuration file: + +``` +{ + “section1” : + { + “property1” : “value1” + } , + “section2” : + { + “section21” : + { + “property2” : “value2” + { + } +} +``` + +# Loading configuration files: + +A configuration file can be loaded by executing: + +```smalltalk +config := Cinic readFileNamed: 'config.json'. +``` + +The resulting Cinic object will be the entry point for traversing the imported configuration. + +# Model: + +Cinic models configuration as a tree of Sections. +The root Section represents the root of the configuration file. +Sections can be nested without limitations. + +Regarding the implementation, a Section object is nothing more than a specialised Dictionary object. +Its keys are property or section names, +Its values are property values or Section objects. + +# Scripting actions: + +In order to act upon a configuration, Cinic provides some scripting facilities. +After loading the above configuration example, one could excecute: + +```smalltalk +#section1 sectionIn: config do: [ :aSection | + Transcript show: aSection property1 + ]. +#section2 sectionIn: config do: [ :aSection | + #section21 sectionIn: aSection do: [:aNestedSection | + Transcript show: aSection property2 + ] + ]. +``` + +Note that property names can be turned into messages send to a Section object. +Cinic will automatically "translate" such unknown messages, and made them return the associated property value. + +When iterating over inner sections of a configuration, Cinic will store the current section in a dynamic variable. +The above script can then be simplified as: + +```smalltalk +#section2 sectionIn: config do: [ :aSection | + #section21 sectionDo: [:aNestedSection | + Transcript show: aSection property2 + ] + ]. +``` + +# Implementing actions: + +An alternative to scripting configuration actions is to implement them as method. +This may be useful if you want to share a common action behaviour between multiple kind of configurations. +This can be done by using Steps. + +## Steps definition + +A Step knows about a Section path and an action block. +The action block is expected to be executed with an associated Section object as argument: + +```smalltalk +CinicStep new + section: #section1; + action: [ :aSection1 | Transcript show: aSection1 property1 ]. +``` + +A Step is intended to be returned by methods providing a `` pragma: + +```smalltalk +section21SetUp + + ^ CinicStep new + section: #section21; + action: [ :aSection21 | Transcript show: aSection property2 ]. +``` + +## Steps execution + +After loading a configuration, one can execute the Steps associated to this configuration by executing . + +```smalltalk +config := Cinic readFileNamed: 'config.json'. +config apply. +``` + +When applying a configuration, Cinic will gather all methods in the pharo image with pragma ``. +It will select the steps matching a section path in the configuration, and execute them. + +The steps will be executed in the same order than the file sections order. + + +## Steps section path + +The above example shows the case of a "standalone" section: #section21. +As soon as a configuration file includes a section with name #section21, the Step will be executed. +But a Step could also target a more precise section path: + +```smalltalk +section1SetUp + + ^ CinicStep new + sectionPath: #(section2 section21); + action: [ :aSection21 | Transcript show: aSection property1 ]. +``` + +In this case, the Step would be executed only if the configuration file provide a section with name #section2, +followed by a section with name #section21. +The block would be evaluated with the #section21 associated object. + +# Global use: + +After being loaded, a configuration can also be made globally available in the Pharo image with: + +```smalltalk +config beDefault +``` + +Code can then access + +```smalltalk +Cinic default +``` + + + + +