parser_regexp_format_notes.txt

-- the autocompletable lines are read in from the given source files by using one of these "parsers"
-- the parsers are collection of regular expressions than can be used to define the acceptable 
-- strings, substring or other features

--
-- Format:
-- Each of these regexp lines will be tested against the lines in the autocomplete source files
-- preference is done in order of match appearance in this file 
-- the first regexp matching will be used, rest ignored for that line
--
-- to ignore a autocomplete source line:
-- (?<ignore>AnyLineMatchingToThisRegexpWillBeIgnored)
--
-- to add an autocomplete source line as non-allowed (error) string:
-- these errors will have preference, even over lines that match some defined string
-- (?<error>AnyLineMatchingToThisRegexpWillBeConsideredAnError)
--
-- to add an autocomplete source line as non-recommended (warning) string:
-- these warnings will have preference, even over lines that match some defined string
-- (?<warning>AnyLineMatchingToThisRegexpWillBeConsideredAsWorthAWarning)
--
-- to add this expression as non-allowed (error) string checker:
-- notice, that the expression won't be checked if the user input matched any of the defined string/substring lines
-- (?<error_exp>TheUserInputWillBeCheckedAgainstThisRegExpForError)
--
-- to this expression as non-recommended (warning) string checker:
-- notice, that the expression won't be checked if the user input matched any of the defined string/substring lines
-- (?<warning_exp>TheUserInputWillBeCheckedAgainstThisRegExpForWarning)
--
-- to accept the line as autocomplete choice:
-- (?<string>AnyLineMatchingToThisRegexpWillBeUsedForAutocomplete)
--
-- TODO: 
-- to accept the line to be used as a sub-string for autocompletion:
-- (?<substring>AnyLineMatchingToThisRegexpWillBeUsedForAutocomplete)
--
-- to select which section of regexps to use
-- note, that if you use any sections, then you should always have a file starting with one 
-- (to prevent any unexpected leak of the current section from one source file to another)
-- (?<section>AnyLineMatchingToThisRegexpWillCauseSectionChange)
--
-- to begin a named section of reg exps, by default, the regexp section is "default" (without quotes)
-- each regexp is attempted for a match when in that section, use the (?<section>...) regexp to switch a section
-- (the section switching allows multiple regexp parsers per parser file, switched based encountered source lines)
-- a special section of [*] can be used to define regexps that are used regardless of the current section (reduce copy&paste)
-- [nameOfSection]
--
-- to read in a new autocomplete source file and append that to list of lines to parse 
-- (be careful with this, no infinite loops and stuff ;)
-- (?<source>AnyLineMatchingToThisRegexpWillBeAddedAsAutocompleteSource)
--
-- TODO:
-- the formatter string for the source lines reg exps, only one of these lines can exist
-- this can be used to convert different kinds of path expressions as suitable system filenames
-- [source_format=TheFormattingOfTheSourceRegexp]
--
-- Note 1, the reg exps do not need to start with the "(?<...>...)" - that part can be used later on the
-- expression, if you do not want to use the entire line as the string, but rather a part of it
-- that tagged part of the expression must only be non-empty for that expression to be triggered
--
-- Note 2, any autocomplete source line that does not match any of the regexps, will cause an error
-- (recommended to keep it that way, but if you wish to silently ignore all such errors,
-- just add an ignore line that accepts any line as the last reg exp of your parser)
--
-- Note 3, the source files work as "suggest only" autocomplete normally, 
-- if you wish to force the user to select one of the autocomplete choices, and to deny the user
-- from writing a custom string, add the following line to your parser as the first line
-- (?<error_exp>^.*$)
-- this will cause all of the lines to cause an error (unless they matched some string/substring)
--
-- Note 4, any empty lines are always automatically ignored (and line trailing/ending whitespaces will get trimmed)