oodumpvars.rex: See "Purpose", below Copyright (C) 2015 Leslie L. Koehler This is free software. See "Notice:" at the bottom of C:\MyRexxStuff\oodumpvars.rex Author: Les Koehler email@example.com Purpose: Return a string for the caller to INTERPRET that will dump his vars to a file and allow adding the file to the THE ring. For .REX programs THE can be invoked, if installed, or the code can be tailored to replace the default Notepad. The file is named the same as the file being edited, with a prefix of the upper case drive letter followed by an underscore (e.g. C_), an optional identifier, a suffix of: .N and an extension of .SDV. Initially, N=0 but If KEEP is specified then N is incremented by 1 until a non-existing file is found. If not invoked from a THE edit session, and a version of ooRexx earlier than 4.2 is installed, then the 5th argument is required to identify the full path and file of the caller. Version 4.2 introduced .stackframes, and it is used if available. Syntax: INTERPRET OODUMPVARS(--> Arg#: 1 2 3 4 5 >-- ['Keep'] [,edit command varname][,'identifier'] [,'stem.'] [,filename] --> or: >-- ['Delete' , '*' | first [,'*' | last]] [,'stem.',['searchid']]--> >-- ) --><-- Help: oodumpvars [? | /? | -? | Help | /Help | -Help | --Help] Notes: 1-For a Delete, note that in order to pass a searchid, you must provide a stem name and Interpret the result. This is a safety measure so that you can verify the results using SAY the first time and then allow the delete the second time. The searchid must start with an upper case drive letter followed by "_". See below. 2-If a stemname is passed when dumping variables, the individual commands are returned in the stem for you to Interpret or SAY. */ /* Note: This code was written for THE and ooRexx. If the file being edited is DIR.DIR, then date.time is used as the filename. */ /* With KEEP you have the possible result of: X_something.the.0.SDV X_something.the.1.SDV etc. If you use the optional identifier, then you might get something like: X_something.the.ident.0.SDV X_something.the.ident.1.SDV The optional identifier allows you to more easily tie the OODUMPVARS invocation in your code to the file it produces. You might, for instance, choose to use a line number or a label as an identifier and call OODUMPVARS multiple times during a debugging session. In order to provide maximum flexibility, when doing a Delete for such files, the SearchId is allowed to end with either a period or an asterisk. Thus the following set of files can be selectively deleted, as needed: X_something.the.ident1.0.SDV X_something.the.ident1.1.SDV X_something.the.ident1.2.SDV X_something.the.ident2.0.SDV X_something.the.ident2.1.SDV X_something.the.ident2.2.SDV See the example near the end of this prolog. Of course the usual simple forms of Delete (without SearchId) continue to work as expected for THE macros. The Drive Letter prefix is to accomodate the use of different thumb drive letters on different machines, as they were for me when I wrote the code! */ /* Examples for THE: Interpret oodumpvars() -- Dumps the variables to a file -- replacing the previous file. Interpret oodumpvars(,'edit') Interpret edit -- Dumps the vars and edits the file -- replacing the previous file. */ /* Interpret oodumpvars(,,'identifier') -- Dumps the vars and adds -- '.identifier' after the original -- extension, replacing the -- previous file. */ /* Interpret oodumpvars('K') -- Dumps the vars to a new file, -- keeping the previous file. Interpret oodumpvars('K','edit') -- Dumps the vars to a new file, Interpret edit -- keeping the previous file and -- edits the new file. */ /* Interpret oodumpvars(,,,'mystem.') -- Sets the elements of MYSTEM. -- to the commands to Interpret: do m=1 to mystem.0 interpret mystem.m end Interpret oodumpvars('K','edit',,'mystem.') -- Similar to above, except do m=1 to mystem.0 -- a new file is created interpret mystem.m -- and we can edit it end -- later. Interpret edit */ /* Interpret oodumpvars('D','*') -- Deletes all the program's SDV files Interpret oodumpvars('D',3,6) -- Deletes generation 3 to 6 Interpret oodumpvars('D',3,'*') -- Deletes generation 3 to last Interpret oodumpvars('D','*',,'mystem.') -- Sets the elements of MYSTEM. -- to the commands to Interpret, -- perhaps like this: do m=1 to mystem.0 interpret mystem.m end */ /* Interpret oodumpvars('D','*',,'mystem.',, 'N:\MyTHEstuff\F_testt.the.') -- Similar to above, but searches -- in a specific folder for SDV files -- that belong to a specific program executed from -- the F drive. -- SysFileTree is used to do the search. -- The searchid must end with a period -- or an asterisk. Asterisk should only -- be used when it is necessary to match -- the trailing part of a subset of -- identifiers. Normally an asterisk -- is appended to the searchid anyway. -- Special allowance is made to handle an asterisk -- for the original filename and/or filetype. This -- makes cleanup of a cluttered DIR easier. -- The elements of MYSTEM. are set to -- the commands to Interpret, just like -- the previous example. */ /* -- Using Identifiers -- If you code: /* Some code */ Interpret oodumpvars('K',,'Les') /* More code */ Interpret oodumpvars('K',,'Lee') -- and run it several times, you might wind up with these files: C:\MyRexxStuff\testprogram.rex.Les.0.SDV C:\MyRexxStuff\testprogram.rex.Les.1.SDV C:\MyRexxStuff\testprogram.rex.Les.2.SDV C:\MyRexxStuff\testprogram.rex.Les.3.SDV C:\MyRexxStuff\testprogram.rex.Lee.0.SDV C:\MyRexxStuff\testprogram.rex.Lee.1.SDV C:\MyRexxStuff\testprogram.rex.Lee.2.SDV C:\MyRexxStuff\testprogram.rex.Lee.3.SDV -- If you then wanted to delete the generation 1 and 2 files you might -- code: interpret oodumpvars('D',1,2,'mystem.', , 'C:\MyRexxStuff\C_testprogram.rex.') -- but you would NOT get the result you want! Instead, just the first 2 -- files found would be deleted, because the code would detect that you -- wanted to delete just TWO files, i.e. 2-1+1. Instead, you should code -- something like this: interpret oodumpvars('D',1,2,'mystem.', , 'C:\MyRexxStuff\C_testprogram.rex.Le*') do m=1 to mystem.0 interpret mystem.m end -- and the shorcut code will be avoided. -- See testoodumpx.rex and testoodump.the to -- play around, or create new test cases for yourself. -- The settings for keywords, minimum abbreviations and flags are -- just below the 'flags=' statement. Just define your -- non-conflicting keyword and add the matching label and code near -- the DUMP: label! Finally, update the Help within the prolog and -- you're done. This is also an easy way to create a simple test case -- that demonstrates a bug to send to me. -- NOTE: If invoked from a .REX program, you will have to tailor -- EDIT_CMD, START_EDITOR, EDITOR and SAYIT below -- to suit your editor. If you want THE to display output from .REX -- programs, take a look at THESTACK.REX and the logic after the -- lesk?=left(who_am_i,4)='LESK' -- -- statement. You might find that the easiest way to go. -- Notice that there are 3 different ways an editor may have -- to be invoked. That's why there are 3 variables. If you -- change them, be sure to test your changes! Getting the quotes -- right under various circumstances can be tricky! -- I am deeply thankfull to Walter Pachl for his relentless -- testing that allowed me to adapt this code to his work habits. -- He also contributed the original EXPANDED_DUMPVARS.REX code that -- tries to fit the Name column in to a fixed width, And it -- handles hex! See WIDTH= below to change the column width. -- Additional thanks to Gil Barmater for the pieces of Object code -- that replace SysDumpVariables for handling CR & LF. All I did -- was piece it all together to suit what I needed!