docs(src): Improve the text regarding the allowed chars in an argument

The previous text seemed to suggest, that you could only use the special
chars if the argument was actually quoted, which was misleading.
This commit is contained in:
Benedikt Peetz 2024-05-18 16:37:25 +02:00
parent fb01d5b16f
commit a088388e19
Signed by: bpeetz
GPG Key ID: B6139BCB07CE946D
2 changed files with 39 additions and 14 deletions

View File

@ -37,13 +37,15 @@
//! $$ \Sigma_{cmd} = \\{x | 0 \leqslant x \leqslant 9\\} \cup \\{x | "a" \leqslant x \leqslant "z"\\} \cup \\{x | "A" \leqslant x \leqslant "Z"\\} \cup \\{"\\_", "\text{-}", "."\\} $$
//!
//! ## Argument
//! Arguments are similar to the command, although they can also contain spaces and quotes,
//! if it's quoted and additional characters (here notated as "$\\dots{}$"):
//! $$ \Sigma_{args-quoted} = \Sigma_{cmd} \cup \\{"\\text{"}", "\\ ", \\dots{}\\} $$
//! $$ \Sigma_{args-single-quoted} = \Sigma_{cmd} \cup \\{"'", "\\ ", \\dots{}\\} $$
//! $$ \Sigma_{args} = \Sigma_{cmd} \cup \\{\\dots{}\\} $$
//! Look at the [trinitry.pest](../../../src/trinitry.pest) file for a full list of the additional
//! allowed characters.
//! Arguments constructed from the same alphabet as the commands, but can contain additional chars
//! listed in the [trinitry.pest](../../../src/trinitry.pest) file.
//! $$ \Sigma_{args} = \Sigma_{cmd} \cup{} \\{\\dots{}\\} $$
//!
//! Besides the extra chars outlined above the arguments can also contain
//! spaces and quotes, if they are quoted. Quoted args are either double quoted, and can thus
//! contain single quotes, or single quoted, and can contain double quotes.
//! $$ \Sigma_{args-double-quoted} = \Sigma_{args} \cup \\{"\\text{\\texttt{'}}", "\\ "} $$
//! $$ \Sigma_{args-single-quoted} = \Sigma_{args} \cup \\{"\\text{\\texttt{"}}", "\\ "} $$
//!
//! # Examples
//! ## Command
@ -61,7 +63,7 @@
//! ```text
//! lua "function() print('Hi!') end"
//! ```
//! Whilst this would not be valid (that is, it would very likely not be what you want):
//! Whilst this would not be valid (it is actually valid, but results in something, you likely did not expect):
//! ```text
//! lua "function() print("Hi!") end"
//! ```

View File

@ -18,12 +18,32 @@
// and the Lesser GNU General Public License along with this program.
// If not, see <https://www.gnu.org/licenses/>.
chars = { ASCII_ALPHANUMERIC | "_" | "-" | "." }
command_chars = { ASCII_ALPHANUMERIC | "_" | "-" | "." }
// TODO(@soispha): Are these all the valid characters? <2023-11-01>
argument_chars = { chars | "(" | ")" | "{" | "}" | "<" | ">" | "?" | "!" | "+" | "^" | "@"
| "&" | "*" | "~" | "|" | "=" | "," | "\\" | "/" }
whitespace = _{ " " } // lower case to avoid special treatment of 'WHITESPACE'
argument_chars = {
command_chars |
"(" |
")" |
"{" |
"}" |
"<" |
">" |
"?" |
"!" |
"+" |
"^" |
"@" |
"&" |
"*" |
"~" |
"|" |
"=" |
"," |
"\\" |
"/"
}
whitespace = _{ " " } // lower case to avoid the special treatment of `WHITESPACE`
quote = _{ "\"" }
q = _{ quote }
@ -33,7 +53,7 @@ sq = _{ single_quote }
command = { chars+ }
command = { command_chars+ }
arg_quoted = { q ~ (!q ~ (argument_chars | " " | "'" ))+ ~ q }
arg_single_quoted = { sq ~ (!sq ~ (argument_chars | " " | "\"" ))+ ~ sq }
@ -43,3 +63,6 @@ argument = { whitespace+ ~ (arg_quoted | arg_single_quoted | arg )}
trinitry = { SOI ~ #command = command ~ (#argument = argument)* ~ EOI }
// better than no syntax highlight:
// vim: ft=javascript