/core/externals/update-engine/externals/google-toolbox-for-mac/Foundation/GTMPath.h

  1//
  2//  GTMPath.h
  3//
  4//  Copyright 2007-2008 Google Inc.
  5//
  6//  Licensed under the Apache License, Version 2.0 (the "License"); you may not
  7//  use this file except in compliance with the License.  You may obtain a copy
  8//  of the License at
  9//
 10//  http://www.apache.org/licenses/LICENSE-2.0
 11//
 12//  Unless required by applicable law or agreed to in writing, software
 13//  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 14//  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
 15//  License for the specific language governing permissions and limitations under
 16//  the License.
 17//
 18
 19#import <Foundation/Foundation.h>
 20
 21#if MAC_OS_X_VERSION_MIN_REQUIRED < MAC_OS_X_VERSION_10_5
 22// NSFileManager has improved substantially in Leopard and beyond, so GTMPath
 23// is now deprecated.
 24
 25// GTMPath
 26//
 27// This class represents a single, absolute file system path. The represented
 28// path must exist at the time of creation. This class also allows you to easily
 29// create new paths (or full hierarchies) based on existing GTMPath instances.
 30//
 31// Given a GTMPath instance, new files and directories can be created inside
 32// that path providing the instance refers to a directory. It is an error to try
 33// to create a file/directory from a GTMPath that represents a file (this should
 34// be common sense: clearly mkdir /etc/passwd/foo won't work).
 35//
 36// === Examples ===
 37//
 38// 1. This sample creates a GTMPath that references /tmp, then gets the
 39//    attributes for that directory.
 40//
 41//   GTMPath *tmp = [GTMPath pathWithFullPath:@"/tmp"];
 42//   NSDictionary *attr = [tmp attributes];
 43//
 44//
 45// 2. This sample creates a new directory inside /tmp named "foo".
 46//
 47//   GTMPath *tmp = [GTMPath pathWithFullPath:@"/tmp"];
 48//   GTMPath *foo = [tmp createDirectoryName:@"foo" mode:0755];
 49//
 50//
 51// 3. This sample creates a GTMPath instance that represents a user's ~/Library
 52//    folder.
 53//
 54//   GTMPath *library = [GTMPath pathWithFullPath:@"/Users/bob/Library"];
 55//   ...
 56//   
 57//
 58// 4. This sample creates a directory hierarchy, where each level has its own
 59//    mode. Notice that the return value from these -create* methods is the
 60//    GTMPath that was just created. This allows these creation calls to be
 61//    chained together enabling easy creation of directory hierarchies. 
 62//    This is one of the big benefits of this class.
 63//
 64//   GTMPath *tmp = [GTMPath pathWithFullPath:@"/tmp"];
 65//   GTMPath *baz = [[[tmp createDirectoryName:@"foo" mode:0755]
 66//                        createDirectoryName:@"bar" mode:0756]
 67//                       createDirectoryName:@"baz" mode:0757];
 68//
 69@interface GTMPath : NSObject {
 70 @private
 71  NSString *fullPath_;
 72}
 73
 74// Returns a GTMPath instance that represents the full path specified by
 75// |fullPath|. Note that |fullPath| MUST be an absolute path.
 76+ (id)pathWithFullPath:(NSString *)fullPath;
 77
 78// Returns a GTMPath instance that represents the full path specified by
 79// |fullPath|. Note that |fullPath| MUST be an absolute path. This method is the
 80// designated initializer.
 81- (id)initWithFullPath:(NSString *)fullPath;
 82
 83// Returns the name of this GTMPath instance. This is not the full path. It is
 84// just the component name of this GTMPath instance. This is equivalent to 
 85// the Unix basename(3) function.
 86- (NSString *)name;
 87
 88// Returns this path's parent GTMPath. This method will ONLY (and always) return
 89// nil when |name| is "/". In otherwords, parent will be nil IFF this GTMPath
 90// instance represents the root path, because "/" doesn't really have a parent.
 91- (GTMPath *)parent;
 92
 93// Returns YES if this GTMPath represents a directory.
 94- (BOOL)isDirectory;
 95
 96// Returns YES if this GTMPath instance represents the root path "/".
 97- (BOOL)isRoot;
 98
 99// Returns the file system attributes of the path represented by this GTMPath
100// instance. See -[NSFileManager fileAttributesAtPath:...] for details.
101- (NSDictionary *)attributes;
102
103// Returns a string representation of the absolute path represented by this 
104// GTMPath instance.
105- (NSString *)fullPath;
106
107@end
108
109
110// Methods for creating files and directories inside a GTMPath instance. These
111// methods are only allowed to be called on GTMPath instances that represent
112// directories. See the NSFileManager documentation for details about the 
113// |attributes| parameters.
114@interface GTMPath (GTMPathGeneration)
115
116// Creates a new directory with the specified mode or attributes inside the 
117// current GTMPath instance. If the creation is successful, a GTMPath for the 
118// newly created directory is returned. Otherwise, nil is returned.
119- (GTMPath *)createDirectoryName:(NSString *)name mode:(mode_t)mode;
120- (GTMPath *)createDirectoryName:(NSString *)name
121                      attributes:(NSDictionary *)attributes;
122
123// Creates a new file with the specified mode or attributes inside the 
124// current GTMPath instance. If the creation is successful, a GTMPath for the 
125// newly created file is returned. Otherwise, nil is returned. |data| is the
126// data to put in the file when created.
127- (GTMPath *)createFileName:(NSString *)name mode:(mode_t)mode;
128- (GTMPath *)createFileName:(NSString *)name
129                 attributes:(NSDictionary *)attributes;
130- (GTMPath *)createFileName:(NSString *)name
131                 attributes:(NSDictionary *)attributes
132                       data:(NSData *)data;
133
134@end
135
136#endif //  MAC_OS_X_VERSION_MIN_REQUIRED < MAC_OS_X_VERSION_10_5