The Address Argument

Yoinks most useful and powerful feature is the ability to target a specific region by adding an address to the end of a .yoink command.

The address syntax is similar in its simplest form to that of the text editor ed, but comes from the sam text editor and is more general. See Table II of The Text Editor sam paper for more details. Note that the displayed block is always rounded out to a full line at both ends.

Defining a Region

In our previous examples, we only included entire files into our root file. With the help of the address argument, however, we can target a specific region within a file.

Consider the sonnet-18-quatrains.txt file below:


#START stanza-1
Shall I compare thee to a summer’s day?
Thou art more lovely and more temperate:
Rough winds do shake the darling buds of May,
And summer’s lease hath all too short a date;
#END stanza-1

#START stanza-2
Sometime too hot the eye of heaven shines,
And often is his gold complexion dimm'd;
And every fair from fair sometime declines,
By chance or nature’s changing course untrimm'd;
#END stanza-2

#START stanza-3
But thy eternal summer shall not fade,
Nor lose possession of that fair thou ow’st;
Nor shall death brag thou wander’st in his shade,
When in eternal lines to time thou grow’st:
#END stanza-3

It contains regions that are marked by #START and #END. The #START and #END demarcations are not mandatory, and the # character holds no special meaning. They are just strings that can be latched on to by regular expressions in the address argument of the .yoink command.

We also add a unique identifier to each region, so we can distinguish one region from another. In this case we use the stanza index as a unique identifier.

Using the Address Argument

To target a specific region in a file, we add an address to the end of a .yoink command. The address is separated from the file name by a space.

Consider the following root file:


Sonnet 18: Shall I compare thee to a summer’s day?
By William Shakespeare

.yoink sonnet-18-quatrains.txt /START stanza-2/,/END stanza-2/

.yoink sonnet-18-rhyming-couplet.txt

.yoink sonnet-18-quatrains.txt /START stanza-3/,/END stanza-3/

.yoink sonnet-18-quatrains.txt /START stanza-1/,/END stanza-1/

Here you can see that all .yoink commands that point to sonnet-18-quatrains.txt have a second argument. This argument is an address. The addresses in our root file correspond to regions in our target file.

Let's analyze the address of the first .yoink command:


/START stanza-2/,/END stanza-2/

If you take a look at Table II of The Text Editor sam paper, we see that we have a regular expression /START stanza-2/ followed by the address mark ,, and finally we have a second regular expression /END stanza-2/.

Also note that there is no mention of the # in the address argument. Why then add a # in the first place? It is here to illustrate two points:

  1. The address argument is line based, just like everything else in Yoink. Partiallly matching a line (as long as it is unique) is sufficient to target the entire line.
  2. You can prepend your region demarcanstions with a comment identifier of the original file format. For example, you can use // in a lot of programming languages to mark comments.

The regular expressions here are just literal matches, but you can use more involved regular expression pattern matching syntax.

A Jumbled Result

Running the jumbled root file with Yoink, yields the following result:


Sonnet 18: Shall I compare thee to a summer’s day?
By William Shakespeare

#START stanza-2
Sometime too hot the eye of heaven shines,
And often is his gold complexion dimm'd;
And every fair from fair sometime declines,
By chance or nature’s changing course untrimm'd;
#END stanza-2

So long as men can breathe or eyes can see,
So long lives this, and this gives life to thee.

#START stanza-3
But thy eternal summer shall not fade,
Nor lose possession of that fair thou ow’st;
Nor shall death brag thou wander’st in his shade,
When in eternal lines to time thou grow’st:
#END stanza-3

#START stanza-1
Shall I compare thee to a summer’s day?
Thou art more lovely and more temperate:
Rough winds do shake the darling buds of May,
And summer’s lease hath all too short a date;
#END stanza-1

We succeeded in jumbling the output using addresses, but we now have the undesirable effect that the address demarcations ended up in the resulting output.

Omitting the address demarcations

In most cases, you want to omit the address demarcations from the resulting output. For example, in our case, we just want the text of the sonnet without the #START and #END lines.

Luckily we have a way to circumvent this: all lines that ends with the four characters OMIT are not included in the final output.

So if we were to append the demarcations with OMIT as shown below:


#START stanza-1 OMIT
Shall I compare thee to a summer’s day?
Thou art more lovely and more temperate:
Rough winds do shake the darling buds of May,
And summer’s lease hath all too short a date;
#END stanza-1 OMIT

#START stanza-2 OMIT
Sometime too hot the eye of heaven shines,
And often is his gold complexion dimm'd;
And every fair from fair sometime declines,
By chance or nature’s changing course untrimm'd;
#END stanza-2 OMIT

#START stanza-3 OMIT
But thy eternal summer shall not fade,
Nor lose possession of that fair thou ow’st;
Nor shall death brag thou wander’st in his shade,
When in eternal lines to time thou grow’st:
#END stanza-3 OMIT

And update the regular expressions in the root file to match the new demarcations:


Sonnet 18: Shall I compare thee to a summer’s day?
By William Shakespeare

.yoink sonnet-18-quatrains.txt /START stanza-2 OMIT/,/END stanza-2 OMIT/

.yoink sonnet-18-rhyming-couplet.txt

.yoink sonnet-18-quatrains.txt /START stanza-3 OMIT/,/END stanza-3 OMIT/

.yoink sonnet-18-quatrains.txt /START stanza-1 OMIT/,/END stanza-1 OMIT/

We get the desired jumbled output, but without the demarcation lines:


Sonnet 18: Shall I compare thee to a summer’s day?
By William Shakespeare

Sometime too hot the eye of heaven shines,
And often is his gold complexion dimm'd;
And every fair from fair sometime declines,
By chance or nature’s changing course untrimm'd;

So long as men can breathe or eyes can see,
So long lives this, and this gives life to thee.

But thy eternal summer shall not fade,
Nor lose possession of that fair thou ow’st;
Nor shall death brag thou wander’st in his shade,
When in eternal lines to time thou grow’st:

Shall I compare thee to a summer’s day?
Thou art more lovely and more temperate:
Rough winds do shake the darling buds of May,
And summer’s lease hath all too short a date;