====== Export Configuration ======
''[[dir:exec]]/exportcfg.js'' is a utility script that will export lists of items configured in SCFG (e.g. message areas, files areas, external program configurations) to the console or a file.

===== Usage =====
''exportcfg.js'' may be invoked via [[util:JSexec]] (e.g. from an OS command prompt) or ''load()ed'' from another JavaScript module.

==== Syntax ====
The command-line syntax (or ''load'' arguments) are detailed here:

<code>
usage: exportcfg.js <cfg-type>
        [[-grp=<msg_area.grp.name | file_area.lib.name | xtrn_area.sec.code>] [...]]
        [[-inc=<internal_code> | -exc=<internal_code>] [...]]
        [-<option>[=<value>] [...]]
        [[[property][=<printf-format> [-upper | -lower | -under]] [...]]
        [[-ex=<property>] [...]]

cfg-types (choose one):
        msg-grps
        msg-subs
        file-libs
        file-dirs
        file-prots
        file-extrs
        file-comps
        file-viewers
        file-testers
        file-dlevents
        xtrn-secs
        xtrn-progs
        xtrn-events
        xtrn-editors

options:
        <option>     <default>
        -hdr         =false
        -ini         =false
        -delim       ="\u0009"
        -term        =""
        -quote       =false
        -strip       =false
        -ascii       =false
        -quiet       =false
        -sort        =false
        -json        =false
        (tip: use -json=4 for pretty JSON output)
        (tip: use -ini='\t%s = %s\n' for pretty .ini output)

per-property options:
        <option>     <default>
        -upper       =false
        -lower       =false
        -under       =false
</code>

=== cfg-type ===
A configuration type (just one) must be specified on the command-line:

^ cfg-type     ^ Description ^
| ''[[http://synchro.net/docs/jsobjs.html#msg_area.grp_list_properties|msg-grps]]''              | Message Groups |
| ''[[http://synchro.net/docs/jsobjs.html#msg_area.grp_list.sub_list_properties|msg-subs]]''     | Message Sub-boards |
| ''[[http://synchro.net/docs/jsobjs.html#file_area.lib_list_properties|file-libs]]''            | File Libraries |
| ''[[http://synchro.net/docs/jsobjs.html#file_area.lib_list.dir_list_properties|file-dirs]]''   | File Directories |
| ''file-prots''                                                                                 | File Transfer Protocols |
| ''file-extrs''                                                                                 | File Extractors |
| ''file-comps''                                                                                 | File Compressors |
| ''file-viewers''                                                                               | File Viewers |
| ''file-testers''                                                                               | File Testers |
| ''file-dlevents''                                                                              | File Download Events |
| ''[[http://synchro.net/docs/jsobjs.html#xtrn_area.sec_list_properties|xtrn-secs]]''            | External Program Sections |
| ''[[http://synchro.net/docs/jsobjs.html#xtrn_area.sec_list.prog_list_properties|xtrn-progs]]'' | External Programs (doors) |
| ''[[http://synchro.net/docs/jsobjs.html#xtrn_area.event_properties|xtrn-events]]''             | External Timed Events |
| ''[[http://synchro.net/docs/jsobjs.html#xtrn_area.editor_properties|xtrn-editors]]''           | External Message Editors |

==== Filtering ====

By default, ''exportcfg.js'' outputs **all** properties for **all** configured items of the chosen ''cfg-type''.

To choose which //groups// (Message Groups, File Libraries, or External Program Sections) from which to output configured items, use the ''-grp'' option. You can use the ''-grp'' option multiple times to specify multiple groups from which to output items. The groups of items will be output in their configured order (unless the ''-sort'' option is used), regardless of the order of the groups specified on the command-line.
  jsexec exportcfg.js msg-subs -grp main

To chose which configuration //properties// to **include** in the output, pass one or more property names on the command-line (without any dashes). The properties may be specified in any order and their values will be output in the order given.
  jsexec exportcfg.js msg-subs code name description
  
Alternatively, you can **exclude** specific properties from the output by specifying one or more property names with the ''-ex'' option.
  jsexec exportcfg.js msg-subs -ex=can_read -ex=can_post -ex=is_operator -ex=is_moderated -ex=scan_ptr -ex=scan_cfg -ex=last_read

By default, all //items// (objects) within the chosen configuration area are **included** in the output. To chose which items to include in the output, use the ''-inc'' option to specify the //internal code// of an item to include in the output. The ''-inc'' option may be used multiple times to specify multiple items to include.
  jsexec exportcfg.js msg-subs -inc=syncdata 

To **exclude** specific configuration items (objects) from the output, you can use the ''-exc'' option. The ''-exc'' option may be used multiple times to specify multiple items to exclude from the output.
  jsexec exportcfg.js msg-subs -exc=syncdata 
==== Output format ====
''exportcfg.js'' supports 3 primary flavors of text output:
  * one line per record (the default)
  * [[http://www.json.org|JSON]]
  * ''.ini'' file format

Other output formats could be coaxed out of this script through creative use of the ''-delim'' and ''-term'' command-line options.

To modify the default output mode, use the following command-line options:

^ Option     ^ Default Value ^ Description ^
| ''-hdr''   | ''false''     | Add a //header// line to the output, identifying each column's property name |
| ''-delim'' | ''\t''        | Specify a property //delimiter// (string of one or more characters) for the output (default: a //horizontal-tab// character) |
| ''-term''  |               | Specify a record/item //terminator// for the output (default: //none//) |

=== Values ===
Configuration property values may be modified by including any of the following options on the command-line:
^ Option     ^ Default Value ^ Description ^
| ''-quote'' | ''false''     | Encode quotes and other special characters in property string values (via ''JSON.stringify'') |
| ''-strip'' | ''false''     | Remove control characters and [[custom:Ctrl-A codes]] from string values |
| ''-ascii'' | ''false''     | Convert CP437 (extended-ASCII) characters in string values to ASCII equivalents |

Configuration property values may be modified on a per-property basis by including any of the following options on the command-line following a property specification:
^ Option     ^ Default Value ^ Description ^
| ''-upper'' | ''false''     | Convert strings to all upper-case letters |
| ''-lower'' | ''false''     | Convert strings to all lower-case letters |
| ''-under'' | ''false''     | Convert spaces in strings to the underscore character (''_'') |

Configuration property values may be truncated, padded, or aligned using C ''printf'' style format strings by specifying a format string following a property specification, separated by an equal-sign (''='') character:
  name="%-30s "
JavaScript-escaped special characters may be included in the format string:
  name="\t%30s "
  
==== Output order ====  

The default output order of the configuration items is the order in which they appear in the configuration files and are represented in [[util:SCFG]].

To alphabetically sort the output items, use the ''-sort'' command-line option.

==== Output control ====  

By default, all output is printed on the console (e.g. sent to //stdout// or the BBS [[server:terminal]] user). To disable the console output use the ''-quiet'' command-line option.
This //quiet// mode is useful when ''load()''ing the module and capturing its output as the return value of ''load()'' (e.g. for writing to a file without requiring OS shell redirection).

===== Examples =====

**Note:**\\
By default, [[util:JSexec]] will change the current working directory to your
Synchronet ''[[dir:ctrl]]'' directory before executing the script, so the redirected
output (stdout) of the example commands above would go into files created
there. To write output files to a different directory, either specify the
**full** path or use the ''jsexec -C'' command-line option to disable the
change-directory function.

==== areas.bbs ====
To export configured message areas (sub-boards) to a FidoNet-style ''areas.bbs'' file:
  jsexec -C exportcfg msg-subs -grp fidonet code="%-16s" name="%-35s" -upper -under -term=" 1:103/705" > areas.bbs
or:
  jsexec -C exportcfg msg-subs -grp fidonet code="%-16s" newsgroup="%-35s" -upper -under -term=" 1:103/705" > areas.bbs
  
See also: ''[[dir:exec]]/[[echoareas]].js''.

==== filegate.zxx ====
To export configured file areas (directories) to a RAID/FILEBONE.NA/FILEGATE.ZXX format file:
  jsexec -C exportcfg file-dirs code="Area %-16s 0 !" -upper description > filegate.zxx
  
==== csv ====
To export configured external online programs (doors) to a comma-separated-value file suitable for loading into a spreadsheet application:
  jsexec -C exportcfg xtrn-progs -delim=, -quote > xtrn-progs.csv
  
==== tab ====
To export configured message areas (sub-boards) to a tab-delimited ASCII file (with column headings) suitable for loading into a spreadsheet application:
  jsexec -C exportcfg msg-subs -strip -ascii -hdr > msg-subs.tab

==== json ====
To export configured file areas (directories) to a pretty-formatted JSON file:
  jsexec -C exportcfg file-dirs -json=4 > file-dirs.json
  
==== ini ====
To export configured external message editors to a pretty-formatted ''.ini'' file:
  jsexec -C exportcfg xtrn-editors -ini="\t%s = %s\n" > xtrn-editors.ini

==== load ====
To load this module from another JavaScript module and capture the output (as an array of strings):
  var output = load({}, "exportcfg.js", "file-dirs", "-quiet");
  
===== See Also =====
  * [[module:importcfg|Import Configuration]]
  * [[:module:|Modules]]

{{tag>javascript export json .ini csv fidonet jsutil}}
