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 vmrexx@tampabay.rr.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!