SFK: help chain (Help)

Команда: help chain
sfk command chaining reference:

   several commands can be combined in a so-called "command chain".
   this is done by appending command names prefixed by "+", for example:

   sfk list docs .txt +ffilter -+foo
      "list" produces a filename list and passes this to "filefilter".
      ffilter reads the contents of these files, looking for the word "foo".

   chain data types
      three types of data can be passed from one command to another:

         - filename lists.
         - plain text records (lines).
         - stream text or binary data.

      output is dependent on command. for example, sfk select produces
      filename lists, sfk filter makes plain text records, xex/xed can
      produce streams of text or binary data.

   chain data type conversion
      vice versa, some commands accept filenames, or text input, or even both.
      depending on what you want to do, it may be necessary to convert between
      this types of data. this can be done by the keywords:

         +texttofilenames or +ttf
         +filenamestotext or +ftt

      however, most sfk commands try to do such conversions automatically.

   using chain data between commands
      sfk cmd1 ... +then cmd2   does not pass any data to cmd2,
                                prints cmd1 output to terminal.
      sfk ... +toterm           dumps current chain content to terminal.
      sfk ... +tofile outfile   dumps chain content to file outfile.
      sfk ... +tovoid +cmd2     does not pass any data to cmd2,
                                drops cmd1 chain text silently.
      in all cases, the chain is cleared. if another command is following,
      it will receive no input from the chain.

   no data tunneling
      chain data can only be passed
      - from a data producing command like  +echo mytext
      - directly to the following command
        if it consumes data like            +setvar myvar
      - but not through a non consumer like +tell othertext
      bad example:
        sfk echo mytext +tell hello +setvar a
          stops with an error at setvar: no chain data
      good example:
        sfk echo mytext +setvar a +tell hello +getvar
          mytext is stored, hello is printed

      in other words, in a command chain like:
      sfk cmd1 +cmd2 +cmd3 +cmd4 +cmd5
      it is not possible to send data from cmd1 to cmd3/4/5
      if cmd2 does not use any chain data (e.g. if, tell).
      since sfk 1.9.3 this bypassing of cmd2 is disabled
      to avoid conflicts by unwanted chain data in cmd3/4/5.
      the only exception is: cmd1 +label name +cmd2
      use global option -keepdata or set environment variable
         set SFK_CONFIG=keepdata
      for the sfk 1.9.2 behaviour which was inconsistent
      and worked only with some commands.

   using chain data with call / label / end
      sfk ... +call myfunc      passes no chain data into myfunc
      sfk ... +tcall myfunc     passes text data into myfunc
      sfk ... +fcall myfunc     passes filenames into myfunc
      sfk label ... +end        returns no chain data
      sfk label ... +tend       returns text data
      sfk label ... +fend       returns a filename list

   if chaining stops with "no files, stopping at x":

      this means command x expects a list of filenames,
      but the previous command did not produce any.
      you have three options then:

      - use +then x if command x should never receive any
        filenames from a previous command.

      - or add -keepchain at the preceeding command, or
        directly after sfk, to enforce execution of command x.

      - or use -nonote to suppress the "no files" message.

   scope and lifetime of options
      most options are valid only for the command where they are specified.
      if another command follows in the chain, the option is reset.
      but some options may also be specified on a global scope.
      read more on that under "sfk help options".

   global options
      -tracechain   get verbose output while sfk steps
                    through a command chain

   more in the SFK Book
      the SFK Book contains long examples with input,
      output, script and detailed command explanations.
      type "sfk book" for more.

   see also
      sfk batch     create an example script
      sfk help var  how to use sfk variables
      sfk script    about sfk scripting
      sfk call      calling a function in a script
      sfk label     possible options with label
      sfk if        conditional execution
      sfk goto      jump to a local label
      sfk for       repeat commands n times
      sfk load      load text or data for chaining