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

  1//
  2//  GTMScriptRunner.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/// Encapsulates the interaction with an interpreter for running scripts.
 22// This class manages the interaction with some command-line interpreter (e.g.,
 23// a shell, perl, python) and allows you to run expressions through the
 24// interpreter, and even full scripts that reside in files on disk.  By default,
 25// the "/bin/sh" interpreter is used, but others may be explicitly specified.
 26// This can be a convenient way to run quick shell commands from Cocoa, or even
 27// interact with other shell tools such as "bc", or even "gdb".
 28// 
 29// It's important to note that by default commands and scripts will have their 
 30// environments erased before execution. You can control the environment they
 31// get with the -setEnvironment: method.
 32//
 33// The best way to show what this class does is to show some examples. 
 34//
 35// Examples:
 36// 
 37// GTMScriptRunner *sr = [GTMScriptRunner runner];
 38// NSString *output = [sr run:@"ls -l /dev/null"];
 39// /* output == "crw-rw-rw-   1 root  wheel    3,   2 Mar 22 10:35 /dev/null" */
 40//
 41// GTMScriptRunner *sr = [GTMScriptRunner runner];
 42// NSString *output = [sr runScript:@"/path/to/my/script.sh"];
 43// /* output == the standard output from the script*/
 44//
 45// GTMScriptRunner *sr = [GTMScriptRunner runnerWithPerl];
 46// NSString *output = [sr run:@"print 'A'x4"];
 47// /* output == "AAAA" */
 48//
 49// See the unit test file for more examples.
 50//
 51@interface GTMScriptRunner : NSObject {
 52 @private
 53  NSString *interpreter_;
 54  NSArray  *interpreterArgs_;
 55  NSDictionary *environment_;
 56  BOOL trimsWhitespace_;
 57}
 58
 59// Convenience methods for returning autoreleased GTMScriptRunner instances, that
 60// are associated with the specified interpreter.  The default interpreter
 61// (returned from +runner is "/bin/sh").
 62+ (GTMScriptRunner *)runner;
 63+ (GTMScriptRunner *)runnerWithBash;
 64+ (GTMScriptRunner *)runnerWithPerl;
 65+ (GTMScriptRunner *)runnerWithPython;
 66
 67// Returns an autoreleased GTMScriptRunner instance associated with the specified
 68// interpreter, and the given args.  The specified args are the arguments that 
 69// should be applied to the interpreter itself, not scripts run through the 
 70// interpreter.  For example, to start an interpreter using "perl -w", you could
 71// do:
 72//   [GTMScriptRunner runnerWithInterpreter:@"/usr/bin/perl"
 73//                                withArgs:[NSArray arrayWithObject:@"-w"]];
 74//
 75+ (GTMScriptRunner *)runnerWithInterpreter:(NSString *)interp;
 76+ (GTMScriptRunner *)runnerWithInterpreter:(NSString *)interp
 77                                  withArgs:(NSArray *)args;
 78
 79// Returns a GTMScriptRunner associated with |interp|
 80- (id)initWithInterpreter:(NSString *)interp;
 81
 82// Returns a GTMScriptRunner associated with |interp| and |args| applied to the
 83// specified interpreter.  This method is the designated initializer.
 84- (id)initWithInterpreter:(NSString *)interp withArgs:(NSArray *)args;
 85
 86// Runs the specified command string by sending it through the interpreter's 
 87// standard input.  The standard output is returned.  The standard error is 
 88// discarded.
 89- (NSString *)run:(NSString *)cmds;
 90// Same as the previous method, except the standard error is returned in |err| 
 91// if specified.
 92- (NSString *)run:(NSString *)cmds standardError:(NSString **)err;
 93
 94// Runs the file at |path| using the interpreter.
 95- (NSString *)runScript:(NSString *)path;
 96// Runs the file at |path|, passing it |args| as arguments.
 97- (NSString *)runScript:(NSString *)path withArgs:(NSArray *)args;
 98// Same as above, except the standard error is returned in |err| if specified.
 99- (NSString *)runScript:(NSString *)path withArgs:(NSArray *)args
100          standardError:(NSString **)err;
101
102// Returns the environment dictionary to use for the inferior process that will
103// run the interpreter. A return value of nil means that the interpreter's 
104// environment should be erased.
105- (NSDictionary *)environment;
106
107// Sets the environment dictionary to use for the interpreter process. See 
108// NSTask's -setEnvironment: documentation for details about the dictionary.
109// Basically, it's just a dict of key/value pairs corresponding to environment
110// keys and values. Setting a value of nil means that the environment should be
111// erased before running the interpreter.
112//
113// *** The default is nil. ***
114//
115// By default, all interpreters will run with a clean environment. If you want 
116// the interpreter process to inherit your current environment you'll need to 
117// do the following:
118//
119// GTMScriptRunner *sr = [GTMScriptRunner runner];
120// [sr setEnvironment:[[NSProcessInfo processInfo] environment]];
121//
122// SECURITY NOTE: That said, in general you should NOT do this because an
123// attacker can modify the environment that would then get sent to your scripts.
124// And if your binary is suid, then  you ABSOLUTELY should not do this.
125// 
126- (void)setEnvironment:(NSDictionary *)newEnv;
127
128// Sets (and returns) whether or not whitespace is automatically trimmed from
129// the ends of the returned strings.  The default is YES, so trailing newlines
130// will be removed.
131- (BOOL)trimsWhitespace;
132- (void)setTrimsWhitespace:(BOOL)trim;
133
134@end