====== Output collection ======


**Express Generator** saves the collections under the ''.\collections'' directory.

The default exports name contains information for the market, the data update time and the count of the strategies.

Here is an example collection exported with the default settings:


    .\collections\Coll_Premium_Data_EURUSD_M30_2023-07-03_str_100.json

{{ :express-generator:express-generator-output-collection.png?nolink |Express Generator - Output collection}}


The collections are saved in JSON format with the corresponding ''.json'' file extension.


===== Notes =====

The file system delimiters are different for the different operational systems.

Windows uses the backslash character for the directory delimiter: ''\''.

Linux and MacOS use a forward slash: ''/''.

Normally both work for Windows, but using the correct character is a good practice.

  * Example for Windows: ''.\collections\my-collection.json''.

  * Example for Linux and MacOS: ''./collections/my-collection.json''.


===== Output parameter =====

We can control the export path with the ''output'' option. The ''output'' option accepts a relative path for the exported file with or without a file extension.

For example, all the following settings save the collection in the ''.\collections\my-collection-name.json'' file.

<code ini>
    output = .\collections\my-collection-name.json
    output = .\collections\my-collection-name
    output = collections\my-collection-name.json
    output = collections\my-collection-name
    output = my-collection-name.json
    output = my-collection-name
    
    ; => .\collections\my-collection-name.json
</code>

We can also specify a sub-directory path.
Example for saving the collection under the ''.\collections\validated'' folder.

<code ini>
    output = .\collections\validated\my-collection-name.json
    output = validated\my-collection-name.json
    output = validated\my-collection-name
    
    ; => .\collections\validated\my-collection-name.json
</code>


===== Placeholders =====

The ''output'' command accepts placeholders, which will be replaced with actual values during the collection export.

The available placeholders are:

<code ini>
    [SERVER] - the data server
    [SYMBOL] - the data symbol
    [PERIOD] - the data period
    [YEAR]   - the data update time year
    [MONTH]  - the data update time month
    [DAY]    - the data update time day
    [COUNT]  - the count of the included strategies
    [PROFIT] - the total profit of the included strategies
</code>

The default pattern of the ''output'' parameter is:

<code ini>
    output = ./collections/Coll_[SERVER]_[SYMBOL]_[PERIOD]_[YEAR]-[MONTH]-[DAY]_str_[COUNT].json
    
    ; => .\collections\Coll_Premium_Data_EURUSD_M30_2023-07-01_str_100.json
</code>

We can use any combination of the placeholders to give a proper name to our collections.

Useful combinations are:

  * set the market in the collection name:

<code ini>
    output = my-collection_[SERVER]_[SYMBOL]_[PERIOD]
    
    ; => .\collections\my-collection_Premium_Data_EURUSD_M30.json
</code>

  * arrange the collections in sub-directories by market:

<code ini>
    output = [SERVER]\[SYMBOL]\[PERIOD]\my-collection.json
    
    ; => .\collections\Premium_Data\EURUSD\M30\my-collection.json
</code>

  * store the collections in sub-directories by data time. We can use the market's information in the actual collection name:

<code ini>
    output = [YEAR]\[MONTH]\[DAY]\collection_[SERVER]_[SYMBOL]_[PERIOD].json
    
    ; => .\collections\2023\07\01\collection_Premium_Data_EURUSD_M30.json
</code>


===== Suffix =====

**Express Generator** tries to prevent the collections from overwriting.

It adds a suffix to the collection filename if a file with the same name already exists.

This will result if we run the Generator four times with the ''output = my-collection-name'' option.

    .\collections\my-collection-name.json
    .\collections\my-collection-name_(1).json
    .\collections\my-collection-name_(2).json
    .\collections\my-collection-name_(3).json


===== Replace existing collection =====

Sometimes it is useful to replace an existing collection name. Such a case is when we want a fixed collection name for further validation.

The option ''output_replace'' controls the behaviour of Express Generator when a collection file already exists.

  * Do not overwrite an existing file. Add a suffix to the new collection filename:

<code ini>
  output_replace = false
</code>

  * Replace an existing collection file:

<code ini>
  output_replace = true
</code>

===== Default settings =====

The ''output'' and the ''output_replace'' parameters are in the **Collection output** section in the ''gen.settings.ini'' file.

<code ini>
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Output collection        ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Collection's filename for a newly generated or validated Collection.
; Possible placeholders: [SERVER], [SYMBOL], [PERIOD], [YEAR], [MONTH], [DAY], [COUNT], [PROFIT]
; Placeholders can be used as directory names too.
; Example: output = ./collections/[SERVER]/[SYMBOL]/[PERIOD]/collection.json
output = ./collections/Coll_[SERVER]_[SYMBOL]_[PERIOD]_[YEAR]-[MONTH]-[DAY]_str_[COUNT].json

; When 'false', it adds a suffix to the collection file if it already exists.
; When 'true', it overwrites the file.
output_replace = false

</code>