README excerpt
# superDoIt
BRANCH | STATUS
------------- | -------------
**v4.2** | [](https://github.com/dalehenrich/superDoit/actions)
**v4.1** | [](https://github.com/dalehenrich/superDoit/actions)
**v3** | [](https://github.com/dalehenrich/superDoit/actions)
**v3.1** | [](https://github.com/dalehenrich/superDoit/actions)
**v2** | [](https://github.com/dalehenrich/superDoit/actions)
**v2.0** | [](https://github.com/dalehenrich/superDoit/actions)
**v2.1** | [](https://github.com/dalehenrich/superDoit/actions)
## Versions
### v4.2
Development version intended for use with GsDevKit_stone:v2 and GemStone 3.5.3 and newer versions of GemStone. github actions for superDoit test 3.6.4 thru 3.6.6, 3.7.0, 3.7.1 and 3.7.2. while the GsDevKit_stones github actions tests 3.5.3, 3.5.8, 3.6.0.
Note that GemStone either 3.7.0 or 3.7.1 or 3.7.2 is **required for all solo scripts**, which allows for supporting versions older that 3.6.4...
### v4.1
Stable branch intended for use with SmalltalkCI, GsDevKit_stones:v1.1.x and versions of GemStone that are shipped with an extent0.rowan.dbf in $GEMSTONE/bin (tested from GemStone 3.6.4 thru 3.7.0).
### v3
Intended for .solo scripts used with versions of GemStone that are shipped with an extent0.rowan.dbf in $GEMSTONE/bin, GemStone 3.6.4 and newer versions of GemStone (currently tested thru 3.6.5).
.stone scripts may be used with GemStone versions as old as 3.4.0.
### v3.1
Stable branch for use by [smalltalkCI](https://github.com/hpi-swa/smalltalkCI)
### v2
Intended for use with older versions of GemStone: 3.6.1, 3.6.0, 3.5.7, 3.5.0 (tested versions)
## Table of Contents
1. [What is superDoit?](#what-is-superdoit)
- [Current best practices](#current-best-practices)
- [superDoit solution](#superDoit-solution)
2. [solo, stone, and topaz scripts](#solo-stone-and-topaz-scripts)
- [.solo script](#solo-script)
- [.stone script](#stone-script)
- [.topaz script](#topaz-script)
2. [superDoit sections](#superdoit-sections)
3. [Installation](#superdoit-installation)
4. [Examples](#examples)
- [executable .solo doit with methods and Rowan specs](#executable-solo-doit-with-methods-and-rowan-specs)
2. [How does superDoit work?](#how-does-superdoit-work)
3. [Rowan and superDoit](#rowan-and-superdoit)
3. [Branch naming conventions](#branch-naming-conventions)
## What is superDoit?
`superDoit` is a scripting framework for writing shell scripts in [GemStone Smalltalk](https://gemtalksystems.com/products/gs64/) using [GemStone Topaz][topaz manual]. To install:
```bash
cd <install dir>
git clone git@github.com:dalehenrich/superDoit.git
superDoit/bin/install.sh
```
### Current best practices
Current best practices for writing a [topaz solo bash scripts to report the sum total size of tranlog files in the given directory][Topaz Solo Scripting using bash to pass arguments] involves creating 3 separate files (see [Scripting with topaz solo using sh-bang][Scripting with topaz solo using she-bang] for resons why 3 files are needed to handle command line arguments in topaz solo scripts):
1. a bash script driver script named [gettranlogspace][gettranlogspace]:
```
#!/bin/bash
export GEMSTONE=/lark1/users/gsadmin/3.6
$GEMSTONE/bin/topaz -lq -I $GEMSTONE/scripts/myini -S
$GEMSTONE/scripts/reporttranlogspace.tpz -- $1
```
2. a solo .topazini file named [myini][myini]:
```
set user DataCurator pass swordfish
set gemstone gs64stone
set solologin on
```
3. a [topaz command file][topaz manual] named [reporttranlogspace.tpz][reporttranlogspace.tpz], that contains the Smalltalk code to calculate and report the sum of the tranlog sizes in the directory:
```
login
run
| dir files sz |
dir := System commandLineArguments last.
files := GsFile
contentsOfDirectory: dir
onClient: false.
sz := 0.
files do: [:ea | sz := sz + (GsFile sizeOfOnServer: ea)].
GsFile gciLogClient: dir, ': tranlogs consume total ',
(sz / 1024) asInteger asString, ' KB'.
%
logout
exit
```
The bash driver script would then be executed:
```
unix> ./gettranlogspace /lark1/users/gsadmin/tranlogs
/lark1/users/gsadmin/tranlogs: tranlogs consume total 98477 KB
```
### superDoit solution
`superDoit` not only eliminates the need to create three separate files to run a solo script, but provides support for declaring command line options, help, debugging and [more](#superdoit-sections).
Here is the `superDoit` version of [reporttranlogspace.solo][reporttranlogspace.solo]:
```
#!/usr/bin/env superdoit_solo
options
{
SuperDoitRequiredOptionWithRequiredArg long: 'tranlogDir' short: 't'.
}
%
usage
-----
USAGE $basename [--help | -h] [--debug | -D] --tranlogDir=<tranlog-directory-path>
DESCRIPTION
Calculate and report the sum of the tranlog sizes in the given <tranlog-directory-path>
OPTIONS
-t, --tranlogDir=<tranlog-directory-path>
path to tranlog directory
-h, --help display usage message
-D, --debug bring up topaz debugger in the event of a script error
EXAMPLES
$basename --help
$basename -D -t <tranlog-directory-path>
$basename -t <tranlog-directory-path>
$basename --tranlogDir=<tranlog-directory-path>
-----
%
doit
| sz |
sz := 0.
self tranlogDir asFileReference files
do: [:tranlogFile |
sz := sz + tranlogFile size ].
self stdout
nextPutAll: self tranlogDir;
nextPutAll: ': tranlogs consume total ';
nextPutAll: (sz / 1024) asInteger asString, ' KB'.
^ self noResult
%
```
**Executing** `./reporttranlogspace.solo -t $GS_HOME/server/stones/gs_361/tranlogs` produces:
```
/home/dhenrich/rogue/_homes/rogue/_home/server/stones/gs_361/tranlogs: tranlogs consume total 39617 KB
```
**Executing** `./reporttranlogspace.solo -h ` produces:
```
-----
USAGE reporttranlogspace.solo [--help | -h] [--debug | -D] --tranlogDir=<tranlog-directory-path>
DESCRIPTION
Calculate and report the sum of the tranlog sizes in the given <tranlog-directory-path>
OPTIONS
-t, --tranlogDir=<tranlog-directory-path>
path to tranlog directory
-h, --help display usage message
-D, --debug bring up topaz debugger in the event of a script error
EXAMPLES
reporttranlogspace.solo --help
reporttranlogspace.solo -D -t <tranlog-directory-path>
reporttranlogspace.solo -t <tranlog-directory-path>
reporttranlogspace.solo --tranlogDir=<tranlog-directory-path>
-----
```
**Executing** `./reporttranlogspace.solo` produces:
```
UserDefinedError: The required option 'tranlogDir' was not set.
```
**Executing** `./reporttranlogspace.solo -D` and entering `where` at topaz prompt produces:
```
-----------------------------------------------------
Near line 62 of file /home/dhenrich/rogue/_homes/rogue/_home/shared/repos/superDoit/gemstone/superdoit.tpz
GemStone: Error Nonfatal
a UserDefinedError occurred (error 2318), reason:halt, The required option 'tranlogDir' was not set.
Error Category: 231169 [GemStone] Number: 2318 Arg Count: 1 Context : 20 exception : 102530817
Arg 1: [20 size:0 primitiveSize:0 cls: 76289 UndefinedObject] nil
Stopping at line 62 of /home/dhenrich/rogue/_homes/rogue/_home/shared/repos/superDoit/gemstone/superdoit.tpz
topaz 1> where
==> 1 UserDefinedError (AbstractException) >> _signalToDebugger @10 line 8 [methId 101346817]
2 UserDefinedError (AbstractException) >> defaultAction @2 line 18 [methId 101347073]
3 UserDefinedError (AbstractException) >> _defaultAction @4 line 4 [methId 101346305]
4 UserDefinedError (AbstractException) >> _signal @2 line 20 [methId 3833089]
5 UserDefinedError (AbstractException) >> signal @2 line 47 [methId 3848449]
6 SuperDoitExecutionClass (Object) >> error: @6 line 7 [methId 6400001]
7 [] in SuperDoitExecution >> getAndVerifyOptions @21 line 12 [methId 102538497]
8 Dictionary >> keysAndValuesDo: @9 line 11 [methId 12241665]
9 SuperDoitExecutionClass (SuperDoitExecution) >> getAndVerifyOptions @10 line 8 [methId 102499841]
10 [] in SuperDoitExecution >> doit @6 line 5 [methId 102543617]
11 ExecBlock0 (ExecBlock) >> on:do: @3 line 44 [methId 5850369]
12 SuperDoitExecutionClass (SuperDoitExecution) >> doit @2 line 8 [methId 102546689]
13 SuperDoitDoitCommand >> executeAgainst: @27 line 19 [methId 102584833]
14 [] in SuperDoitCommandDefinition >> executeAgainst: @7 line 2 [methId 102500609]
15 OrderedCollection (Collection) >> do: @5 line 10 [methId 3419649]
16 SuperDoitCommandDefinition >> executeAgainst: @3 line 2 [methId 102502913]
17 [] in SuperDoitCommandParser >> parseAndExecuteScriptFile: @22 line 15 [methId 102511105]
18 [] in AbstractFileReference >> readStreamDo: @8 line 4 [methId 48130817]
19 ExecBlock0 (ExecBlock) >> ensure: @2 line 12 [methId 5852161]
20 FileReference (AbstractFileReference) >> readStreamDo: @4 line 5 [methId 42354689]
21 SuperDoitCommandParser >> parseAndExecuteScriptFile: @2 line 3 [methId 102520577]
22 SuperDoitCommandParser class >> processInputFile @31 line 22 [methId 102519297]
23 Executed Code @2 line