back to Table of Contents

ParseLine (function)

Does parse the given input line and break the line up into its individual words or components according to the given separators and quoting chars.

Any kind and number of the given separator chars will split the components unless they appear in quoted sections. Parts of the line enclosed by the given quotation char(s) will be handled as one word or component. For more specific information see the PARSING RULES below.

SYNTAX:

ub& = ParseLine& (inpLine$, sepChars$, quoChars$, outArray$(), minUB&)

INPUTS:

inpLine$ (STRING)

• The input line which you want to process. This may in fact be any sequence of chars including control chars and zeros.

sepChars$ (STRING)

• This string may contain up to 5 different chars, which shall serve as separators, such as tabs or spaces. More chars following the 5th one will be ignored.
  • If left empty, then only the given quoting char(s) will split the components.

quoChars$ (STRING)

• This string may contain up to 2 different chars, which shall serve as quotation marks. More chars following the 2nd one will be ignored.
  • If left empty, then the regular quotation mark (") is used by default.
  • If only one char is given, then it simply replaces the regular quotation mark (").
  • If two chars are given, then the first one serves as opening quote mark and the second one as matching closing quote mark.
    • If both chars are identical, then it behaves like only one char again.

outArray$() (STRING array)

• This must be a 1-dimensional REDIMed (dynamic) STRING array of at least one element, in which the individual components will be stored. The array will be internally adjusted as needed for the number of components found in the input line. It will always keep the lower bound, but will raise or reduce the upper bound as needed.

minUB& (LONG)

• Should be either zero or the minimum upper bound, which the output array shall have after the call. This can be used, if you expect a fix number of components.
  • If the input line has not enough components, then the unused array elements remain empty.
  • Note that the array may still grow bigger, if the line has more components than expected.

RESULT:

ub& (LONG)

• The final upper bound of the output array after parsing. It will be negative (-1) if there was nothing to parse (ie. the input line was either empty or consisted of separators only), the given array remains unchanged in that case.

PARSING RULES:

Note that a char cannot be a separator and a quoting char at the same time, if required you've to workaround that by performing several parsing stages !!

• Any separators will split up the words or components as usual.
• Opening a quotation will also split (even without leading separators), ie. it will finish the currently processed (unquoted) component and begins the quoted one.
• Closing a quotation (even without trailing separators) will finish the current (quoted) component.
• Quoted components may be empty ("") and produce an empty array entry in that case.
• An open quoted component with no closing mark in the remaining input line will be closed at the end of line (EOL), ie. the complete remaining line is taken (as is) in one quoted component.
• With respect to the latter two points, opening a quotation with the very last char of the input line will produce an additional empty array entry (as it is, in fact, an empty quoted component closed by EOL).

Quoting rules: (one char mode)

• Very simple and logic, the 1st occurrence of the given quoting char opens a quote, the 2nd occurrence does close it, the 3rd will open the next quote, the 4th does close it again and so on.

Quoting rules: (two chars mode)

• The occurrence of the opening quote mark (1st given char) does open a quote, further only a matching occurrence of the closing quote mark (2nd char) does close the (quoted) component.
• Nesting of several quotes is not supported, hence every quote must be closed, before another one may be opened, ie:
  • Further open/close markers inside a quote will be handled as literal text until the internal counter recognizes a matching close marker.
  • Also close markers outside a quote will be handled as literal text as well.

back to Table of Contents