casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Path.h
Go to the documentation of this file.
1 //# Path.h: Path name of a file
2 //# Copyright (C) 1993,1994,1995,1996,1997,1998,1999,2000
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 
29 #ifndef CASA_PATH_H
30 #define CASA_PATH_H
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
35 
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 // <summary>
40 // Path name of a file
41 // </summary>
42 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
43 // </reviewed>
44 
45 // <prerequisite>
46 // <li> Basic knowledge of the UNIX file system
47 // </prerequisite>
48 
49 // <etymology>
50 // The term 'path' is the standard term for describing the location of a file
51 // in a hierarchy of possibly nested directories. In order to find a
52 // particular file you must travel a specific path strating from a known
53 // point. We use the term in its standard sense in this class.
54 // </etymology>
55 
56 // <synopsis>
57 // This class can be used to describe a pathname. One can also create,
58 // validate, parse (get base or directory names or original, expanded or
59 // absolute names), query and append strings. The client programmer can
60 // give a string, at construction, which describes a path. This string can
61 // be a relative or an absolute name. Environment variables and a tilde
62 // (with or without user name) can also be used in the string and will
63 // be expanded by the function expandedName.
64 // <br> The function
65 // Once a Path has been constructed, you can query the object for its
66 // original name, expanded name, absolute name, the name of the directory
67 // where it is found or the name of only the file. Expanding the path name
68 // means that possible environment variables and tilde get expanded.
69 // There are also functions to get the length or maximum length of a path.
70 // Pathnames can also be checked on correctness and they can be checked
71 // if they conform the POSIX standard.
72 // </synopsis>
73 
74 // <example>
75 // In this example a few pathnames are created.
76 // <srcblock>
77 // Path test1("~/test/$TEST1/.."); // absolute path
78 // Path test2("/$HOME/./analyse"); // absolute path
79 // Path test3("myFile"); // relative path
80 //
81 // cout << test1.originalName() << endl;
82 //
83 // // Test1 is according the POSIX standard
84 // if (test1.isStrictlyPosix()){
85 // cout << "test1 is strictly POSIX << endl;
86 // }
87 //
88 // // Test1 is valid
89 // if (test1.isValid()){
90 // cout << test1.isValid() << endl;
91 // }
92 //
93 // // if "TEST1=$TEST2 and TEST2=$TEST1"(recursive environment variables)
94 // // an exception will be thrown. ~ is replaced by the homedirectory
95 // cout << test1.expandedName() << endl;
96 // // $HOME is expanded
97 // cout << test2.expandedName() << endl;
98 // cout << test1.absoluteName() << endl;
99 // cout << test2.absoluteName() << endl;
100 // cout << test2.baseName() << endl;
101 // cout << test1.dirName() << endl;
102 // cout << test3.originalName() << endl; // myFile is returned
103 // cout << test3.expandedName() << endl; // Nothing is changed
104 // cout << test3.absoluteName() << endl; // The current working directory
105 // is placed before 'myFile'
106 // cout << test3.baseName() << endl; // The current working directory
107 // // is returned
108 // cout << test3.dirName() << endl; // myFile is returned
109 // </srcblock>
110 // </example>
111 
112 // <motivation>
113 // Programmer convenience and (eventually) OS independence.
114 // </motivation>
115 
116 // <todo asof=$DATE$>
117 // <li> To make the class OS independent some functions should be rebuild.
118 // These functions could be expandedName or absoluteName.
119 // <li> The function expandedName or absoluteName could map the filename to
120 // the native convention
121 // <li> A (maybe static) function contractName(const String& pathName)
122 // could be implemented to remove . and .. from the file name.
123 // </todo>
124 
125 
126 class Path
127 {
128 public:
129  // Default constructor, the path is set to . (working directory).
130  Path();
131 
132  // Construct a path with the given name.
133  // When the name is empty, it is set to . (working directory).
134  // It is not checked if the path name is valid.
135  // Function isValid() can be used for that purpose.
136  Path (const String& pathName);
137 
138  // Copy constructor, copy semantics.
139  Path (const Path& that);
140 
141  // Destructor
142  ~Path();
143 
144  // Assignment, copy semantics.
145  Path& operator= (const Path& that);
146 
147  // Append a string to the path name.
148  // When the current path does not end with a / and the string to append
149  // does not start with a /, an intermediate / is also added.
150  void append (const String& string);
151 
152  // Returns the string as given at construction.
153  const String& originalName () const;
154 
155  // Return a string giving the expanded pathname.
156  // This means that the environment variables are expanded and the tilde
157  // is replaced by the home directory. An expanded name can still
158  // be a relative path.
159  // An exception is thrown when converting a recursive environment
160  // variable results in an endless loop (that is, more than 25
161  // substitutions).
162  const String& expandedName () const;
163 
164  // Return the string which giving the absolute pathname.
165  // It is generated from the expanded pathname by adding
166  // the working directory when needed.
167  const String& absoluteName () const;
168 
169  // Return the realpath which is the absolute pathname with possible
170  // symlinks resolved. It also resolves //, /./, /../ and trailing /.
171  // <br>The path must be an existing file or directory.
172  // It uses the system's realpath function. In case it fails,
173  // an exception is thrown.
174  String resolvedName() const;
175 
176  // Check if pathname is valid. This function checks for: double slashes,
177  // non-printable characters, pathname length and filename lengths, this
178  // function is more OS-specific.
179  Bool isValid() const;
180 
181  // Check if pathname is valid according the POSIX standard.
182  // This function checks for
183  // double slashes, non-printable characters,pathname length and filename
184  // lenghts, all according to the POSIX-standard.
185  Bool isStrictlyPosix() const;
186 
187  // Return length of path name
188  uInt length() const;
189 
190  // Return the maximum length a path name can have.
191  uInt maxLength() const;
192 
193  // Return the basename of the path; this is only the name of the file.
194  // It takes it from the expanded path name.
195  String baseName() const;
196 
197  // Return the dirname of the path; this is the directory where the
198  // filename is found. It takes it from the expanded path name.
199  // <br>To get the absolute dirname one could do:
200  // <srcblock>
201  // Path tmpPath (myPath.dirName());
202  // String absDir (tmpPath.absoluteName());
203  // </srcblock>
204  // or
205  // <srcblock>
206  // Path tmpPath (myPath.absoluteName());
207  // String absDir (tmpPath.dirName());
208  // </srcblock>
209  String dirName() const;
210 
211  // Strip otherName from this name. If stripped, the result gets a
212  // leading ././
213  // If not stripped, it is tried if name can be stripped from otherName.
214  // If stripped, the result gets a trailing /.
215  // If still not stripped, it is tried to strip the directory of otherName.
216  // If that succeeds, the result gets a leading ./
217  // This is used by RefTable and TableKeyword to ensure that the
218  // name of a subtable or referenced table is always relative to
219  // the main table.
220  static String stripDirectory (const String& name, const String& otherName);
221 
222  // If the name starts with ././ add otherName to it.
223  // If the name ends with /. strip name from otherName and return the
224  // remainder.
225  // If the name starts with ./ add the directory of otherName to it.
226  // It is the opposite of stripDirectory.
227  static String addDirectory (const String& name, const String& otherName);
228 
229 
230 private:
231  // Strings to describe the pathname in three different ways.
233  // These variables are pointer to strings because the functions which use
234  // these variables are const functions. This means that they would not be
235  // able to modify the string, now they can.
238 
239  // Define the maximum number of bytes in a pathname
240  // This definition does not use Posix values.
241  static uInt getMaxPathNameSize ();
242  // Define the maximum number of bytes in a filename
243  // This definition does not use Posix values.
244  static uInt getMaxNameSize ();
245 
246 
247  // This function is used by expandedName to replace the tilde and to
248  // expand the environment variables
249  String expandName (const String& inString) const;
250 
251  // This function is used by absoluteName to make a name absolute,
252  // this means that the name is described from the root
253  String makeAbsoluteName (const String& inString) const;
254 
255  // Remove . and .. from the path name.
256  // Also multiple slashes are replaced by a single.
257  String removeDots (const String& inString) const;
258 
259  // This function is used by expandName and absoluteName. It sets the
260  // integer "count" on the next slash or on the end of a string
261  void getNextName (const String& inString, uInt& count) const;
262 };
263 
264 
265 inline const String& Path::originalName() const
266 {
267  return itsOriginalPathName;
268 }
269 
270 
271 
272 } //# NAMESPACE CASACORE - END
273 
274 #endif
Bool isValid() const
Check if pathname is valid.
String dirName() const
Return the dirname of the path; this is the directory where the filename is found.
Path()
Default constructor, the path is set to.
Path & operator=(const Path &that)
Assignment, copy semantics.
static uInt getMaxNameSize()
Define the maximum number of bytes in a filename This definition does not use Posix values...
static uInt getMaxPathNameSize()
Define the maximum number of bytes in a pathname This definition does not use Posix values...
String itsExpandedPathName
Definition: Path.h:237
String expandName(const String &inString) const
This function is used by expandedName to replace the tilde and to expand the environment variables...
String itsOriginalPathName
Strings to describe the pathname in three different ways.
Definition: Path.h:232
Path name of a file.
Definition: Path.h:126
uInt length() const
Return length of path name.
String resolvedName() const
Return the realpath which is the absolute pathname with possible symlinks resolved.
uInt maxLength() const
Return the maximum length a path name can have.
const String & expandedName() const
Return a string giving the expanded pathname.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const String & originalName() const
Returns the string as given at construction.
Definition: Path.h:265
~Path()
Destructor.
Bool isStrictlyPosix() const
Check if pathname is valid according the POSIX standard.
const String & absoluteName() const
Return the string which giving the absolute pathname.
String removeDots(const String &inString) const
Remove.
String itsAbsolutePathName
These variables are pointer to strings because the functions which use these variables are const func...
Definition: Path.h:236
String: the storage and methods of handling collections of characters.
Definition: String.h:225
String baseName() const
Return the basename of the path; this is only the name of the file.
static String stripDirectory(const String &name, const String &otherName)
Strip otherName from this name.
static String addDirectory(const String &name, const String &otherName)
If the name starts with.
void getNextName(const String &inString, uInt &count) const
This function is used by expandName and absoluteName.
String makeAbsoluteName(const String &inString) const
This function is used by absoluteName to make a name absolute, this means that the name is described ...
unsigned int uInt
Definition: aipstype.h:51
void append(const String &string)
Append a string to the path name.