excel-list-transform 0.5__py3-none-any.whl

excel_list_transform/generate_cfg.py

@@ -0,0 +1,374 @@
+#! /usr/local/bin/python3
+"""Generate example configuration files."""
+
+# Copyright (c) 2024 Tom Björkholm
+# MIT License
+
+
+from excel_list_transform.file_extension import fix_file_extension
+from excel_list_transform.config_enums import ColumnRef, FileType, \
+    RewriteKind, CaseSensitivity, ExcelLib
+from excel_list_transform.config_factory import config_factory_from_enum
+from excel_list_transform.generate_txt import generate_syntax_txt
+from excel_list_transform.config_xls_list_refmt_name import \
+    ConfigXlsListRefmtName
+from excel_list_transform.config_xls_list_refmt_num import \
+    ConfigXlsListRefmtNum
+
+syntax_o2x_common: str = '''
+
+Column names are changed from another language (Swedish) and sometimes from
+a more instuctive naming to the names understood by RRS.
+
+The events does not use divisions, boat names and WhatsApp. Thus the
+form did not ask for these. They are inserted as empty columns to please
+RRS.
+
+The phone number has to be in international format '+' followed by only
+digits for RRS, but the sailors filling in the form sometimes use
+national format (no + and no country code). Also the sailors filling
+in the form are used to group digits by dashes and spaces for easy
+reading. The s7_rewrite_columns include rewrite instructions to
+"fix" the phone number to the format needed by RRS.
+The rewriting of phone numbers in this example is for Swedish mobile
+phone numbers. For other countries s7_rewrite_columns need to be
+adjusted.
+'''
+
+syntax_only_o2r_common: str = '''
+This an example of taking a registration list from the excel file received
+from office forms or google forms and transforming it for importing into
+RRS ( https://www.racingrulesofsailing.org ).
+'''
+
+by_name_common: str = '''
+
+s8_column_order both tells the order the columns shall be written
+in, and what columns to write out. The columns not listed here
+are ignored (and thus removed from the output).
+
+This configuration files references columns "BY_NAME", which is the
+preferred way to reference columns.
+'''
+
+by_number_common: str = '''
+
+This configuration files references columns "BY_NUMBER".
+The preferred way to reference columns in configuration files
+is "BY_NAME".
+'''
+
+syntax_o2r_common: str = syntax_only_o2r_common + syntax_o2x_common
+
+
+def generate_syntax_o2r_name(filename: str, colref: ColumnRef) -> None:
+    """Generate config example for office_forms_to_rrs."""
+    assert colref == ColumnRef.BY_NAME
+    cfg = ConfigXlsListRefmtName()
+    cfg.out_excel_library = ExcelLib.OPENPYXL
+    cfg.in_type = FileType.EXCEL
+    cfg.out_type = FileType.EXCEL
+    cfg.s1_split_columns = []
+    cfg.s3_merge_columns = []
+    cfg.s5_rename_columns = [
+        {'column': 'Klass', 'name': 'Class'},
+        {'column': 'Nationalitetsbokstäver i seglet', 'name': 'Nationality'},
+        {'column': 'Segelnummer (endast siffror)', 'name': 'Sail Number'},
+        {'column': 'Förnamn', 'name': 'First Name'},
+        {'column': 'Efternamn', 'name': 'Last Name'},
+        {'column': 'Klubb', 'name': 'Club Name'},
+        {'column': 'Epostadress', 'name': 'Email'},
+        {'column': 'Mobiltelefonnummer', 'name': 'Phone'}]
+    cfg.s6_insert_columns = [
+        {'column': 'Division', 'value': None},
+        {'column': 'Boat Name', 'value': None},
+        {'column': 'WhatsApp', 'value': None}]
+    cfg.s7_rewrite_columns = [
+        {'column': 'Phone', 'kind': RewriteKind.STRIP,
+         'chars': '', 'case': CaseSensitivity.IGNORE_CASE},
+        {'column': 'Phone', 'kind': RewriteKind.REMOVECHARS,
+         'chars': [' ', '-'], 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 'Phone', 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^07', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 'Phone', 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^\\+4607', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 'Phone', 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^467', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 'Phone', 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^4607', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE}]
+    cfg.s8_column_order = ['Class', 'Division', 'Nationality',
+                           'Sail Number', 'Boat Name', 'First Name',
+                           'Last Name', 'Club Name', 'Email', 'Phone',
+                           'WhatsApp']
+    cfg.write(to_json_filename=filename)
+
+
+TXT_O2R_NAME = syntax_o2r_common + by_name_common
+
+
+def generate_syntax_o2r_num(filename: str, colref: ColumnRef) -> None:
+    """Generate config example for office_forms_to_rrs."""
+    assert colref == ColumnRef.BY_NUMBER
+    cfg = ConfigXlsListRefmtNum()
+    cfg.out_excel_library = ExcelLib.OPENPYXL
+    cfg.in_type = FileType.EXCEL
+    cfg.out_type = FileType.EXCEL
+    cfg.s1_split_columns = []
+    cfg.s2_remove_columns = [0, 1, 2, 3, 4, 5, 14, 15, 16, 17, 18, 19]
+    cfg.s3_merge_columns = []
+    cfg.s4_place_columns_first = [5, 6, 7, 0, 1, 4, 2, 3]
+    cfg.s5_rename_columns = [
+        {'column': 0, 'name': 'Class'},
+        {'column': 1, 'name': 'Nationality'},
+        {'column': 2, 'name': 'Sail Number'},
+        {'column': 3, 'name': 'First Name'},
+        {'column': 4, 'name': 'Last Name'},
+        {'column': 5, 'name': 'Club Name'},
+        {'column': 6, 'name': 'Email'},
+        {'column': 7, 'name': 'Phone'}]
+    cfg.s6_insert_columns = [
+        {'column': 1, 'name': 'Division', 'value': None},
+        {'column': 4, 'name': 'Boat Name', 'value': None},
+        {'column': 10, 'name': 'WhatsApp', 'value': None}]
+    cfg.s7_rewrite_columns = [
+        {'column': 9, 'kind': RewriteKind.STRIP,
+         'chars': '', 'case': CaseSensitivity.IGNORE_CASE},
+        {'column': 9, 'kind': RewriteKind.REMOVECHARS,
+         'chars': [' ', '-'], 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 9, 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^07', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 9, 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^\\+4607', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 9, 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^467', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 9, 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^4607', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE}]
+    cfg.write(to_json_filename=filename)
+
+
+TXT_O2R_NUM = syntax_o2r_common + by_number_common
+
+syntax_only_o2s_common: str = '''
+This an example of taking a registration list from the excel file received
+from office forms or google forms and transforming it for importing into
+SailWave regatta scoring program ( https://www.sailwave.com ).
+'''
+
+syntax_o2s_common: str = syntax_only_o2s_common + syntax_o2x_common
+
+
+def generate_syntax_o2s_name(filename: str, colref: ColumnRef) -> None:
+    """Generate config example for office_forms_to_sw."""
+    assert colref == ColumnRef.BY_NAME
+    cfg = ConfigXlsListRefmtName()
+    cfg.out_excel_library = ExcelLib.OPENPYXL
+    cfg.in_type = FileType.EXCEL
+    cfg.out_type = FileType.CSV
+    cfg.s1_split_columns = []
+    cfg.s3_merge_columns = [{'columns': ['Förnamn', 'Efternamn'],
+                             'separator': ' '}]
+    cfg.s5_rename_columns = [
+        {'column': 'Klass', 'name': 'Class'},
+        {'column': 'Nationalitetsbokstäver i seglet', 'name': 'Nat'},
+        {'column': 'Segelnummer (endast siffror)', 'name': 'SailNo'},
+        {'column': 'Förnamn', 'name': 'HelmName'},
+        {'column': 'Klubb', 'name': 'Club'},
+        {'column': 'Epostadress', 'name': 'HelmEmail'},
+        {'column': 'Mobiltelefonnummer', 'name': 'HelmPhone'}]
+    cfg.s6_insert_columns = [
+        {'column': 'Division', 'value': None},
+        {'column': 'Boat', 'value': None}]
+    cfg.s7_rewrite_columns = [
+        {'column': 'HelmPhone', 'kind': RewriteKind.STRIP,
+         'chars': '', 'case': CaseSensitivity.IGNORE_CASE},
+        {'column': 'HelmPhone', 'kind': RewriteKind.REMOVECHARS,
+         'chars': [' ', '-'], 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 'HelmPhone', 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^07', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 'HelmPhone', 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^\\+4607', 'to': '+467',
+         'case': CaseSensitivity.MATCH_CASE},
+        {'column': 'HelmPhone', 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^467', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 'HelmPhone', 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^4607', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE}]
+    cfg.s8_column_order = ['Class', 'Division', 'Nat', 'SailNo', 'Boat',
+                           'HelmName', 'Club', 'HelmEmail', 'HelmPhone']
+    cfg.write(to_json_filename=filename)
+
+
+TXT_O2S_NAME = syntax_o2s_common + by_name_common
+
+
+def generate_syntax_o2s_num(filename: str, colref: ColumnRef) -> None:
+    """Generate config example for office_forms_to_sw."""
+    assert colref == ColumnRef.BY_NUMBER
+    cfg = ConfigXlsListRefmtNum()
+    cfg.out_excel_library = ExcelLib.OPENPYXL
+    cfg.in_type = FileType.EXCEL
+    cfg.out_type = FileType.CSV
+    cfg.s1_split_columns = []
+    cfg.s2_remove_columns = [0, 1, 2, 3, 4, 5, 14, 15, 16, 17, 18, 19]
+    cfg.s3_merge_columns = [{'columns': [0, 1], 'separator': ' '}]
+    cfg.s4_place_columns_first = [4, 5, 6, 0, 3, 1, 2]
+    cfg.s5_rename_columns = [
+        {'column': 0, 'name': 'Class'},
+        {'column': 1, 'name': 'Nat'},
+        {'column': 2, 'name': 'SailNo'},
+        {'column': 3, 'name': 'HelmName'},
+        {'column': 4, 'name': 'Club'},
+        {'column': 5, 'name': 'HelmEmail'},
+        {'column': 6, 'name': 'HelmPhone'}]
+    cfg.s6_insert_columns = [
+        {'column': 1, 'name': 'Division', 'value': None},
+        {'column': 4, 'name': 'Boat', 'value': None}]
+    cfg.s7_rewrite_columns = [
+        {'column': 8, 'kind': RewriteKind.STRIP,
+         'chars': '', 'case': CaseSensitivity.IGNORE_CASE},
+        {'column': 8, 'kind': RewriteKind.REMOVECHARS,
+         'chars': [' ', '-'], 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 8, 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^07', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 8, 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^\\+4607', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 8, 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^467', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 8, 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^4607', 'to': '+467', 'case': CaseSensitivity.MATCH_CASE}]
+    cfg.write(to_json_filename=filename)
+
+
+TXT_O2S_NUM = syntax_o2s_common + by_number_common
+
+
+syntax_r2s_common: str = '''
+This an example of taking a registration list from the excel file
+exported from RRS ( https://www.racingrulesofsailing.org ) and
+transforming it for importing into SailWave regatta scoring
+program ( https://www.sailwave.com ).
+
+The names of the columns are changed from RRS names to SailWave
+names. The phone number exported from RRS is in international
+format, except that the '+' is missing.
+
+'''
+
+
+def generate_syntax_r2s_name(filename: str, colref: ColumnRef) -> None:
+    """Generate config example for rrs_to_sw."""
+    assert colref == ColumnRef.BY_NAME
+    cfg = ConfigXlsListRefmtName()
+    cfg.out_excel_library = ExcelLib.OPENPYXL
+    cfg.in_type = FileType.EXCEL
+    cfg.out_type = FileType.CSV
+    cfg.s1_split_columns = []
+    cfg.s3_merge_columns = [{'columns': ['First Name', 'Last Name'],
+                             'separator': ' '}]
+    cfg.s5_rename_columns = [
+        {'column': 'Nationality', 'name': 'Nat'},
+        {'column': 'Sail Number', 'name': 'SailNo'},
+        {'column': 'First Name', 'name': 'HelmName'},
+        {'column': 'Club Name', 'name': 'Club'},
+        {'column': 'Email', 'name': 'HelmEmail'},
+        {'column': 'Mobile Phone', 'name': 'HelmPhone'},
+        {'column': 'Boat Name', 'name': 'Boat'}]
+    cfg.s6_insert_columns = []
+    cfg.s7_rewrite_columns = [
+        {'column': 'HelmPhone', 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^', 'to': '+', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 'HelmPhone', 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^\\+\\+', 'to': '+', 'case': CaseSensitivity.MATCH_CASE}]
+    cfg.s8_column_order = ['Class', 'Division', 'Nat', 'SailNo', 'Boat',
+                           'HelmName', 'Club', 'HelmEmail', 'HelmPhone']
+    cfg.write(to_json_filename=filename)
+
+
+TXT_R2S_NAME = syntax_r2s_common + by_name_common
+
+
+def generate_syntax_r2s_num(filename: str, colref: ColumnRef) -> None:
+    """Generate config example for rrs_to_sw."""
+    assert colref == ColumnRef.BY_NUMBER
+    cfg = ConfigXlsListRefmtNum()
+    cfg.out_excel_library = ExcelLib.OPENPYXL
+    cfg.in_type = FileType.EXCEL
+    cfg.out_type = FileType.CSV
+    cfg.s1_split_columns = []
+    cfg.s2_remove_columns = [10]  # remove WhatsApp
+    cfg.s3_merge_columns = [{'columns': [5, 6], 'separator': ' '}]
+    cfg.s4_place_columns_first = []
+    cfg.s5_rename_columns = [
+        {'column': 0, 'name': 'Class'},
+        {'column': 1, 'name': 'Division'},
+        {'column': 2, 'name': 'Nat'},
+        {'column': 3, 'name': 'SailNo'},
+        {'column': 4, 'name': 'Boat'},
+        {'column': 5, 'name': 'HelmName'},
+        {'column': 6, 'name': 'Club'},
+        {'column': 7, 'name': 'HelmEmail'},
+        {'column': 8, 'name': 'HelmPhone'}]
+    cfg.s6_insert_columns = []
+    cfg.s7_rewrite_columns = [
+        {'column': 8, 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^', 'to': '+', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 8, 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^\\+\\+', 'to': '+', 'case': CaseSensitivity.MATCH_CASE},
+        {'column': 8, 'kind': RewriteKind.REGEX_SUBSTITUTE,
+         'from': '^\\+H', 'to': 'H', 'case': CaseSensitivity.MATCH_CASE}]
+    cfg.write(to_json_filename=filename)
+
+
+TXT_R2S_NUM = syntax_r2s_common + by_number_common
+
+
+def generate_syntax_example(filename: str, colref: ColumnRef) -> None:
+    """Generate config example for example."""
+    cfg = config_factory_from_enum(colref)
+    cfg.out_type = FileType.CSV
+    cfg.in_csv_dialect['name'] = 'csv.unix_dialect'
+    cfg.write(to_json_filename=filename)
+
+
+TXT_SYNTAX_WXAMPLE = '''
+This example configuration file does not match any known use case.
+It is written as an example configuration with 2 objectives:
+to demonstrates all configuration options, and to be small.
+'''
+
+dispatch = {'forms_to_rrs': {ColumnRef.BY_NAME: generate_syntax_o2r_name,
+                             ColumnRef.BY_NUMBER: generate_syntax_o2r_num},
+            'forms_to_sw': {ColumnRef.BY_NAME: generate_syntax_o2s_name,
+                            ColumnRef.BY_NUMBER: generate_syntax_o2s_num},
+            'rrs_to_sw': {ColumnRef.BY_NAME: generate_syntax_r2s_name,
+                          ColumnRef.BY_NUMBER: generate_syntax_r2s_num},
+            'example': {ColumnRef.BY_NAME: generate_syntax_example,
+                        ColumnRef.BY_NUMBER: generate_syntax_example}}
+
+txts = {'forms_to_rrs': {ColumnRef.BY_NAME: TXT_O2R_NAME,
+                         ColumnRef.BY_NUMBER: TXT_O2R_NUM},
+        'forms_to_sw': {ColumnRef.BY_NAME: TXT_O2S_NAME,
+                        ColumnRef.BY_NUMBER: TXT_O2S_NUM},
+        'rrs_to_sw': {ColumnRef.BY_NAME: TXT_R2S_NAME,
+                      ColumnRef.BY_NUMBER: TXT_R2S_NUM},
+        'example': {ColumnRef.BY_NAME: TXT_SYNTAX_WXAMPLE,
+                    ColumnRef.BY_NUMBER: TXT_SYNTAX_WXAMPLE}}
+
+
+def get_example_names() -> list[str]:
+    """Return names of example usages with example cfg files."""
+    return list(dispatch.keys())
+
+
+def generate_examplecfg(filename: str, cfgtype: str,
+                        colref: ColumnRef) -> int:
+    """Generate example cfg file for one type of usage."""
+    fixedname = fix_file_extension(filename=filename, ext_to_add='.cfg')
+    syntaxfilename = fix_file_extension(filename=fixedname, ext_to_add='.txt',
+                                        ext_to_remove='.cfg')
+    generate_syntax_txt(filename=syntaxfilename,
+                        example_description=txts[cfgtype][colref],
+                        cfgfilename=fixedname)
+
+    dispatch[cfgtype][colref](filename=fixedname, colref=colref)
+    print(f'Wrote files {fixedname} and {syntaxfilename}')
+    return 0

excel_list_transform/generate_txt.py

@@ -0,0 +1,259 @@
+#! /usr/local/bin/python3
+"""Generate example configuration files."""
+
+# Copyright (c) 2024 Tom Björkholm
+# MIT License
+
+
+def generate_syntax_txt(filename: str, example_description: str,
+                        cfgfilename: str) -> None:
+    """Generate a text file with configuration syntax description."""
+    msg = '''
+    Description of how to write/change the configuration file.
+    ==========================================================
+
+    The configuration file is in JSON syntax.
+    https://en.wikipedia.org/wiki/JSON
+    The keywords and the nesting is important. The order of keywords
+    have no significance (the examples use alphabetical order).
+    Indentation and line breaks hanve no significance.
+
+    It is recommended that you let the command generate a configuration
+    file and then edit that file to match your needs. It is NOT recommended
+    that the user writes the configuration file from scratch.
+
+
+    column_ref
+    ==========
+    The keyword column_ref is used to tell if the configuration
+    references columns by name (value "BY_NAME") or by number
+    (value "BY_NUMBER"). The syntax of parts of the configuration file
+    is slightly different depending on the how columns are referenced.
+    Thus, you first have to decide how you want to reference columns.
+
+    Generally it is easier to write a correct configuration using "BY_NAME",
+    so "BY_NAME" is recommended when possible.
+    "BY_NAME" imposes a few restrictions:
+     - each column need to have a unique text at the first line to use
+       as column name.
+     - the column names need to be stable and known.
+
+    If you cannot meet these restrictions you will have to reference the
+    columns by number "BY_NUMBER". When referencing the columns by number
+    it is important to note that the column numbers change when splitting,
+    merging, inserting or removing columns.
+
+    When referencing "BY_NUMBER" the columns are numbered from left to
+    right. The leftmost column is number 0.
+
+
+    Type of input and output file
+    ==============================
+    The type of input file to read is determined by "in_type".
+    The type of input file to read is determined by "out_type".
+    "in_type" and "out_type" can have values "CSV" or "EXCEL".
+
+    Excel files can be read and written using three libraries.
+    "in_excel_library" and "out_excel_library" can have values
+    "OPENPYXL", "XLSXWRITER" or "PYLIGHTXL". These are different
+    third party libraries that can read/write excel. My experience
+    is that "PYLIGHTXL" most often is able to read and write excel
+    files correctly. If you have trouble reading/writing your
+    particular excel file, please try different combinations of
+    these libraries. "in_excel_library" is always needed in
+    the configuration file but is not used if the input is CSV.
+    "out_excel_library" is always needed in the configuration file
+    but is not used if the output is CSV.
+
+    Currently "PYLIGHTXL" appears to be best to write files for
+    Microsoft Excel to open without complaints. But "OPENPYXL"
+    appears to be best to write files to be imported by
+    https://www.racingrulesofsailing.org .
+    When newer versions arrive this might change...
+
+    Comma separated values files (CSV files) may differ slightly
+    depening on the programs used to read/write them and the locale
+    used. "in_csv_dialect" and "out_csv_dialect" changes how CSV files
+    are read and written. They are always needed in the configuration
+    file, but are not used if the input and output are excel files.
+
+
+    Column manipulation
+    ====================
+    A number or records starting with "s" and a number describe
+    column manipulation to be done. These manipulations are done
+    in order of the number: s1_(something) before s2_(something),
+    before s3_(something). As the "s" number records might add, remove
+    or rename columns, it is important to keep track of the order that
+    they are applied.
+
+    Some "s" numbers are only used if columns are referenced
+    by name while other "s" numbers are only used if columns are
+    referenced by number.
+
+
+    "s1_split_columns"
+    ==================
+    The first operation that is done is splitting of columns.
+    The key "s1_split_columns" have an array of splits to be
+    done. (When the list of splits has more than one split,
+    the least confusion is to split columns to the right before
+    columns to the left. Named references also helps to avoid
+    confusion.)
+
+    Each split has the following keys: "column", "separator" and
+    "where". In the case of number column references the there is
+    also the key "store_single". In the case of named column references
+    there is instead the key "right_name".
+
+    "column" take as argument the column to be split. This is a
+    column number in the case of "BY_NUMBER", and a column name/title
+    in the sace of "BY_NAME".
+
+    "separator" is a string of characters that indicate the position
+    where the column shall be split. (For instance a single space
+    if splitting between two words.)
+
+    "where" can either have the value "RIGHTMOST" or the value
+    "LEFTMOST". This is used if the separator string is present
+    more than once in the column value to split. The split is then
+    done at the leftmost or rightmost occurence according to the
+    value of "where".
+
+    "right_name" is only used if column references are "BY_NAME".
+    After the split the left column uses the original column name,
+    and "right_name" is used as the name of the new right column.
+
+    "store_single" is used only if column references are "BY_NUMBER".
+    If the column value before split does not include the separator,
+    the result of the split is a single value.
+    "store_single" can have the value "RIGHTMOST" or the value
+    "LEFTMOST". This determines which column the single value shall
+    be stored in. (The other column will be empty.)
+    In the case of column references "BY_NAME" the single value is
+    always stored in the column with the original name.
+
+
+    "s2_remove_columns"
+    ===================
+    "s2_remove_columns" is only used with column references "BY_NUMBER".
+    The value of "s2_remove_columns" is a list of column numbers to
+    remove.
+    (For columns references "BY_NAME" see "s8_column_order".)
+
+
+    "s3_merge_columns"
+    ==================
+    The key "s3_merge_columns" have an array of merges to be done.
+    Each merge have the keys "columns" and "separator"
+
+    "columns" have a list of column references. If "BY_NAME" the
+    column references are column names/titles. If "BY_NUMBER" the
+    column references are column numbers.
+
+    "separator" is a string of characters that is inserted between
+    the column values being merged.
+
+
+    "s4_place_columns_first"
+    ========================
+    "s4_place_columns_first" is only used with column references "BY_NUMBER".
+    The key "s4_place_columns_first" has a value that is a list of the
+    column numbers to be placed first in order. This step re-orders the
+    columns.
+    (For columns references "BY_NAME" see "s8_column_order".)
+
+
+    "s5_rename_columns"
+    ===================
+    The key "s5_rename_columns" has a value that is a list of column rename
+    operations. Each column rename operation has the keys "column" and "name"
+
+    "column" is the number/name of the column before renameing. This is a
+    column number in the case of "BY_NUMBER", and a column name/title
+    in the sace of "BY_NAME".
+
+    "name" is the new name/title of the column identified by "column".
+
+
+    "s6_insert_columns"
+    ===================
+    The key "s6_insert_columns" has a value that is a list of columns to
+    insert. Each column to insert is described by the keys: "column",
+    "value" and for "BY_NUMBER" only "name",
+
+    "column" is the column reference of the inserted column.
+    In the case of "BY_NUMBER" this is also the position where
+    the column is inserted. In the case of "BY_NAME" this is the
+    name of the inserted column.
+
+    "value" is the value that this column shall have for every row.
+    The special word null can be used to state that column shall be
+    empty (with no value).
+
+    "name" is the name/title of the column in the case of "BY_NUMBER".
+
+
+    "s7_rewrite_columns"
+    ====================
+    The key "s7_rewrite_columns" has a value that is a list of
+    rewrite operations that will be applied in order. Each rewrite
+    operation is described by several keys.
+
+    "kind" key is used to specify which kind of rewrite operation
+    this is. Different values for "kind" will have different other
+    keys. "kind" can have the values: "STRIP", "REMOVECHARS",
+    "STR_SUBSTITUTE" and "REGEX_SUBSTITUTE".
+
+    "kind" value "STRIP" shall have the keys: "kind", "case", "chars"
+    and "column". This case means that the characters in "chars" shall
+    be stripped off the beginning and end of the column value. If key
+    "chars" is empty string, then white space is stripped off.
+
+    "kind" value "REMOVECHARS" shall have the keys: "kind", "case",
+    "chars" and "column". This case means that the characters in "chars"
+    shall be removed from the column (also when the characters are in the
+    middle of the column value).
+
+    "kind" value "REGEX_SUBSTITUTE" shall have the keys: "kind", "case",
+    "from", "to" and "column". This case means that "from" value is used
+    as a regular expression, and if it matches the matching part is replaced
+    with the value of key "to".
+
+    "kind" value "STR_SUBSTITUTE" shall have the keys: "kind", "case",
+    "from", "to" and "column". This case means that "from" value is a string,
+    and if a sub-string of the column value equals this string that part is
+    replaced with the value of key "to".
+
+    "column" identifies the column to rewrite. This is a column number in the
+    case of "BY_NUMBER", and a column name/title in the sace of "BY_NAME".
+
+    "chars" is a list of characters written as a string. These characters
+    are removed or stripped off the beginning/end depending on the "kind"
+    value.
+
+    "case" specifies if comparison of column value to value of "chars" or
+    value of "from" shall be case sensitive or not. Possible values are
+    "MATCH_CASE" and "IGNORE_CASE".
+
+    "from" specifies what the part to substitute shall match. The from part
+    in the substitute from something to something.
+
+    "to" specifies the string that substitution will replace "from" with.
+
+
+    "s8_column_order"
+    =================
+    The key "s8_column_order" is used only in the "BY_NAME" case.
+    The value of the "s8_column_order" key is a list of column names.
+    The columns will be output in this order.
+    Columns not mentioned in "s8_column_order" will not be output,
+    and will thus be removed.
+    (For "BY_NUMBER" see "s2_remove_columns" and "s4_place_columns_first".)
+    '''
+    with open(file=filename, mode='w', encoding='utf-8') as file:
+        print(f'Explanation for example configuration file {cfgfilename}',
+              file=file)
+        print(example_description, file=file)
+        print('\n\n\n', file=file)
+        print(msg, file=file)