ncbifile.hpp

ncbi源码

    /// 
    /// If group_mode is "fDefault", then default for group mode is set to
    /// - "fDefaultDirGroup" if this is a directory or to
    /// - "fDefaultGroup" if this is a file.
    ///
    /// If other_mode is "fDefault", then default for other mode is set to
    /// - "fDefaultDirOther" if this is a directory or to
    /// - "fDefaultOther" if this is a file.
    static void SetDefaultModeGlobal(EType entry_type,
                                     TMode user_mode,  // e.g. fDefault
                                     TMode group_mode = fDefault,
                                     TMode other_mode = fDefault);

    /// Set mode for this one object only.
    ///
    /// When "fDefault" is passed as value of the mode parameters, the mode
    /// will be set to the current global mode as specified
    /// by SetDefaultModeGlobal().
    virtual void SetDefaultMode(EType entry_type,
                                TMode user_mode,  // e.g. fDefault
                                TMode group_mode = fDefault,
                                TMode other_mode = fDefault);

protected:
    /// Get the default global mode.
    ///
    /// Used by derived classes like CDir and CFile.
    static void GetDefaultModeGlobal(EType  entry_type,
                                     TMode* user_mode,
                                     TMode* group_mode,
                                     TMode* other_mode);

    /// Get the default mode.
    ///
    /// Used by derived classes like CDir and CFile.
    void GetDefaultMode(TMode* user_mode,
                        TMode* group_mode,
                        TMode* other_mode) const;

private:
#  ifdef NCBI_OS_MAC
    FSSpec* m_FSS;      ///< Mac OS specific file description
#  else
    string m_Path;      ///< Full directory entry path
#  endif

    /// Which default mode: user, group, or other.
    ///
    /// Used as index into array that contains default mode values;
    /// so there is no "fDefault" as an enumeration value for EWho, here!
    enum EWho {
        eUser = 0,      ///< User mode
        eGroup,         ///< Group mode
        eOther          ///< Other mode
    };

    /// Holds default mode global values.
    static TMode m_DefaultModeGlobal[eUnknown][3/*EWho*/];

    /// Holds default mode values.
    TMode        m_DefaultMode[3/*EWho*/];
};



/////////////////////////////////////////////////////////////////////////////
///
/// CFile --
///
/// Define class to work with files.
///
/// Models the files in a file system. Basic functionality is derived from
/// CDirEntry and extended for files.

class NCBI_XNCBI_EXPORT CFile : public CDirEntry
{
    typedef CDirEntry CParent;    ///< CDirEntry is parent class

public:
    /// Constructor.
    CFile(const string& file);

    /// Destructor.
    virtual ~CFile(void);

    /// Check existence of file.
    virtual bool Exists(void) const;

    /// Get size of file.
    ///
    /// @return
    /// - size of file, if no error.
    /// - -1, if there was an error obtaining file size.
    Int8 GetLength(void) const;


    //
    // Temporary files
    //

    /// Temporary file creation mode
    enum ETmpFileCreationMode {
        eTmpFileCreate,     ///< Create empty file for each GetTmpName* call.
        eTmpFileGetName     ///< Get name of the file only.
    };

    /// Get temporary file name.
    ///
    /// @param mode
    ///   Temporary file creation mode.
    /// @return
    ///   Name of temporary file, or "kEmptyStr" if there was an error
    ///   getting temporary file name.
    /// @sa
    ///    GetTmpNameEx(), ETmpFileCreationMode
    static string GetTmpName(ETmpFileCreationMode mode = eTmpFileGetName);

    /// Get temporary file name.
    ///
    /// @param dir
    ///   Directory in which temporary file is to be created;
    ///   default of kEmptyStr means that system temporary directory will
    ///   be used or current, if a system temporary directory cannot
    ///   be determined.
    /// @param prefix
    ///   Temporary file name will be prefixed by value of this parameter;
    ///   default of kEmptyStr means that, effectively, no prefix value will
    ///   be used.
    /// @param mode
    ///   Temporary file creation mode. 
    ///   If set to "eTmpFileCreate", empty file with unique name will be
    ///   created. Please, do not forget to remove it youself as soon as it
    ///   is no longer needed. On some platforms "eTmpFileCreate" mode is 
    ///   equal to "eTmpFileGetName".
    ///   If set to "eTmpFileGetName", returns only the name of the temporary
    ///   file, without creating it. This method is faster but it have
    ///   potential race condition, when other process can leave as behind and
    ///   create file with the same name first.
    /// @return
    ///   Name of temporary file, or "kEmptyStr" if there was an error
    ///   getting temporary file name.
    /// @sa
    ///    GetTmpName(), ETmpFileCreationMode
    static string GetTmpNameEx(const string&        dir    = kEmptyStr,
                               const string&        prefix = kEmptyStr,
                               ETmpFileCreationMode mode   = eTmpFileGetName);


    /// What type of temporary file to create.
    enum ETextBinary {
        eText,          ///< Create text file
        eBinary         ///< Create binary file
    };

    /// Which operations to allow on temporary file.
    enum EAllowRead {
        eAllowRead,     ///< Allow read and write
        eWriteOnly      ///< Allow write only
    };

    /// Create temporary file and return pointer to corresponding stream.
    ///
    /// The temporary file will be automatically deleted after the stream
    /// object is deleted. If the file exists before the function call, then
    /// after the function call it will be removed. Also any previous contents
    /// of the file will be overwritten.
    /// @param filename
    ///   Use this value as name of temporary file. If "kEmptyStr" is passed
    ///   generate a temporary file name.
    /// @param text_binary
    ///   Specifies if temporary filename should be text ("eText") or binary
    ///   ("eBinary").
    /// @param allow_read
    ///   If set to "eAllowRead", read and write are permitted on temporary
    ///   file. If set to "eWriteOnly", only write is permitted on temporary
    ///   file.
    /// @return
    ///   - Pointer to corresponding stream, or
    ///   - NULL if error encountered.
    /// @sa
    ///   CreateTmpFileEx()
    static fstream* CreateTmpFile(const string& filename    = kEmptyStr,
                                  ETextBinary   text_binary = eBinary,
                                  EAllowRead    allow_read  = eAllowRead);

    /// Create temporary file and return pointer to corresponding stream.
    ///
    /// Similar to CreateTmpEx() except that you can also specify the directory
    /// in which to create the temporary file and the prefix string to be used
    /// for creating the temporary file.
    ///
    /// The temporary file will be automatically deleted after the stream
    /// object is deleted. If the file exists before the function call, then
    /// after the function call it will be removed. Also any previous contents
    /// of the file will be overwritten.
    /// @param dir
    ///   The directory in which the temporary file is to be created. If not
    ///   specified, the temporary file will be created in the current 
    ///   directory.
    /// @param prefix
    ///   Use this value as the prefix for temporary file name. If "kEmptyStr"
    ///   is passed generate a temporary file name.
    /// @param text_binary
    ///   Specifies if temporary filename should be text ("eText") or binary
    ///   ("eBinary").
    /// @param allow_read
    ///   If set to "eAllowRead", read and write are permitted on temporary
    ///   file. If set to "eWriteOnly", only write is permitted on temporary
    ///   file.
    /// @return
    ///   - Pointer to corresponding stream, or
    ///   - NULL if error encountered.
    /// @sa
    ///   CreateTmpFile()
    static fstream* CreateTmpFileEx(const string& dir         = ".",
                                    const string& prefix      = kEmptyStr,
                                    ETextBinary   text_binary = eBinary,
                                    EAllowRead    allow_read  = eAllowRead);
};



/////////////////////////////////////////////////////////////////////////////
///
/// CDir --
///
/// Define class to work with directories.
///
/// NOTE: Next functions are unsafe in multithreaded applications:
///       - static bool Exists() (for Mac only);
///       - bool Exists() (for Mac only).

class NCBI_XNCBI_EXPORT CDir : public CDirEntry
{
    typedef CDirEntry CParent;  ///< CDirEntry is the parent class

public:
    /// Constructor.
    CDir();
#  if defined(NCBI_OS_MAC)
    /// Constructor - for Mac OS.
    CDir(const FSSpec& fss);
#  endif
    /// Constructor using specified directory name.
    CDir(const string& dirname);

    /// Destructor.
    virtual ~CDir(void);

    /// Check if directory "dirname" exists.
    virtual bool Exists(void) const;

    /// Get user "home" directory.
    static string GetHome(void);

    /// Get temporary directory.
    static string GetTmpDir(void);

    /// Get the current working directory.
    static string GetCwd();

    /// Define a vector of pointers to directory entries.
    typedef vector< AutoPtr<CDirEntry> > TEntries;

    /// Modes for GetEntries
    /// @sa GetEntries
    enum EGetEntriesMode {
        eAllEntries,        ///< All included
        eIgnoreRecursive    ///< Supress self recursive elements (like "..")
    };


    /// Get directory entries based on the specified "mask".
    ///
    /// @param mask
    ///   Use to select only files that match this mask. Do not use file mask
    ///   if set to "kEmptyStr".
    /// @return
    ///   An array containing all directory entries.
    TEntries GetEntries(const string&   mask = kEmptyStr,
                        EGetEntriesMode mode = eAllEntries) const;

    /// Get directory entries based on the specified set of"masks".
    ///
    /// @param mask
    ///   Use to select only files that match this set of masks.
    /// @return
    ///   An array containing all directory entries.
    TEntries GetEntries(const vector<string>& masks,
                        EGetEntriesMode       mode = eAllEntries) const;

    /// Create the directory using "dirname" passed in the constructor.
    /// 
    /// @return
    ///   TRUE if operation successful; FALSE, otherwise.
    bool Create(void) const;

    /// Create the directory path recursively possibly more than one at a time.
    ///
    /// @return
    ///   TRUE if operation successful; FALSE otherwise.
    bool CreatePath(void) const;

    /// Delete existing directory.
    ///
    /// @param mode
    ///   - If set to "eOnlyEmpty" the directory can be removed only if it
    ///   is empty.
    ///   - If set to "eNonRecursive" remove only files in directory, but do
    ///   not remove subdirectories and files in them.
    ///   - If set to "eRecursive" remove all files in directory, and
    ///   subdirectories.
    /// @return
    ///   TRUE if operation successful; FALSE otherwise.
    /// @sa
    ///   EDirRemoveMode
    virtual bool Remove(EDirRemoveMode mode = eRecursive) const;
};


/// File finding flags
enum EFindFiles {
    fFF_File       = (1<<0),             ///< find files
    fFF_Dir        = (1<<1),             ///< find directories
    fFF_Recursive  = (1<<2),             ///< decsend into sub-dirs
    fFF_Default    = fFF_File | fFF_Dir  ///< default behaviour
};

/// bitwise OR of "EFindFiles"
typedef int TFindFiles; 


/// Find files in the specified directory
template<class TFindFunc>
TFindFunc FindFilesInDir(const CDir&            dir,
                         const vector<string>&  masks,
                         TFindFunc              find_func,
                         TFindFiles             flags = fFF_Default)
{
    CDir::TEntries contents = dir.GetEntries(masks, CDir::eIgnoreRecursive);

    ITERATE(CDir::TEntries, it, contents) {
        const CDirEntry& dir_entry = **it;

        if (dir_entry.IsDir()) {
            if (flags & fFF_Dir) {
                find_func(dir_entry);
            }

            if (flags & fFF_Recursive) {
                CDir nested_dir(dir_entry.GetPath());
                find_func = 
                  FindFilesInDir(nested_dir, masks, find_func, flags);
            }
        }
        else
        if (dir_entry.IsFile() && (flags & fFF_File)) {
            find_func(dir_entry);
        }
    } // ITERATE
    return find_func;
}


/// Generic algorithm for file search
///
/// Algorithm scans the provided directories using iterators,
/// finds files to match the masks and stores all calls functor
/// object for all found entries
/// Functor call should match: void Functor(const CDirEntry& dir_entry)
///

template<class TPathIterator, 
         class TMaskIterator, 
         class TFindFunc>
TFindFunc FindFiles(TPathIterator path_begin,
                    TPathIterator path_end,
                    TMaskIterator mask_begin,
                    TMaskIterator mask_end,
                    TFindFunc     find_func,
                    TFindFiles    flags = fFF_Default)
{
    vector<string> masks;
    for (; mask_begin != mask_end; ++mask_begin) {
        masks.push_back(*mask_begin);
    }

    for (; path_begin != path_end; ++path_begin) {
        const string& dir_name = *path_begin;

        CDir dir(dir_name);
        find_func = FindFilesInDir(dir, masks, find_func, flags);
    } // for
    return find_func;
}

/// Functor for generic FindFiles, adds file name to the specified container
template<class TNames>
class CFindFileNamesFunc
{
public:
    CFindFileNamesFunc(TNames& names) : m_FileNames(&names) {}

    void operator()(const CDirEntry& dir_entry)
    {
        m_FileNames->push_back(dir_entry.GetPath());
    }
protected:
    TNames*  m_FileNames;
};


/////////////////////////////////////////////////////////////////////////////
///
/// Utility algorithm scans the provided directories using iterators
/// finds files to match the masks and stores all found files in 
/// the container object.
///

template<class TContainer, class It1>
void FindFiles(TContainer&           out, 
               It1                   first_path, 
               It1                   last_path, 
               const vector<string>& masks,
               TFindFiles            flags = fFF_Default)
{
    CFindFileNamesFunc<TContainer> func(out);
    FindFiles(first_path, last_path, 
              masks.begin(), masks.end(), func, flags);
}