From 416a2fae7a17b05279247178884805d9ce732348 Mon Sep 17 00:00:00 2001 From: Mario Pietsch Date: Mon, 6 Mar 2023 17:12:26 +0100 Subject: [PATCH] Add syntax docs to railroad plugin (#7334) --- .../railroad/doc/example-transclusion.tid | 3 + plugins/tiddlywiki/railroad/doc/syntax.tid | 250 ++++++++++++++++++ plugins/tiddlywiki/railroad/parser.js | 4 +- 3 files changed, 255 insertions(+), 2 deletions(-) create mode 100644 plugins/tiddlywiki/railroad/doc/example-transclusion.tid diff --git a/plugins/tiddlywiki/railroad/doc/example-transclusion.tid b/plugins/tiddlywiki/railroad/doc/example-transclusion.tid new file mode 100644 index 000000000..f8d1144b1 --- /dev/null +++ b/plugins/tiddlywiki/railroad/doc/example-transclusion.tid @@ -0,0 +1,3 @@ +title: $:/plugins/tiddlywiki/railroad/example-transclusion + +"railroad transclusion example" text \ No newline at end of file diff --git a/plugins/tiddlywiki/railroad/doc/syntax.tid b/plugins/tiddlywiki/railroad/doc/syntax.tid index fc0d8d87f..0e6e809dd 100644 --- a/plugins/tiddlywiki/railroad/doc/syntax.tid +++ b/plugins/tiddlywiki/railroad/doc/syntax.tid @@ -2,6 +2,7 @@ created: 20150103184022184 modified: 20150119220342000 title: $:/plugins/tiddlywiki/railroad/syntax + The railroad widget uses a special notation to construct the components defined below. `x` and `y` here stand for any component. @@ -12,9 +13,28 @@ Names (as opposed to quoted strings) are available when a value starts with a le ; sequence : <$railroad text=""" ["<-"] {x} ["->"] """/> + * A sequence of components * The `<-` and `->` delimiters allow you to force a single component to be treated as a sequence. This is occasionally useful for spacing a diagram out +examples + +<<< + +``` +x y z sequence +``` +<$railroad text=""" x y z """/> + +``` +<-x y z-> explicit sequence +``` + +<$railroad text=""" <- x y z -> """/> + +<<< + + --- ; optional @@ -22,6 +42,24 @@ Names (as opposed to quoted strings) are available when a value starts with a le * A component that can be omitted * The colon makes `x` appear straight ahead +examples + +<<< + +``` +[:x] optional, normally included +``` +<$railroad text=""" [:x] """/> + +``` +[x] optional, normally omitted +``` + +<$railroad text=""" [x] """/> + +<<< + + --- ; repeated @@ -29,12 +67,62 @@ Names (as opposed to quoted strings) are available when a value starts with a le * A list of one or more `x` * The `+` suffix adds `y` as a separator between each `x` and the next +examples + +<<< + +``` +{x} one or more +``` +<$railroad text=""" {x} """/> + +``` +{x +","} one or more, comma-separated +``` + +<$railroad text=""" {x +","} """/> + +<<< + + --- ; optional repeated : <$railroad text=""" "[{" [":"] x [:"+" y] "}]" """/> * An optional list of `x`, i.e. a list of zero or more `x` +examples + +<<< + +``` +[{:x}] zero or more, normally included +``` + +<$railroad text=""" [{:x}] """/> + +``` +[{:x +","}] zero or more, comma-separated, normally included +``` + +<$railroad text=""" [{:x +","}] """/> + +``` +[{x}] zero or more, normally omitted +``` + +<$railroad text=""" [{x}] """/> + +``` +[{x +","}] zero or more, comma-separated, normally omitted +``` + +<$railroad text=""" [{x +","}] """/> + +<<< + + + --- ; choice @@ -42,6 +130,25 @@ Names (as opposed to quoted strings) are available when a value starts with a le * A set of alternatives * The colon indicates which branch appears straight ahead. By default, it's the first branch +examples + +<<< + +``` +(x|y|z) alternatives +``` + +<$railroad text=""" (x|y|z) """/> + +``` +(x|:y|z) alternatives, normally y +``` + +<$railroad text=""" (x|:y|z) """/> + +<<< + + --- ; string / terminal @@ -49,36 +156,117 @@ Names (as opposed to quoted strings) are available when a value starts with a le * A literal or terminal component * This follows the normal ~TiddlyWiki rules for quoted strings +examples + +<<< + +``` +"x" terminal +``` + +<$railroad text=""" "x" """/> + +<<< + + --- ; nonterminal : <$railroad text=""" (name | "<" string ">") """/> * A nonterminal component, i.e. the name of another diagram +examples + +<<< + +``` +<"x"> nonterminal +``` + +<$railroad text=""" <"x"> """/> + +<<< + + --- ; comment : <$railroad text=""" "/" string "/" """/> * A comment +examples + +<<< + +``` +/ "comment" / comment +``` + +<$railroad text=""" / "comment" / """/> + +<<< + + --- ; dummy : <$railroad text=""" "-" """/> * The absence of a component +examples + +<<< + +``` +- dummy +``` + +<$railroad text=""" - """/> + +<<< + + --- ; link : <$railroad text=""" "[[" x "|" (name|string) "]]" """/> * A link to the tiddler title or URI given by the string or name +examples + +<<< + +``` +[[x|"tiddler"]] link +``` + +<$railroad text=""" [[x|"tiddler"]] """/> + +<<< + + --- ; transclusion : <$railroad text=""" "{{" (name|string) "}}" """/> * Treats the content of another tiddler as diagram syntax and transcludes it into the current diagram +examples + +<<< + +``` +{{"$:/plugins/tiddlywiki/railroad/example-transclusion"}} transclusion + +// "railroad transclusion example" text <- text in the tidlder + +``` + +<$railroad text=""" {{ "$:/plugins/tiddlywiki/railroad/example-transclusion" }} """/> + +<<< + + --- ; arrow pragma @@ -86,14 +274,76 @@ Names (as opposed to quoted strings) are available when a value starts with a le * Controls whether repeat paths have an arrow on them * Can be toggled on and off in mid-diagram, if desired +examples + +<<< +``` +<$railroad text=""" +\arrow yes +[{:x}] +"""/> + +``` + +<$railroad text="""\arrow yes [{:x}] """/> + +``` +<$railroad text=""" +\arrow no +[{:x}] +"""/> +``` + +<$railroad text="""\arrow no [{:x}] """/> + +<<< + + --- ; debug pragma : <$railroad text=""" "\debug" """/> * Causes the diagram to display its parse tree +examples + +<<< + +``` +\debug +x +``` + +<$railroad text="""\debug x """/> + +<<< + + --- ; start/end pragma : <$railroad text=""" ("\start" |: "\end") ("none" |: "single" | "double") """/> * Controls the style of the diagram's startpoint or endpoint +examples + +<<< + +``` +\start none x +``` + +<$railroad text=""" \start none x """/> + +``` +\start double +\end double + x +``` + +<$railroad text=""" \start double +\end double +x +"""/> + +<<< + diff --git a/plugins/tiddlywiki/railroad/parser.js b/plugins/tiddlywiki/railroad/parser.js index bb55b57b8..013d898d7 100644 --- a/plugins/tiddlywiki/railroad/parser.js +++ b/plugins/tiddlywiki/railroad/parser.js @@ -5,6 +5,8 @@ module-type: library Parser for the source of a railroad diagram. +x y z sequence +<-x y z-> explicit sequence [:x] optional, normally included [x] optional, normally omitted {x} one or more @@ -13,8 +15,6 @@ Parser for the source of a railroad diagram. [{:x +","}] zero or more, comma-separated, normally included [{x}] zero or more, normally omitted [{x +","}] zero or more, comma-separated, normally omitted -x y z sequence -<-x y z-> explicit sequence (x|y|z) alternatives (x|:y|z) alternatives, normally y "x" terminal