;-- TIME_STAMP   2022-07-14 10:21:45   v 0.1


; #FUNCTION# =======================================================================================
; Name ..........: _ConfigRead
; Description ...: Reading a configuration file, optionally filtered
; ...............: File rules:     • Can have any file extension
; ...............:                 • Requires sections, spelling case sensitive: [Section] <> [section]
; ...............:                 • If the entries contain values that are to be split into
; ...............:                   individual fields, use only ";" as the separator.
; ...............:                   Separators in the text must be masked: "\;"
; ...............:                 • Comments start with "REM " at the beginning of the line
; ...............:                 • Blank lines may be included and will be ignored
; Parameter(s)...: $_File          The file path
; ...............: $_Section       The section name
; ...............: $_aReturn       (ByRef) The variable to get the result array
; ....[optional].: $_Ubound2       If the lines are to be split into single values whose number is
; ...............:                 (Default: 0 - full line as one array item, masked separators are displayed with masking)
; ....[optional].: $_funcProgress  Each line is passed to this function for evaluation. (Default: Null)
; ...............:                 Use only one parameter in your function: "line" ( _MyFunc($line) )
; ...............:                 Return "" from your function if the line should be ignored.
; ...............:                 If $_Ubound2 = 0 --> return a string.
; ...............:                 If $_Ubound2 > 0 --> return a 1D-array, [0]..[$_Ubound2 -1], NO counter at [0]!
; ...............:                 Note:
; ...............:                 If your text contains masked delimiters, your function must take this into account when splitting.
; Return values .: Success         1
; ...............: Failure         0    @error = 1  Section not exists or empty
; Author ........: BugFix
; ==================================================================================================
Func _ConfigRead($_File, $_Section, ByRef $_aReturn, $_Ubound2=0, $_funcProgress=Null)
    Local $aSection[100], $n = 0
    If $_Ubound2 > 0 Then ReDim $aSection[100][$_Ubound2]
    Local $funcRet, $line, $aLine, $bInSection = False
    Local $fh = FileOpen($_File)
    Do
        $line = FileReadLine($fh)
        If Not @error Then
            ; check if the result array has to be enlarged
            If $n > UBound($aSection) -1 Then
                If $_Ubound2 > 0 Then
                    ReDim $aSection[UBound($aSection)+100][$_Ubound2]
                Else
                    ReDim $aSection[UBound($aSection)+100]
                EndIf
            EndIf

            ; comment line --> skip
            If StringRegExp($line, '^REM\s') Then ContinueLoop

            ; empty line --> skip
            If $line = '' Then ContinueLoop

            ; while reading target section a new section starts --> stop reading
            If $bInSection And StringRegExp($line, '^\[[^\]]+') Then
                $bInSection = False
                ExitLoop
            EndIf

            ; target section starts
            If StringRegExp($line, '^\[' & $_Section & '\]') Then
                $bInSection = True
                ContinueLoop
            EndIf

            ; while reading target section
            If $bInSection Then
                If $_Ubound2 = 0 Then                   ; output: 1D-array (one line per item)
                    If $_funcProgress <> Null Then
                        $funcRet = $_funcProgress($line); call external funtion to evaluate the line
                        If $funcRet <> '' Then          ; func returns empty string to skip the line
                            $aSection[$n] = $funcRet
                            $n += 1
                        EndIf
                    Else
                        $aSection[$n] = $line           ; add each line to result array
                        $n += 1
                    EndIf
                Else                                    ; output: 2D-array, 2nd dimension according to $_Ubound2
                    If $_funcProgress <> Null Then
                        $funcRet = $_funcProgress($line); call external funtion to evaluate the line
                        If $funcRet <> '' Then                                          ; func returns empty string to skip the line ...
                            If IsArray($funcRet) And UBound($funcRet) >= $_Ubound2 Then ; ... otherwise an array with ubound >= $_Ubound2 must be returned
                                For $i = 0 To $_Ubound2 -1
                                    $aSection[$n][$i] = $funcRet[$i]
                                Next
                                $n += 1
                            EndIf
                        EndIf
                    Else
                        $aLine = StringRegExp($line, '(\\;[^;]+|[^;]+\\;[^;]+|[^;]+\\;|[^;]+)', 3)  ; splits the line by ";", masked delimiters ("\;") are ignored
                        If UBound($aLine) >= $_Ubound2 Then     ; line is ignored if the number of elements is less than $_Ubound2
                            For $i = 0 To $_Ubound2 -1
                                $aSection[$n][$i] = StringReplace($aLine[$i], '\;', ';')
                            Next
                            $n += 1
                        EndIf
                    EndIf
                EndIf
            EndIf
        Else    ; EOF reached
            ExitLoop
        EndIf
    Until $line = -1
    FileClose($fh)
    If $n = 0 Then Return SetError(1,0,0)
    If $_Ubound2 > 0 Then
        ReDim $aSection[$n][$_Ubound2]
    Else
        ReDim $aSection[$n]
    EndIf
    $_aReturn = $aSection
    Return 1
EndFunc