/*!
* @class FormattedFile
*
* @headerfile <seqan/stream.h>
*
* @brief Base class for formatted file I/O.
*
* @signature template <typename TFileFormat, typename TDirection[, typename
* TSpec]> struct FormattedFile;
*
* @tparam TFileFormat A type specifying the file format.
* @tparam TDirection The direction of the file, one of @link
* DirectionTags#Input Input @endlink or @link
* DirectionTags#Output @endlink.
* @tparam TSpec A tag for the specialization, defauls to <tt>void</tt>.
*
* FormattedFile provides the following basic I/O operations on formatted files:
*
* <ul> <li>Open a file given its filename or attach to an existing stream like
* stdin/stdout.</li> <li>Guess the file format from the file content or
* filename extension.</li> <li>Set the file format manually.</li> <li>Access
* compressed or uncompressed files transparently.</li> </ul>
*
* FormattedFile encapsulates a VirtualStream and provides access to its @link
* StreamConcept#DirectionIterator @endlink. Each instance of FormattedFile
* keeps a @link FormattedFile#FormattedFileContext @endlink while reading or
* writing the formatted file.
*
* @mfn FormattedFile#FileFormat
*
* @brief Metafunction for retrieving the file format type of a formatted file.
*
* @signature FileFormat<TFormattedFile>::Type;
*
* @tparam TFormattedFile The formatted file type to query for its file format
* type.
*
* @return Type The resulting @link FileFormats @endlink file formats type.
*
* @mfn FormattedFile#FormattedFileContext
*
* @brief Returns the context type for a FormattedFile.
*
* @signature FormattedFileContext<TFormattedFile, TStorageSpec>::Type
*
* @tparam TFormattedFile The FormattedFile to query.
* @tparam TStorageSpec The storage specification, passed as specialization to
* any @link StringSet @endlink contained in the context.
* @tparam Type The resulting FormattedFile context type.
*
* @fn FormattedFile::operatorTDependentContext
*
* @brief Allows conversion to a dependent context for the FormattedFile
*
* @signature TDependentContext & FormattedFile::operator TDependentContext();
*
* @return TDependentContext The dependent context of this FormattedFile.
*
* @fn FormattedFile::getFileExtensions
*
* @brief Static function that returns a list of allowed file format extension.
*
* @signature TExtensionVector getFileExtensions()
*
* @return TExtensionVector A <tt>std::vector<std::string></tt> with the
* allowed file extensions.
*
* @fn FormattedFile#FormattedFile
*
* @brief Provides default construction.
*
* @signature FormattedFile::FormattedFile();
* @signature FormattedFile::FormattedFile(fileName[, openMode]);
* @signature FormattedFile::FormattedFile(stream);
* @signature FormattedFile::FormattedFile(other);
* @signature FormattedFile::FormattedFile(otherContext);
* @signature FormattedFile::FormattedFile(otherContext, fileName[, openMode]);
* @signature FormattedFile::FormattedFile(otherContext, stream);
*
* @param[in] fileName Path to file to open, <tt>char const *</tt>.
* @param[in] openMode Optionally, the file open mode, default obtained from
* <tt>TDirection</tt>.
* @param[in] stream A <tt>std::basic_istream<></tt> to read from or
* <tt>std::basic_ostream<></tt> to write to, depending
* on <tt>TDirection</tt>.
* @param[in] other A second FormattedFile, this FormattedFile's dependent
* context will depend on <tt>other</tt>'s dependent context.
* @param[in] otherContext The dependent context of another FormattedFile, this
* FormattedFile's dependent context will depend on
* <tt>otherContext</tt>.
*
* @throw IOError The variants that accept the <tt>fileName</tt> parameter throw
* an exception of this type in case opening the file fails.
*
* @fn FormattedFile#format
*
* @brief Return the format of a FormattedFile.
*
* @signature TFormat format(file);
*
* @param[in] file The FormattedFile to check.
*
* @return TFormat The type as returned from @link FormattedFile#FileFormat
* @endlink.
*
* @fn FormattedFile#setFormat
*
* @brief Set the format of a FormattedFile.
*
* @signature void setFormat(file, format);
*
* @param[in,out] file The FormattedFile to change.
* @param[in] format The @link FormattedFile#FileFormat @endlink to set.
*
* @fn FormattedFile#guessFormat
*
* @brief Guess the format of an open FormattedFile.
*
* @signature bool guessFormat(file);
*
* @param[in,out] file The open FormattedFile for which the format is to be
* guessed.
*
* @fn FormattedFile#open
*
* @brief Open a FormattedFile.
*
* @signature bool open(file, fileName);
*
* @param[in,out] file The FormattedFile to open.
* @param[in] fileName The name of the file open.
*
* @return bool <tt>true</tt> in the case of success, <tt>false</tt> otherwise.
*
* @fn FormattedFile#close
*
* @brief Close a FormattedFile.
*
* @signature bool close(file);
*
* @param[in,out] file The FormattedFile to close.
*
* @return bool <tt>true</tt> in the case of success, <tt>false</tt> otherwise.
*
* @fn FormattedFile#atEnd
*
* @brief Determines whether a FormattedFile is at the end.
*
* @signature bool atEnd(file);
*
* @param[in,out] file The FormattedFile to check.
*
* @return bool <tt>true</tt> in the case of success, <tt>false</tt> otherwise.
*
* @fn FormattedFile#context
*
* @brief Return the FormattedFile's dependent context object.
*
* @signature TDependentContext & context(file);
*
* @param[in,out] file The FormattedFile to query for its context.
*
* @return TDependentContext The dependent context, type as returned from @link
* FormattedFile#FormattedFileContext @endlink.
*
* @fn FormattedFile#getFileExtensions
*
* @brief Static function that returns a list of allowed file format extension.
*
* @signature TExtensionVector getFileExtensions(file)
*
* @param[in] file The FormattedFile to query.
*
* @return TExtensionVector A <tt>std::vector<std::string></tt> with the
* allowed file extensions.
*
* This is a shortcut to @link FormattedFile#getFileExtensions @endlink.
*/