================================ ``grail.compass.runfile`` module ================================ .. include:: ..\version.h .. contents:: Table of Contents :backlinks: top ----------- Description ----------- Utility for generating run files. ----- Class ----- class :dc:`RunFile` Defines a file object with an additional 'add()' method. A RunFile object is basically a file object with an additional add() method defined on it. This add() function has side-effects designed to make it easier to compose a RunFile than with the conventional File methods. For example, assuming you have varX with X equal to 1 through 7 already defined, .. Python:: import RunFile rf = RunFile.Open("run202.bas", "w") rf.add("meds-207v1 10=%s10.dat 11=%s 12=%s 3=rpt207.%s", var1, var2, var3, var4) rf.add("meds-207v1 19=%s 20=%s 21=%s", var5, var6, var7) rf.close() If we opened "run202.bas" it would contain the contents added via the add() method. In order to display a "%" character use two characters in a row as in, .. Python:: rf.add("%%") This will display a single "%" character within the runfile. .. Note :: The RunFile inherits from the built-in file object, and as such behaves just like a file. .. :df:`add(formatstr, *args)` Writes to file, appends \n, and converts all args to strings. Arguments: :a:`formatstr` : string Your standard c-style format string, embedded with %s's since all args will be converted to strings :a:`*args` : variable-argument list A N-long list of arguments matching the number of %s's located in the format string; each argument will be converted to a string (if its not a string already). .. Note :: There are some side-effects associated with this function call. These side-effects are intended and are, 1. appends a \n to the end of the format string for each call to add() 2. converts all args to strings (and strings remain strings), thus you don't have to worry about integers and all that .. :df:`additm(index, formatstr, *args)` Writes to file if and only if the index value is not in the :d:`OMMISION_LIST`. It writes to a file if the index variable is defined, and also increments an ITM[n] variable. If the specified index is 0, then validation is ignored, and the line is written regardless of the contents. This essentially mimics the old med-style ITM#[n] runfile composition command. For example, .. Python:: a = 1 b = "" c = 10 d = 20 runfile = runfile.Open("myrunfile.a", "wt") runfile.additm(2, " %s %s", a, b) runfile.additm(0, " %s", c) # added regardless of c's value. runfile.additm(1, " %s", d) runfile.close() Would result in a runfile that looked like this, .. Python:: ITM1 10 ITM2 20 Because the first :f:`additm()` called had the 2nd value, b, containing a blank string, which exists in the :d:`runfile.OMMISION_LIST`. Arguments: :a:`index` : integer Index you want to make sure exists, or 0 if you don't care. The index is *not* zero based. :a:`formatstr` : string Same as add() attribute. :a:`*args` : variable-argument list Same as add() attribute. .. Note:: The are some side-effects associated with this function call, and they are * Increments internal item count by one if a write is performed. * Other side-effects similar to the :f:`add()` method. :df:`addtmp(index, formatstr, *args)` Functions like additm, except doesn't write out an "ITM[n]" string. Essentially the same validation behavior as the additm() function. Except, a ITM[n] string is not written out the runfile. Arguments: :a:`index` : integer Index into the *args that you want to validate. The index is *not* zero based. :a:`formatstr` : string Same as add() attribute. :a:`*args` : variable-argument list Same as add() attribute. :df:`setoutputhook(hookfn)` Set a function to dump strings to prior to dumping to the file. Useful for debugging runfile creations, this lets you basically stream the format strings to both the file and to some other stream (say sys.stdout). For example, say you want to stream the strings printed to the file also to the console, you would do the following, .. Python:: rf = runfile.openrunfile("myfile.a", "wt") rf.setoutputhook(sys.stdout.write) Presto, now all the strings sent to myfile.a will also be sent to the console. Arguments: :a:`hookfn` : function A function that accepts strings; or :a:`None` if you want to disable the hook. --------- Functions --------- :df:`TimeStampStr()` Returns a human readable time stamp to use in the run file as a string. :df:`openrunfile(path[,mode])` Constructs a RunFile object. Provides a simple means for opening a runfile object for writing. Arguments: :a:`path` : string Path for the runfile. :a:`mode` : string Standard file open access mode. This is the same access mode you would use with the built-in :f:`open()` function [#python-lib-builtin-funcs]_. Returns: A RunFile object that you can use to compose your runfile. :df:`Open(path, accessmode)` .. warning:: DEPRECATED (as of MineSightŪ Grail v1.1) Prefer to use the :f:`openrunfile()` function instead. ---- Data ---- :dd:`OMMISSION_LIST` A list of values that indicate :f:`RunFile.addtmp()` and :f:`RunFile.additm()` should not write a line. .. [#python-lib-builtin-funcs] "Built-in Functions" *Python Library Reference*. 21 December 2001. 14 May 2004.