What is the purpose of Branch?

[dodyg]

http://wyam.io/modules/branch

[daveaglick]

The idea is to allow a sequence of modules to execute without impacting the "main" module sequence. In other words, Branch executes it's child modules as if there were no Branch module in the sequence, but then when it's child modules are done, the main sequence of modules is executed as if there were no Branch. I'm not sure either of those explanations made a ton of sense, so it's probably best explained with an example. Assume you have a module, AddOne, that just adds 1 to whatever numeric value is in the content of the input document(s). The input and output content of the following configuration should demonstrate what Branch does:

                            // Input Content      // Output Content
Pipelines.Add(
    AddOne(),       // [Empty]                // 0
    AddOne(),       // 0                          // 1
    AddOne(),       // 1                          // 2
    Branch(
        AddOne(),   // 2                          // 3
        AddOne()    // 3                          // 4
    ),
    AddOne(),       // 2                          // 3
    AddOne()        // 3                          // 4
);

You can see that the input content to the AddOne modules after the Branch is the same as the input content to the AddOne modules inside the branch. The result of the modules in the Branch had no impact on those modules that run after the Branch. This is true for both content and metadata. If any modules inside the Branch created or changed metadata, it would be forgotten once the Branch was done.

Now, why would you need this? There are a couple of use cases I can think of. One might be if you need to process your input documents multiple different ways. Branch would let you keep the input content to each transformation the same. Another case might be if you want to write the documents to disk multiple times but don't want to preserve the metadata that WriteFiles adds from one write to the next.

[dodyg]

Thank you for the explanation. This explanation I think should go to the documentation because it clearly describes the purpose of http://wyam.io/modules/branch.

[daveaglick]

Good point - done.