]> lifelog.hopto.org Git - LifeLog.git/commitdiff
New help doco.
authorWill Budic <redacted>
Thu, 21 Sep 2023 06:47:53 +0000 (16:47 +1000)
committerWill Budic <redacted>
Thu, 21 Sep 2023 06:47:53 +0000 (16:47 +1000)
htdocs/cgi-bin/docs/PerlCNF/PerlCNFConstantAnonExplained.md [new file with mode: 0644]

diff --git a/htdocs/cgi-bin/docs/PerlCNF/PerlCNFConstantAnonExplained.md b/htdocs/cgi-bin/docs/PerlCNF/PerlCNFConstantAnonExplained.md
new file mode 100644 (file)
index 0000000..1b12e8e
--- /dev/null
@@ -0,0 +1,159 @@
+# PerlCNF Constant, Anon, Values and Data Types Explained
+
+    CNF has so called instructional property name value pairs.
+    This document delves a little bit further into explaining them, how and why are as such implemented.
+
+## Instructual Types
+
+    1. Data type of values is determined and implemented by computer language doing the interpretation.
+    2. These data types must cover maximums, like 64 bit Integer for numbers, and String of UTF 8 unicode base as the minimum.
+    3. The following are instructional value types CNF must cover.
+        1. Constant
+        2. Anon
+        3. Collections
+        5. Data
+
+## Constant
+
+A CNF Constant is as the name suggests, can't be changed once declared in the configuration.
+There are additional rules with these constants.
+
+    * They are private settings to every instance of the Parser, hence not global.
+    * They can be declared only once.
+        - Subsequent parsing of scripts and includes, by the same Parser will issue warnings or exceptions.
+    * They must be present in the configuration, otherwise an Application can't function.
+        - The Application might provide itself inbuilt defaults, but that is now considered bad practice.
+    * Constant is preferred and recommended setting requirement for further CNF properties settings like, special instructions or plugins.
+    * Can be shortened to **CONST**.
+
+Accessed best is via method:
+
+        ```PERL
+        $parser->const('ThreadPoolSize');
+        ```
+
+Or directly with:
+
+        ```PERL
+        $parser->{'ThreadPoolSize'};
+        ```
+
+### CNF Basic Format
+
+    ```CNF
+
+    #This is the number of threads to make available as workers.
+    <<ThreadPoolSize<CONSTANT>10>>
+    ```
+
+### CNF Multiline Format
+
+Quotes are not necessary in CNF, they get trimmed if present.
+Constants can't be further instructional, as the reserved word CONSTANT or CONST is the instruction.
+
+
+```CNF
+
+<<<CONSTANT
+    TreadPoolSize = 10
+    TreadWaitTime = 3000
+    DEBUG         = yes
+>>>
+```
+
+## Anon
+
+    A CNF anon is the variable version of a property and value.
+    They are in nature of no concern to the Parser and can be overwritten or omitted from a script.
+    Hence their name.
+
+    * They are a composite to the parser and considered global and public by default.
+    * Setting parser to ANONS_ARE_PUBLIC => 0, will make them private.
+        - Private or the Parser instance will have only its own Anon's assigned.
+    * Anon instructional type is also considered also to be the basic form of an CNF property.
+
+Accessed for value only via method:
+
+```Perl
+$parser->anon('CurrentDate');
+```
+
+### Basic Format
+
+```CNF
+#Check is logs need trimming.
+<<CheckLogsOnStartup<1>>>
+#Assign current date the Parse has parsed this script.
+<<CurrentDate<DATE>now>>
+<<ReleaseDate<DATE>2023-09-21 10:57:44>>
+```
+
+### Multiline Format
+
+Since version 2.8, multiline format can also be used with the VAR or VARIABLE instruction.
+But only for simple property value pairs.
+Anons which are instructional must be scripted standalone.
+
+```CNF
+<<<VARIABLE
+    CheckLogsOnStartup = 1
+    AppName = "  Application ACME Removals PTY LTD   "
+    AppLabel =   This line of text will be trimmed but not at the end.
+    ...
+>>>
+```
+
+## CNF Property
+
+    A CNF property is in simplest form a anon, but also is a complex instruction value, like a collection.
+    Or a processed data value, will come from a property.
+    Collections will be processed in form of a property to.
+
+
+## Format
+
+```CNF
+<<MyProperty<SOME_INSTRUCTION>
+    ...The Property Body...
+>>
+```
+
+## Type Of Collections
+
+    There is three type of collections.
+    Convention is to prefix collection property name with the instruction signifier of either **@** or **%**.
+    The list signifier is a **$$** postfix to the name.
+
+1. Array type.
+    ```CNF
+        <<@SomeList<@>
+            Blue,
+            Red,
+            Green
+        >>
+    ```
+
+2. Hash Type.
+    ```CNF
+        <<%SomeHash<%>
+           Blue  = #0000FF
+           Red   = #FF0000
+           Green = #008000
+        >
+    ```
+
+    ```PERL
+       my $list = $parser->collection('@SomeList');
+       my $hash = %{$parser->collection('%SomeHash')};
+    ```
+
+
+3. List Type
+    1. Collections as named list so can be scripted into multiple properties or files (includes).
+        ```CNF
+        <<MyList$$<@>1,3,5,9,13>>
+        <<MyList$<@>19,23,113>>
+        ```
+    ```PERL
+       my $list = $parser->list('MyList');
+    ```