Merge branch 'release-2.140.101'
[feisty_meow.git] / nucleus / library / filesystem / directory.h
1 #ifndef DIRECTORY_CLASS
2 #define DIRECTORY_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : directory                                                         *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             *
9 *******************************************************************************
10 * Copyright (c) 2001-$now By Author.  This program is free software; you can  *
11 * redistribute it and/or modify it under the terms of the GNU General Public  *
12 * License as published by the Free Software Foundation; either version 2 of   *
13 * the License or (at your option) any later version.  This is online at:      *
14 *     http://www.fsf.org/copyleft/gpl.html                                    *
15 * Please send any updates to: fred@gruntose.com                               *
16 \*****************************************************************************/
17
18 #include <basis/astring.h>
19 #include <basis/contracts.h>
20 #include <structures/string_array.h>
21
22 namespace filesystem {
23
24 //! Implements a scanner that finds all filenames in the directory specified.
25
26 class directory : public virtual basis::root_object
27 {
28 public:
29   directory(const basis::astring &path, const char *pattern = "*");
30     //!< opens up the "path" specified and scans for files and subdirectories.
31     /*!< if the location was accessible, then the good() method returns true.
32     note that the "path" should just be a bare directory without any
33     wildcards attached.  the "pattern" can be specified if you wish to
34     strain out just a subset of the files in the directory.  it must meet
35     the same requirements that the operating system places on wildcard
36     patterns. */
37
38   directory(const directory &to_copy);
39
40   virtual ~directory();
41
42   directory &operator =(const directory &to_copy);
43
44   DEFINE_CLASS_NAME("directory");
45
46   bool good() const { return _scanned_okay; }
47     //!< true if the directory existed and its contents were readable.
48
49   const basis::astring &path() const;
50     //!< returns the directory that we manage.
51
52   const basis::astring &pattern() const;
53     //!< returns the pattern that the directory class scans for.
54
55   static basis::astring absolute_path(const basis::astring &relative_path);
56     //!< returns the absolute path to a file with "relative_path".
57     /*!< an empty string is returned on failure. */
58
59   bool reset(const basis::astring &path, const char *pattern = "*");
60     //!< gets rid of any current files and rescans the directory at "path".
61     /*!< a new "pattern" can be specified at this time also. */
62
63   bool move_up(const char *pattern = "*");
64     //!< resets the directory to be its own parent.
65
66   bool move_down(const basis::astring &subdir, const char *pattern = "*");
67     //!< changes down into a "subdir" of this directory.
68     /*!< the "subdir" should be just the file name component to change into.
69     absolute paths will not work.  for example, if a directory "/l/jed" has
70     a subdirectory named "clampett", then use: @code
71       my_dir->move_down("clampett") @endcode
72     */
73
74   bool rescan();
75     //!< reads our current directory's contents over again.
76
77   const structures::string_array &files() const;
78     //!< returns the list of files that we found in this directory.
79     /*!< these are all assumed to be located in our given path.  to find out
80     more information about the files themselves, construct a filename object
81     with the path() and the file of interest. */
82     
83   const structures::string_array &directories() const;
84     //!< these are the directory names from the folder.
85     /*!< they can also be examined using the filename object.  note that
86     this does not include the entry for the current directory (.) or the
87     parent (..). */
88
89   // static methods of general directory-related interest.
90
91   static basis::astring current();
92     //!< returns the current directory, as reported by the operating system.
93
94   static bool make_directory(const basis::astring &path);
95     //!< returns true if the directory "path" could be created.
96
97   static bool remove_directory(const basis::astring &path);
98     //!< returns true if the directory "path" could be removed.
99
100   static bool recursive_create(const basis::astring &directory_name);
101     //!< returns true if the "directory_name" can be created or already exists.
102     /*!< false returns indicate that the operating system wouldn't let us
103     make the directory, or that we didn't have sufficient permissions to
104     access an existing directory to view it or move into it. */
105
106 private:
107   bool _scanned_okay;  //!< did this directory work out?
108   basis::astring *_path;  //!< the directory we're looking at.
109   structures::string_array *_files;  //!< the list of files.
110   structures::string_array *_folders;  //!< the list of directories.
111   basis::astring *_pattern;  //!< the pattern used to find the files.
112 };
113
114 } //namespace.
115
116 #endif
117