Page MenuHomePhabricator

Syntax
Updated 2,387 Days AgoPublic

Overview

Instead of having dozens of different checkboxes and the like, Redstring 3.0 should use a simple(-ish) syntax to allow for various patterns of repetition and synchronization for columns.

The basic format for a substitution is {<pass>:<column>:[rule]}.

NOTE: Yes, this makes all Redstring 2.0 projects completely out-of-date, but that's unavoidable. Making this system have the default behavior of Redstring 2.0's syntax would be a nightmare.

Benefits

This single-handedly resolves T455: Attempts to use column not referenced in model., as passes are no longer implicit to the columns. In addition, it allows implementation of T457: Allow a single column substitution to be treated separately..

In short, the user may quickly create all manner of synchronized, repeated, and independent column substitutions using this syntax, giving them further control over Redstring's behavior.

Syntax

Again, the basic format for a substitution is {<pass>:<column>:[rule]}.

For this entire section, we'll assume following columns:

ABCD
1aar
2bbs
3cct
4du
5ev
w
x
y
z

Examples will be displayed with the model in the tab, and the result in the box.

MODEL
The result
goes here.

Pass

Each "pass" has its own master incrementer, which is used to determine which column item should be used for a given result. Passes are performed in ascending order, with all of that pass's substitutions being performed.

For example...

{1:A}{2:C}
1a
2a
3a
4a
5a
1b
2b
3b
4b
5b
1c
2c
3c
4c
5c

Unlike in 2.x, where pass order was implicit, Redstring 3.x requires a pass to be specified for every substitution.

Column Reuse

One use of passes is in reusing a single column, such as in...

{2:C}{1:C}
aa
ab
ac
ba
bb
bc
ca
cb
cc

In the above example, note how the passes can be called in any order in the model.

Column Synchronization

Another use of passes is in synchronizing two columns, such as in...

{1:A}{1:B}{2:C}
1aa
2ba
3ca
4da
5ea
1ab
2bb
3cb
4db
5eb
1ac
2bc
3cc
4dc
5ec

In that example, you'll notice that columns A and B were kept in sync with each other, but C was not.

Columns and Auto-Incrementers

Normally, the second value in a substitution would be a column ID (A, B, C, etc.), as indicated by the Redstring interface. However, one may also use a numerical auto-incrementers, such as 1-100. Such auto-incrementers will act like a reference to a column with all the values in the specified range.

{1:A}{2:7-9}
17
27
37
47
57
18
28
38
48
58
19
29
39
49
59

Auto-incrementers may also be written in reverse, thereby becoming decrementers. 5-3 would be valid, as in the following example.

{1:A}{2:5-3}
15
25
35
45
55
14
24
34
44
54
13
23
33
43
53

Rule

The Rule is an optional argument that changes the synchronization behavior for columns of different lengths. (Default: p.)

  • p will pad a column that has reached its end with empty values, effectively stopping the column at its end without stopping any other columns in the pass. (Default)
  • r causes a column that has reached its end to repeat from the beginning.
  • s forces the pass to stop as soon as the columns has reached the end. This overrides all conflicting options.

Padding

Padding is the default, will simply omit values from a column once it has reached the end.

{1:A}{1:C:p}
1a
2b
3c
4
5

Since column A has five values, but column C has only three, the last two results have nothing from column C.

Repetition

Repetition causes a column that has reached its end to start over from the beginning if it runs out of values.

{1:A}{1:C:r}
1a
2b
3c
4a
5b

In this case, we see column C's first two values repeating on the fourth and fifth result.

Stop Pass

The s rule will force the pass to stop as soon as the column runs out, overriding any other rules that might conflict.

{1:A}{1:C:s}
1a
2b
3c

Note that, though column A has five values, only three results are produced.

However, the opposite doesn't do anything unusual...

{1:A:s}{1:C}
1a
2b
3c
4
5

We see column C following the default rule (p). The s on column A has no effect, since the pass would stop at this point anyway.

In a situation with more than two columns, we may put the s on the second-shortest, and another argument on the shortest, to further customize the pass:

{1:A:s}{1:C:r}{1:D}
1ar
2bs
3ct
4au
5bv

In the example above, we see that the shortest column, C, was repeated when it ran out, following its r rule. However, since column A was given the s rule, we end up with five results, consistent with column A's five values. Redstring ignores the fact that column D has 9 values.

Only one rule is allowed per substitution.

Syntax Highlighting

The Redstring 3.0 editor should use a "positive highlighting" approach, meaning that valid substitutions should be highlighted (probably bold) to stand out from the rest of the text, and everything else displayed as normal text. All valid substitutions will match the regex {\d:((\d*-\d*)|[A-Z])(:[prs])?}.

This approach will also make it easier to have literal curly braces, as it would be very rare to see something that looked like a substitution, even in code.

We should also allow have an option in the interface to highlight invalid substitutions as well, always matching the regex {.:.(:.*)?}. Even here, all other potential "invalid substitutions" should be ignored, in favor of the idea that curly braces may be in similar use in the code or text being processed.

Last Author
jcmcdonald
Last Edited
Jan 26 2016, 4:11 PM