From a088388e198940a8cf753d172d075dadf30ef545 Mon Sep 17 00:00:00 2001 From: Benedikt Peetz Date: Sat, 18 May 2024 16:37:25 +0200 Subject: [PATCH] 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. --- src/lib.rs | 18 ++++++++++-------- src/trinitry.pest | 35 +++++++++++++++++++++++++++++------ 2 files changed, 39 insertions(+), 14 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 277c985..97ca1bc 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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" //! ``` diff --git a/src/trinitry.pest b/src/trinitry.pest index e42d49d..e1333fd 100644 --- a/src/trinitry.pest +++ b/src/trinitry.pest @@ -18,12 +18,32 @@ // and the Lesser GNU General Public License along with this program. // If not, see . -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