casacore
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>
34 #include <casacore/casa/BasicSL/String.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
casacore::Path::expandedName
const String & expandedName() const
Return a string giving the expanded pathname.
casacore::Path::itsOriginalPathName
String itsOriginalPathName
Strings to describe the pathname in three different ways.
Definition: Path.h:232
casacore::Path::maxLength
uInt maxLength() const
Return the maximum length a path name can have.
casacore::Path::originalName
const String & originalName() const
Returns the string as given at construction.
Definition: Path.h:265
casacore::Path::stripDirectory
static String stripDirectory(const String &name, const String &otherName)
Strip otherName from this name.
casacore::Path::getMaxPathNameSize
static uInt getMaxPathNameSize()
Define the maximum number of bytes in a pathname This definition does not use Posix values.
casacore::Path::isStrictlyPosix
Bool isStrictlyPosix() const
Check if pathname is valid according the POSIX standard.
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::Path::resolvedName
String resolvedName() const
Return the realpath which is the absolute pathname with possible symlinks resolved.
casacore::Path::removeDots
String removeDots(const String &inString) const
Remove.
casacore::Path::makeAbsoluteName
String makeAbsoluteName(const String &inString) const
This function is used by absoluteName to make a name absolute, this means that the name is described ...
casacore::Path::getNextName
void getNextName(const String &inString, uInt &count) const
This function is used by expandName and absoluteName.
casacore::Path::length
uInt length() const
Return length of path name.
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::Path::itsAbsolutePathName
String itsAbsolutePathName
These variables are pointer to strings because the functions which use these variables are const func...
Definition: Path.h:236
casacore::Path::isValid
Bool isValid() const
Check if pathname is valid.
casacore::Path::baseName
String baseName() const
Return the basename of the path; this is only the name of the file.
casacore::Path::Path
Path()
Default constructor, the path is set to.
casacore::Path::append
void append(const String &string)
Append a string to the path name.
casacore::Path::addDirectory
static String addDirectory(const String &name, const String &otherName)
If the name starts with.
casacore::Path::~Path
~Path()
Destructor.
casacore::Path::absoluteName
const String & absoluteName() const
Return the string which giving the absolute pathname.
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::Path::getMaxNameSize
static uInt getMaxNameSize()
Define the maximum number of bytes in a filename This definition does not use Posix values.
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::Path
Path name of a file.
Definition: Path.h:126
casacore::Path::itsExpandedPathName
String itsExpandedPathName
Definition: Path.h:237
casacore::Path::operator=
Path & operator=(const Path &that)
Assignment, copy semantics.
casacore::Path::expandName
String expandName(const String &inString) const
This function is used by expandedName to replace the tilde and to expand the environment variables.
casacore::Path::dirName
String dirName() const
Return the dirname of the path; this is the directory where the filename is found.