/src/Editing/notes.txt

 1{- Command grammar:
 2
 3  command = (insert | append | prepend | erase | replace | move | swap | wrap | use | make)*
 4
 5  insert = ("insert" | "add") ... positions*
 6  append = "append" ... [positions*]
 7  prepend = "prepend" ... [positions*]
 8  erase = ("erase" | "remove" | "delete" | "cut" | "omit" | "kill") substrs*
 9  replace = "replace" (substrs* ("with" | "by") ...)*
10  move = "move" (substr "to" position)*
11  swap = "swap" (substr "and" substr)*
12  wrap = "wrap" wrapping ("around" substrs*)* | "wrap" substrs* "in" wrapping
13  use = "use" verbatim*
14  make = "make" declarator-id* type-description
15
16  wrapping = ... "and" ... | "parentheses" | "parens" | "braces" | "curlies"
17    | ("square" | "angle" | "curly" | "round") "brackets" | ("single" | "double") "quotes"
18  relative = between | befaft ranked
19  substrs = declaration | range | ("everything" | rankeds) [relative]
20  substr = declaration | range | ("everything" | ranked) [relative]
21  declaration = "declaration" "of" declarator-id
22  position = limit | befaft ("everything" | ranked)
23  befaft = "before" | "after"
24  positions = "at" limit | befaft (("everything" | rankeds) [befaft ranked])*
25  ordinal = "first" | ("second" | "third" | etc) ["last"] | "last"
26  ranked = [ordinal] ...
27  rankeds = "all" [("except" | "but") ordinal*] ... | ["each" | "every" | "any" | ordinal*] ...
28  between = "between" (bound "and" relative-bound | ordinal "and" ordinal ...)
29  range = ([["everything"] "from"] bound | "everything") ("till" | "until") relative-bound
30  limit = "begin" | "front" | "end" | "back"
31  bound = limit | [befaft] ("everything" | ranked)
32  relative-bound = limit | [befaft] ("everything" | ranked) [relative]
33
34  Ellipsis denote a verbatim string, which may be quoted in backticks. Finally, x* = x ["and" x*].
35
36  This is an idealized grammar with LOTS of ambiguity. The parsers do their best to choose the most sensible interpretation of ambiguous commands.
37
38Design notes:
39
40  Consider "erase {x} and second {", given "{x}{y}". Here, "second {" has to be searched for in the original string, rather than the result of performing the first erase. However, consider "erase z" and move everything after x to front", given "xyz". The "everything after front" should /not/ include "z", but this requires performing the first erase. Also, consider "append z and move everything after x to front", given "xy". This should produce "yxz", not "yzx".
41
42  "use" is heavily biased toward whole-token edits, so users are encouraged to use those. This will not only produce better edits, it is also more readable.
43
44  Giving moves a single target makes "move 4 to end and 5 to begin" work, because otherwise it would be parsed as a move with two targets, the second of which, 5, is not a valid target.
45
46  Should "second last x before y" in "xxaxxy" designate the 'x' before or after 'a'?
47
48    We choose the latter, because it seems more natural, despite the curious result that "first x before y" now means the same as "last x before y".
49
50  Should "erase all x and y" mean "erase all x and all y" or "erase all x and the sole y"?
51
52    We choose the latter, because:
53    - it's easier to implement, because we don't need "and"-repetition nested under "all";
54    - it's safe, because if y occurs multiple times, a clear "y occurs multiple times" error will be emitted, whereas the former solution could result in unintended edit results.
55
56  Should "first and second last x" mean "(first and second) last x" or "first and (second last) x"?
57
58    I have no strong feelings on the matter. Currently it is interpreted to mean the second.
59
60  Should "from ..." / "until ..." bounds be inclusive or exclusive?
61
62    We choose the former, for no particular reason. Note that this default can be overridden by by saying "from after ..." / "until before ...".
63
64  Grammar guidelines:
65
66    - Ranges are never relative (but their bounds may be).
67    - Position specifications never mention ranges (this means that "everything" must not be a range).
68
69  Semantic choices:
70
71    - Ordinal specifications are always relative to the full string, so "erase from x until second b" in "bxabcb" produces "bxbcb", not "bxb".
72
73-}