Browse Source

config format fully settled, plus minor tidies

master
Loki Verloren 7 months ago
parent
commit
8395844ba3
3 changed files with 13 additions and 4 deletions
  1. 1
    1
      README.md
  2. 8
    1
      doc/configformat.md
  3. 4
    2
      doc/overview.md

+ 1
- 1
README.md View File

@@ -56,7 +56,7 @@ See the [checklist](checklist.md) for current status.
56 56
 
57 57
 ## Documentation
58 58
 
59
-See [overview](doc/overview.md) for implementation and usage information, and [declarations](doc/declarations.md) for a human-readable description of the declaration syntax used in Tri.
59
+See [overview](doc/overview.md) for implementation and usage information, and [declarations](doc/declarations.md) for a human-readable description of the declaration syntax used in Tri. The format of the configuration file can be found in [configformat](docs/configformat.md).
60 60
 
61 61
 ## Motivation
62 62
 

configformat.md → doc/configformat.md View File

@@ -1,6 +1,10 @@
1 1
 # Tri Configuration File Format
2 2
 
3
-In keeping with the goals of the declaration format designed for Tri, the configuration format has been designed to the same ends - to be easy to read for humans, as well as easy to process by the machine.
3
+In keeping with the goals of the declaration format designed for Tri, the configuration format has been designed to the same ends - to be easy to read for humans, as well as easy to process by the machine. 
4
+
5
+Due to the built-in triggers `init` and `save`, in fact the human doesn't really ever have to even look at the configuration file, and since it never writes redundant default values, the human may not know anyway what names go where, without looking at the Tri app definition, but using the help builtin, one sees all the names.
6
+
7
+Under the detailed help with help save, the user can see the full, default configuration struct with defaults explicit, with a foregoing note saying that it is not necessary to put these lines in the configuration file and that they will be removed when the configuration is rewritten.
4 8
 
5 9
 ## Rules for structure of config
6 10
 
@@ -10,5 +14,8 @@ In keeping with the goals of the declaration format designed for Tri, the config
10 14
 4. Items belonging to commands are prefixed by a tab at the beginning of the line, and the group is delimited by the next command name at the start or the end of file
11 15
 5. Items that represent arrays, are likewise grouped under their parent name, with two tabs as prefix, and group ends at the first line with less than two tabs at the start.
12 16
 6. All content after the name and maybe prefix tabs, after one space after the name, is one whole string that is the value, thus one can have space- and tab-containing content, the only thing a value cannot have is a carriage return, because that is the end marker
17
+7. Any line that doesn't start with a letter or a tab is automatically ignored. These lines will not be preserved when it rewrites the file. 
18
+8. Any line that is otherwise correct syntax (name, or 1 or 2 tabs and name, but does not exist in the Tri), will trigger an error and halt of execution.
19
+9. Any valid name value that is followed by an invalid value will also halt execution specifying its position and printing it's next and previous lines, and for command items, printed as commandname/varname (triggers will error if they have a value, also)
13 20
 
14 21
 By keeping the rules simple, the programmer's task is made simpler, letting them instead spend time on the complicated things that are necessary. Yes, maybe it might be easier to use json or other structured variable type parser/formatter, however, this syntax is so simple the parser is barely more wordy than using the libraries as commonly used.

+ 4
- 2
doc/overview.md View File

@@ -82,10 +82,12 @@ Any application built with Tri implicitly has a data directory (defaulting to ap
82 82
 
83 83
    Deletes configuration file, then exits. Future runs will then start from defaults. Configuration files only store values that are not default.
84 84
 
85
-3. `save`
85
+2. `save`
86 86
    
87 87
    At the end of successful parse of config and CLI args, the new state is persisted into the configuration file.
88 88
 
89
-Note that both of these triggers will be overridden if explicitly specified in the declaration, should a specific further effect be required and  these names are desired to be used. They do not have short versions to conserve names for the application's purposes.
89
+3. `defaults`
90
+
91
+   Defaults will print the entire set of names as they would appear in the configuration, with their default values afterwards, with one prefix tab grouping command items and two prefix tabs grouping items in lists (if default of this array element *has* more than one item).
90 92
 
91 93
 Also note that logging configuration is not handled by default, nor is there a parser for it. If the application needs these configurations, the handler must be written by the developer to fit the system they are using. I recommend the logger I wrote, found within the Parallelcoin `pod` repository, [located here](https://github.com/parallelcointeam/pod/tree/master/pkg/util/clog).

Loading…
Cancel
Save