/*!
* @class Pipe
*
* @headerfile <seqan/pipe.h>
*
* @brief Pipes are pop-passive pipeline modules.
*
* @signature template <typename TInput, typename TSpec> class Pipe;
*
* @tparam TSpec The specializing type.
* @tparam TInput The type of the pipeline module this module reads from. Use
* Bundle2, Bundle3, etc. to read from more than one module.
*
* Use @link Pipe#Value @endlink to get the output type of a given Pipe (returns
* <tt>Value<TInput>::Type</tt> by default).
*
* Use Size to get the size type of a given Pipe (returns
* <tt>Size<TInput>::Type</tt> by default).
*
* @mfn Pipe#Value
*
* @brief Return value type of the Pipe specialization.
*
* @signature Value<TPipe>::Type;
*
* @tparam TPipe The Pipe specialization to query.
*
* @return Type The resulting value type.
*
* @mfn Pipe#Size
*
* @brief Return size type of the Pipe specialization.
*
* @signature Size<TPipe>::Type;
*
* @tparam TPipe The Pipe specialization to query.
*
* @return Type The resulting size type.
*
* @fn Pipe::Pipe
*
* @brief Constructor
*
* @signature Pipe::Pipe(in);
*
* @param[in] in Reference to an input pipe.
*
* @fn Pipe#length
*
* @headerfile <seqan/pipe.h>
*
* @brief Length of the pipe.
*
* @signature TSize length(pipe);
*
* @param[in] pipe The Pipe to query for its size.
*
* @return TSize The size of the pipe.
*
* @fn Pipe#front
*
* @headerfile <seqan/pipe.h>
*
* @brief Gets the first element of the remaining stream.
*
* @signature TValue front(object);
*
* @param[in] object A pop-passive pipeline module.
*
* @return TValue The first element of the remaining input stream. Return type
* is <tt>Value<TObject>::Type</tt> for <tt>object</tt>
* type <tt>TObject</tt>.
*
* Pipe#front or Pipe#pop can only be called within a read process surrounded by
* beginRead and endRead.
*
* @see Pipe#pop
*
* @fn Pipe#pop
*
* @headerfile <seqan/pipe.h>
*
* @brief Pops the first element of the remaining stream.
*
* @signature void pop(pipe[, ref]);
*
* @param[in,out] pipe A pop-passive pipeline module.
* @param[out] ref Reference to the result. Result type is
* <tt>Value<TObject>::Type</tt> for <tt>object</tt> type
* <tt>TObject</tt>. Returns the first element of the remaining
* input stream.
*
* In contrast to Pipe#front this function also steps one element further.
*
* Pipe#front or Pipe#pop can only be called within a read process surrounded by
* beginRead and endRead.
*
* @fn Pipe#atEnd
*
* @brief Check whether the @link Pipe @endlink object is at end.
*
* @signature bool atEnd(pipe);
*
* @param[in] pipe The @link Pipe @endlink object to query.
*
* @return bool true in case of the pipe being at the end, false otherwise.
*
* @fn Pipe#beginRead
*
* @headerfile <seqan/pipe.h>
*
* @brief Initiates a read process.
*
* @signature bool beginRead(object);
*
* @param[in,out] object A pop-passive pipeline module.
*
* @return bool true on success, false on failure.
*
* <tt>beginRead</tt> rewinds the output stream, prepares <tt>object</tt> for
* succeeding reads, and typically calls <tt>beginRead</tt> of the input
* pipeline modules.
*
* A read process must be terminated with endRead. Nested read processes are not
* allowed.
*
* @see Pipe#endRead
*
* @fn Pipe#endRead
*
* @headerfile <seqan/pipe.h>
*
* @brief Terminates a read process.
*
* @signature bool endRead(object);
*
* @param[in,out] object A pop-passive pipeline module.
*
* @return bool true on success, false on failure.
*
* <tt>endRead</tt> closes the output stream, frees resources possibly allocated
* by beginRead, and typically calls <tt>endRead</tt> of the input pipeline
* modules.
*
* @see Pipe#beginRead
*
* @fn Pipe#assign
*
* @headerfile <seqan/pipe.h>
*
* @brief Assigns one object to another object.
*
* @signature void assign(target, source);
*
* @param[out] target Reference to assign to.
* @param[in] source Value to assign.
*
* Assign value of source to target.
*/