Merge pull request #17 from lexakimov/feature

0.9.0

Author: lexakimov

CONFIGURATION.md

@@ -5,6 +5,25 @@
 
 This guide will help you understand how to configure `xmlgenerator`.
 
+* [Basic usage](#basic-usage)
+* [Configuration](#configuration)
+  * [Customizing the generation of elements and values](#customizing-the-generation-of-elements-and-values)
+    * [Probability of adding optional attributes](#probability-of-adding-optional-attributes)
+    * [Limiting the number of elements](#limiting-the-number-of-elements)
+    * [Limiting string length](#limiting-string-length)
+    * [Limiting the range for numeric values](#limiting-the-range-for-numeric-values)
+  * [Overriding values](#overriding-values)
+    * [By tag/attribute name](#by-tagattribute-name)
+    * [By regular expression for tag/attribute name](#by-regular-expression-for-tagattribute-name)
+    * [Using built-in functions to generate values](#using-built-in-functions-to-generate-values)
+    * [Declaring and using local and global variables](#declaring-and-using-local-and-global-variables)
+  * [Configuring output filenames](#configuring-output-filenames)
+  * [Applying settings for groups of documents](#applying-settings-for-groups-of-documents)
+    * [Configuration Example](#configuration-example)
+  * [Appendix 1: Configuration File Structure](#appendix-1-configuration-file-structure)
+  * [Appendix 2: Placeholder Functions](#appendix-2-placeholder-functions)
+
+
 ## Basic usage
 
 Let's start with the simplest scenario: generating an XML document from a single XSD schema and printing the result to the console.
@@ -65,7 +84,6 @@ To demonstrate, we will use the [order.xsd](examples/order.xsd) schema, which de
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
   <xs:element name="order">
     <xs:complexType>
       <xs:sequence>
@@ -103,7 +121,6 @@ To demonstrate, we will use the [order.xsd](examples/order.xsd) schema, which de
       <xs:attribute name="status" type="xs:string" use="optional"/>
     </xs:complexType>
   </xs:element>
-
 </xs:schema> 
 ```
 
@@ -266,7 +283,7 @@ You can set a value for a field by specifying its exact name.
 ```yaml
 global:
   value_override:
-    # A value of "31" will be set for all <age> elements
+    # A value of "31" will be set for all <age> elements and attributes
     age: "31"
 ```
 
@@ -317,7 +334,7 @@ xmlgenerator -c config.yml --pretty examples/employee.xsd
 </employee>
 ```
 
-#### Using built-in functions
+#### Using built-in functions to generate values
 
 The most powerful method is to use placeholders like `{{ function }}` to substitute data generated by built-in functions.
 
@@ -350,6 +367,29 @@ xmlgenerator -c config.yml --pretty examples/employee.xsd
 
 *A full list of available functions is provided in [Appendix 2](#appendix-2-placeholder-functions)*.
 
+#### Declaring and using local and global variables
+
+If you need to reuse a generated value, you can declare variables in the `variables` block and reference them using the `local` and `global` functions.
+
+Values of variables declared in `variables.global` are evaluated from the specified expressions once (on first access) and then reused throughout the entire generation process when referenced via `global('key')`.
+
+Values of variables declared in `variables.local` are evaluated from the specified expressions and then reused within the generation of a single document when referenced via `local('key')`.
+
+
+**`config.yml` configuration:**
+```yaml
+variables:
+  global:
+    shared_id: "{{ uuid }}"
+  local:
+    document_code: "prefix_{{ source_extracted }}-{{ uuid }}"
+
+global:
+  value_override:
+    someAttribute1: "{{ global('shared_id') }}"
+    someAttribute2: "{{ local('document_code') }}"
+```
+
 ### Configuring output filenames
 
 The `output_filename` parameter allows you to set a template for the names of generated files. This is especially useful when processing multiple schemas where the results need to be saved to a single directory. Placeholders can also be used in the template.
@@ -482,12 +522,27 @@ Thus, the `specific` section provides a powerful mechanism for fine-tuning gener
 ### Appendix 1: Configuration File Structure
 
 ```yaml
+# Optional block for variables, accessible as `{{ global('name') }}` and `{{ local('name') }}`.
+variables:
+  # variable values are evaluated from the specified expressions once (on first access) and then
+  # reused on access via `global('name')`.
+  global:
+    invoice_id: "{{ uuid }}"
+    # You can also reference other variables here via local() and global(). Avoid circular dependencies!
+    batch_name: "{{ global('invoice_id') }}-{{ number(1, 10) }}"
+  # variable values are evaluated from the specified expressions and then reused within the generation
+  # of a single document when accessed via `local('name')`.
+  local:
+    customer_prefix: "{{ source_extracted }}"
+    # You can also reference other variables here via local() and global(). Avoid circular dependencies!
+    customer_id: "{{ local('customer_prefix') }}-{{ uuid }}"
+
 # Global settings (apply to all schemas)
 global:
 
   # Regular expression to extract a substring from the source xsd schema filename.
   # The extracted substring can be used via the `source_extracted` function.
-  # The regular expression must contain the group `extracted`.
+  # The regular expression must contain the named group `(?P<extracted>...)`.
   # Default value: `(?P<extracted>.*).(xsd|XSD)` (extracts the filename without extension).
   source_filename: ...
 
@@ -517,9 +572,6 @@ global:
   # Key - string or regular expression to match the tag/attribute name.
   # Value - string with optional use of placeholders:
   # `{{ function }}` - substitutes the value provided by the predefined function.
-  # `{{ function | modifier }}` - same, but with a modifier [ global | local ].
-  # - `global` - a single value will be used for the entire generation process.
-  # - `local` - a single value will be used within the context of the current document.
   #
   # The list of available functions is below.
   # The order of entries matters; the first matching override will be selected.
@@ -547,6 +599,7 @@ specific:
       # override the value set by the global configuration
       name_regexp_1: "static value"
       # reset overrides for tags/attributes containing 'name' set by the global configuration
+      # a random value will be generated
       name:
 ```
 
@@ -560,13 +613,12 @@ Configuration Priority:
 
 In the `value_override` sections, you can specify either a string value or special placeholders:
 
-- `{{ function }}` - Substitutes the value provided by the predefined function.
-- `{{ function | modifier }}` - Same, but with a modifier `[ global | local ]`, where:
-    - `global`: The function will generate and use *the same single value* throughout the *entire generation process*
-      for all documents.
-    - `local`: The function will generate and use *the same single value* within the scope of *a single generated
-      document*.
-    - No modifier: A new value is generated each time the function is called.
+- `{{ function }}` - substitutes the value provided by the predefined function.
+- `{{ global('name') }}` - gets a value of the predefined global variable `name` (configured in the `variables` block);
+  the value is generated once per process on first use.
+- `{{ local('name') }}` - gets a value of the predefined local variable `name` (configured in the `variables` block);
+  the value is recalculated for each generated document. Built-in context values such as `root_element`,
+  `source_filename`, `source_extracted`, and `output_filename` are also available through `local()`.
 
 **List of Placeholder Functions:**
 
@@ -576,6 +628,8 @@ In the `value_override` sections, you can specify either a string value or speci
 | `source_extracted`                 | A string extracted from the source XSD filename using the regex specified in `source_filename`.          |
 | `output_filename`                  | String defined by the `output_filename` configuration parameter.                                         |
 | `root_element`                     | The name of the root element of the XML document.                                                        |
+| `local('name')`                    | Value of the local variable `name` (configured under `variables.local` or built-in context values).      |
+| `global('name')`                   | Value of the global variable `name` (configured under `variables.global`).                               |
 | `uuid`                             | A random UUIDv4.                                                                                         |
 | `regex("pattern")`                 | A random string value matching the specified regular expression.                                         |
 | `any('A', "B", C)`                 | A random value from the provided enumeration.                                                            |
@@ -602,4 +656,4 @@ In the `value_override` sections, you can specify either a string value or speci
 | `kpp`                              | Tax Registration Reason Code (KPP).                                                                      |
 | `snils_formatted`                  | SNILS (Personal Insurance Account Number) formatted as `123-456-789 90`.                                 |
 
-\* It's available to set custom locale via `func("ru_RU")`. Default locale is `en_US`</td></tr>
+\* For functions marked with an asterisk, you can specify a locale, for example: `first_name("ru_RU")`. The default locale is `en_US`.