comments

Author: Aerijo

lib/snippet-body.pegjs

@@ -23,7 +23,7 @@ format ::= '$' int | '${' int '}' | '${' int ':' modifier '}' | '${' int ':+' if
 
 regex ::= JS regex value
 
-options ::= JS regex options // NOTE: Unrecognised options should be ignored for the best fault tolerance (can log a warning though)
+options ::= JS regex options
 
 modifier = '/' var
 
@@ -52,73 +52,123 @@ int ::= [0-9]+
 // Grab anything that isn't \ or $, then try to build a special node out of it, and (at the top level) if that fails then just accept it as text
 topLevelContent = content:(text / escapedTopLevel / tabStop / choice / variable / any)* { return coalesce(content); }
 
-tabStopContent = content:(tabStopText / escapedTabStop / tabStop / choice / variable)* { return coalesce(content); }
+// Placeholder content. The same as top level, except we need to fail on '}' so that it can end the tab stop (the `any` rule would eat it if we used it here)
+tabStopContent = content:(tabStopText / escapedTabStop / tabStop / choice / variable / notCloseBrace)* { return coalesce(content); }
 
-tabStop = tabStopSimple / tabStopWithoutPlaceholder / tabStopWithPlaceholder / tabStopWithTransform
+// The forms of a tab stop. They all start with '$', so we pull that out here.
+tabStop = '$' t:(tabStopSimple / tabStopWithoutPlaceholder / tabStopWithPlaceholder / tabStopWithTransform) { return t; }
 
-tabStopSimple = '$' n:integer { return { index: n, content: [] }; }
+// The simplest form is just $n for some integer `n`
+tabStopSimple = n:integer { return { index: n, content: [] }; }
 
-tabStopWithoutPlaceholder = '${' n:integer '}' { return { index: n, content: [] }; }
+// The next simplest form is equivalent to the above, but wrapped in `{}`
+tabStopWithoutPlaceholder = '{' n:integer '}' { return { index: n, content: [] }; }
 
-tabStopWithPlaceholder = '${' n:integer ':' content:tabStopContent '}' { return { index: n, content }; }
+// When a ':' follows `n`, the content after the ':' is the placeholder and it can be anything
+tabStopWithPlaceholder = '{' n:integer ':' content:tabStopContent '}' { return { index: n, content }; }
 
-tabStopWithTransform = '${' n:integer t:transformation '}' { return { index: n, transformation: t }; }
+// When a transform follows `n` (indicated by '${n:/...')
+tabStopWithTransform = '{' n:integer t:transformation '}' { return { index: n, transformation: t }; }
 
-transformation = '/' capture:regexString '/' replace:replace '/' flags:flags { return { capture, flags, replace }; }
+// Builds a capture regex and substitution tree. If the capture is not a valid regex, then the match fails
+transformation = '/' find:regexString '/' replace:replace '/' flags:flags & {
+  // Predicate: only succeed if the `find` + `flags` values make a valid regex
+  // If so, then store the regex into `find` to be used in the following
+  // match transformation action
+  try {
+    find = new RegExp(find, flags);
+    return true;
+  } catch(e) {
+    return false;
+  }
+} {
+  return { find, replace };
+}
 
-// TODO: enforce this is a valid regex, or fail (can do at transform level where we make regex though)
+// Pulls out the portion that would be for the find regex. Validation is done
+// higher up, where we also have access to the flags.
 regexString = r:([^/\\] / '\\' c:. { return '\\' + c } )* { return r.join(""); }
 
-replace = (format / replaceText / replaceModifier / escapedReplace)*
+// The form of a substitution for a transformation. It is a mix of plain text + modifiers + backreferences to the find capture groups
+// It cannot access tab stop values.
+replace = (replaceText / format / replaceModifier / escapedReplace)*
 
-format = formatSimple / formatPlain / formatWithModifier / formatWithIf / formatWithIfElse / formatWithElse
+// A reference to a capture group of the find regex of a transformation. Can conditionally
+// resolve based on if the match occurred, and have arbitrary modifiers applied to it.
+// The common '$' prefix has been pulled out.
+format = '$' f:(formatSimple / formatPlain / formatWithModifier / formatWithIf / formatWithIfElse / formatWithElse) { return f; }
 
-formatSimple = '$' n:integer { return { backreference: n }; }
+// The simplest format form, resembles a simpel tab stop except `n` refers to the capture group index, not a tab stop
+formatSimple = n:integer { return { backreference: n }; }
 
-formatPlain = '${' n:integer '}' { return { backreference: n }; }
+// The same as the simple variant, but `n` is enclosed in {}
+formatPlain = '{' n:integer '}' { return { backreference: n }; }
 
-formatWithModifier = '${' n:integer ':' modifier:modifier '}' { return { backreference: n, modifier }; }
+// A modifier is something like "/upcase", "/pascalcase". If recognised, it resolves to the
+// application of a JS function to the `n`th captured group.
+formatWithModifier = '{' n:integer ':' modifier:modifier '}' { return { backreference: n, modifier }; }
 
-formatWithIf = '${' n:integer ':+' ifContent:replace '}' { return { backreference: n, ifContent }; }
+// If the `n`th capture group is non-empty, then resolve to the `ifContent` value, else an empty string
+// Note that ifContent is a replace itself; it's formats still refer to the original transformation find though,
+// as transformations cannot be nested.
+formatWithIf = '{' n:integer ':+' ifContent:replace '}' { return { backreference: n, ifContent }; }
 
-formatWithIfElse = '${' n:integer ':?' ifContent:replace ':' elseContent:replace '}' { return { backreference: n, ifContent, elseContent }; }
+// Same as the if case, but resolve to `elseContent` if empty instead of the empty string
+formatWithIfElse = '{' n:integer ':?' ifContent:replace ':' elseContent:replace '}' { return { backreference: n, ifContent, elseContent }; }
 
-formatWithElse = '${' n:integer ':' '-'? elseContent:replace { return { backreference: n, elseContent }; }
+// Same as the if case, but reversed behaviour with empty vs non-empty `n`th match
+formatWithElse = '{' n:integer ':' '-'? elseContent:replace { return { backreference: n, elseContent }; }
 
+// Used in `format`s to transform a string using a JS function
 modifier = '/' modifier:var { return modifier; }
 
+// Regex flags. Validation is performed when the regex itself is also known.
 flags = f:[a-z]* { return f; }
 
+// A tab stop that offers a choice between several fixed values. These values are plain text only.
+// This feature is not implemented, but the syntax is parsed to reserve it for future use.
+// It will currently just default to a regular tab stop with the first value as it's placeholder.
 choice = '${' n:integer '|' choiceText (',' choiceText)* '|}'
 
-variable = variableSimple / variablePlain / variableWithPlaceholder / variableWithTransform
+// Syntactically looks like a named tab stop. Variables are resolved in JS and may be
+// further processed with a transformation. Unrecognised variables are transformed into
+// tab stops with the variable name as a placeholder.
+variable = '$' v:(variableSimple / variablePlain / variableWithPlaceholder / variableWithTransform) { return v; }
 
-variableSimple = '$' v:var { return { variable: v }; }
+variableSimple = v:var { return { variable: v }; }
 
-variablePlain = '${' v:var '}' { return { variable: v }; }
+variablePlain = '{' v:var '}' { return { variable: v }; }
 
-variableWithPlaceholder = '${' v:var ':' content:tabStopContent '}' { return { variable: v, content }; }
+variableWithPlaceholder = '{' v:var ':' content:tabStopContent '}' { return { variable: v, content }; }
 
-variableWithTransform = '${' v:var t:transformation '}' { return { variable: v, transformation: t }; }
+variableWithTransform = '{' v:var t:transformation '}' { return { variable: v, transformation: t }; }
 
+// Top level text. Anything that cannot be the start of something special. False negatives are handled later by the `any` rule
 text = t:([^$\\}])+ { return t.join("") }
 
+// None-special text inside a tab stop placeholder. Should be no different to regular top level text.
 tabStopText = text
 
+// None-special text inside a choice. $, {, }, etc. are all regular text in this context.
 choiceText = t:[^,|]+ { return t.join(""); }
 
+// None-special text inside a replace (substitution part of transformation). Same as normal text, but `/` is special (the end of the regex-like pattern)
 replaceText = t:[^$\\}/]+ { return t.join(""); }
 
 // Match an escaped character. The set of characters that can be escaped is based on context, generally restricted to the minimum set that enables expressing any text content
 escapedTopLevel = '\\' c:[$\\}] { return c; }
 
+// Characters that can be escaped in a tab stop placeholder are the same as top level
 escapedTabStop = escapedTopLevel
 
+// Only `,` and `|` can be escaped in a choice, as everything else is plain text
 escapedChoice = '\\' c:[$\\,|] { return c; }
 
-replaceModifier = '\\' m:[uUlL] { return { modifier: m }; }
+// Same as top level, but `/` can also be escaped
+escapedReplace = '\\' c:[$\\/] { return c; }
 
-escapedReplace = '\\' c:[$\\] { return c; }
+// We handle 'modifiers' separately to escapes. These indicate a change in state when building the replacement (e.g., capitalisation)
+replaceModifier = '\\' m:[uUlL] { return { modifier: m }; }
 
 // Match nonnegative integers like those used for tab stop ordering
 integer = digits:[0-9]+ { return parseInt(digits.join(""), 10); }
@@ -128,3 +178,6 @@ var = a:[a-zA-Z_] b:[a-zA-Z_0-9]* { return a + b.join(""); }
 
 // Match any single character. Useful to resolve any parse errors where something that looked like it would be special had malformed syntax.
 any = a:. { return a; }
+
+// Match anything that isn't a '}'. Useful for parse errors inside placeholder text, as `}` should be used to end the tab stop region
+notCloseBrace = a:[^}] { return a; }