clarify quoting and escaping

[honzakutil]

Quoting and escaping part of the documentation looks a little bit misleading. Special characters are really not considered to be special in pair of parentheses, but this not apply to parentheses of the choice definition. Rule asp ch1(-12V) ch2(-5V) will cause an error. Rule asp ch1((-12V)) ch2((-5V)) is correct, but does not help with assigning -12V value, since it assign (-12V). Correct way how to do it is to use asp ch1('-12V') ch2('-5V') or asp ch1(-12V) ch2(-5V).

I know it is just low priority detail, it just looks interesting to me. :-) Is there any practical use of fact that spacial characters are not considered to be special in ( )? Or it is just implication of the fact, how KiVar internally works?

[markh-de]

I have slightly reworded some parts of that section, but I don't think that's what you mean.

Background: When using special separator characters, you need a way to "protect" verbatim parts of your input string. For example, when a separator appears inside a quoted string, you want to keep the quoted string as a verbatim string, and do not want to mess with separation. Same with parentheses: Imagine a fictional programming language function call: function_name(arg1, another_function(foo, bar), arg3). When comma-splitting the content of the outer parens, you would not want to let your parser split foo and bar, as they are inside a "protected" scope.

As separating parts of a rule is done from the outside to the inside, the parser must be aware of (nested) parens and keep their content together, so that the rule is split correctly.

For KiVar: If the parser would not do this, the spaces inside a choice definition would be used to split the rule definition into its sections. E.g. asp ch1(value -!) would be separated into asp, ch1(value and -!).

To answer your question: The outcome of how you have used the parens is a side-effect without a use-case.

Hope this explains it.

Anyway, if you find the documentation misleading, please point me to the exact part which confuses you.

There will be so much to be updated in the documentation once I got all my current plans implemented. :smile:

[markh-de]

Ah, I think I know what you mean. Yes, you are right, it may be misleading. Special characters are only protected inside inner unresolved parens. It's more an implementation detail, and expected by the user anyway. I'll change this into a less prominent side-note (when reworking the docs).

I'll keep this issue to remind me. :smile:

[markh-de]

Nevermind. Just removed the stuff about the parens.

They do not belong into the list anyways. Because the difference between quoting/escaping and the parens is: The quoting and escaping is virtual (it gets removed by the parser and is not part of the result), whereas parens are kept, they just protect their content as a side-effect.

So, this must have been the part that confused you. Sorry.

Is this issue resolved for you?

[honzakutil]

Thanks for explanation. Outcome for me is, that parentheses are not intended for any other use than choice(value). Because documentation of KiVar is one of the best I have seen on github, I was curious, if it is mistake or intention with some feature behind.