Textflow Variables

Until now, we’ve been discussing the Working Text which is passed between commands. The most common way of working with Textflow is to simply pass the Working Text “down” the Pipeline from beginning to end.

However, this can be limiting. If you need to slice up data into multiple parts and do work on each, it can be limiting to have one Working Text object.

In reality, what’s passed between Commands is something called Working Data. The Text is just one property of this object.

Working Data also contains a collection of Variables. These are “containers” for pieces of data. You can write to and read from these Variables to store and retrieve multiple pieces of data within the same pipeline.

Here’s a practical example:

http -url:http://domain.com/some/path
# The Working Text is now an entire HTML document

# Let's write this data to a Variable to keep it handy
# This command writes all the working text to a variable
write-to -var:html

# The HTML document is still the working text
# Now let's get the title from it
extract -selector:title

# And now let's write THAT to another variable
write-to -var:title

# Since the working text is now just the title, let's "reset" it to all the HTML
read-from -var:html

# Now let's get some body content and write that to another variable
extract -selector:article
write-to -var:body

# We now have three variables: html, title, and body
# Let's turn it into an HTML structure
template-json -template:$aside_template

$aside_template
<aside>
  <header>{{ vars.title }}</header>
  <main>{{ vars.body }}</main>
</aside>

By using write-to and read-from, we’re essentially “setting aside” the Working Text, and then resetting it, just to slice it up a different way and set that aside. After dividing it up into pieces, when re-assemble it at the end. (template-json has all the Variables injected as an object called vars.)

Command Redirection

Using write-to and read-from can get confusing. There’s actually a simpler way to work with variables that breaks the rule of “Working Text is always passed between Commands.”

We can “redirect” command output directly to a variable. When we do this, the Working Text does not change and is passed to the next Command unchanged. The output of the Command is not written to the working text, but is instead written to the variable we specify.

Here’s the same example from above:

http -url:http://domain.com/some/path
extract -selector:title => title
extract -selector:body => article

template-json … [same as above]

The two extract commands do not modify the Working Text – meaning, the second extract is working from the same text that the first extract is working from. Both of them perform their work, then send the output directly to the named variable and just pass the Working Text through.