Apple-2-SW/bastools
1
0
Fork 0
mirror of https://github.com/AppleCommander/bastools.git synced 2025-01-06 20:29:54 +00:00
Code Issues Projects Releases Wiki Activity
9fbbcc5b81
bastools/tools/st/README.md
Rob Greene b9f2eb28d1 Updating README. #16.
2018-06-24 15:45:27 -05:00

235 lines
11 KiB
Markdown
Raw Blame History

# Overview
`st` is a command-line tool to investigate and (ultimately) author shape tables for inclusion in Applesoft programs.
Samples are extracted from the [original Mouse Maze](https://github.com/a2geek/mouse-maze-2001/tree/master/doc/original), written in 1983.
# Usage
```shell
$ st --help
Usage: st [-hV] [--debug] [COMMAND]
Shape Tools utility
Options:
--debug Dump full stack traces if an error occurs
-h, --help Show this help message and exit.
-V, --version Print version information and exit.
Commands:
extract Extract shapes from shape table
generate Generate a shape table from source code
help Displays help information about the specified command
```
## Sub-command extract
```shell
$ st extract --help
Usage: st extract [-hO] [--skip-empty] [--stdin] [--stdout]
[--border=<borderStyle>] [--coding=<codeStyle>]
[--format=<outputFormat>] [-o=<outputFile>] [-w=<width>]
[--shapes=<shapeNums>]... [<inputFile>]
Extract shapes from shape table
Parameters:
[<inputFile>] File to process
Options:
--border=<borderStyle> Set border style (none, simple, box)
Default: simple
--coding=<codeStyle> Select source style (bitmap, long, short)
Default: long
--format=<outputFormat>
Select output format (text, source, png, gif, jpeg,
bmp, wbmp)
Default: text
--shapes=<shapeNums> Extract specific shape(s); formats are '1' or '1-4' and
can be combined with a comma
--skip-empty Skip empty shapes
--stdin Read from stdin
--stdout Write to stdout
-h, --help Show help for subcommand
-o, --output=<outputFile> Write output to file
-O, --optimize Optimize vector shapes (source only)
-w, --width=<width> Set width (defaults: text=80, image=1024)
```
## Sub-command generate
```shell
$ st generate --help
Usage: st generate [-h] [--demo-code] [--single] [--stdin] [--stdout]
[--address=<address>] [--name=<realName>] [-o=<outputFile>]
[<inputFile>]
Generate a shape table from source code
Parameters:
[<inputFile>] File to process
Options:
--address=<address> Address for AppleSingle file
Default: 24576
--demo-code Generate a ProDOS .po image with Applesoft BASIC code
demoing the shape table
--name=<realName> Filename assign in AppleSingle file
Default: SHAPES.BIN
--single Write to AppleSingle file (requires address, defaults to
0x6000)
--stdin Read from stdin
--stdout Write to stdout
-h, --help Show help for subcommand
-o, --output=<outputFile> Write output to file
```
# Features
## Text extract
```shell
$ st --debug extract --stdout --border=box --skip-empty --format=text --width=132 ~/Downloads/shapes/NEW\ MOUSE
┌─────────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┬─────────────────┐
│XXXXXXXXXXXXXXXX*│...........*X.. │......XXXXX...+ │XXXXXXXXXXXXXXX* │XXXXXXXXXXXXXXX* │.X.X.X.X.X.X.X.* │.X.X.X.X.X.X.X.* │
│X...............X│.....XXXX.XX... │..XXXXX...XX... │XXXXXXXXXXXXXXXX │XXXXXXXXXXXXXXXX │.X.X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │
│X...............X│....XXXXXXXX... │......XXXXX.... │XXXXXXXXXXXXXXXX │XXXXXXXXXXXXXXXX │.X.X.XXXXXXX.X.X │.X.X.X.....X.X.X │
│X...............X│..XXXXXXXXXXX.. │............... │XXXXXXXXXXXXXXXX │XXXXXXXXXXXXXXXX │.X..XX.....XX..X │.X.X.X.XXX.X.X.X │
│X...............X│.XX.XXXXXXX.XX. │....XX..XXX.... │XXXXXXXXXXXXXXXX │XXXXXXXXXXXXXXXX │.X..X.XX.XX.X..X │.X.X..XX.XX..X.X │
│X...............X│.X...XXXXXXXXXX │.....XX.XXX.... │XXXXXXXXXXXXXXXX │XXXXXXXXXXXXXXXX │.X..XX.....XX..X │.X.X.XX.XX.X.X.X │
│X...............X│.XX............ │.....XX.XXXX... │XXXXXXXXXXXXXXXX │XXXXXX....XXXXXX │.X.X.XX.X.XX.X.X │.X.X.XXXX..X.X.X │
│X...............X│..XXX.XX....... │....XX.XXXXX... │XXXXXXXXXXXXXXXX │XXXXX......XXXXX │.X.X..XX.XX..X.X │.X..XX.X..XX.X.X │
│X...............X│....XXX........ │......XXXXXX... │XXXXXXXXXXXXXXXX │XXXX........XXXX │.X..XX.XXX.XX..X │.X.XX..XX.XX.X.X │
│X...............X│............... │...XXXXXXXXXXX. │XXXXXXXXXXXXXXXX │XXXX........XXXX │.X.XXX..X..XXX.X │.X....XXXXXX.X.X │
│X...............X│............... │..XX.........XX │XXXXXXXXXXXXXXXX │XXX..........XXX │.X.X.XXX.XXX.X.X │.X.XXXXXXXXXXX.X │
│X...............X│ │..XX.........XX │XXXXXXXXXXXXXXXX │XXX..........XXX │.X.X...XXX...X.X │..XX.........XX. │
│X...............X│ │...XXXXXXXXXXX. │XXXXXXXXXXXXXXXX │XXX..........XXX │.X.X.XXX.XXX.X.X │..XX.........XX. │
│X...............X│ │............... │XXXXXXXXXXXXXXXX │XXX..........XXX │.X.XXX.X.X.XXX.X │.X.XXXXXXXXXXX.X │
│X...............X│ │ │XXXXXXXXXXXXXXXX │XXXXXXXXXXXXXXXX │.X..XX.X.X.XX..X │.X.X.X.X.X.X.X.X │
│X...............X│ │ │ │ │ │ │
│XXXXXXXXXXXXXXXXX│ │ │ │ │ │ │
├─────────────────┼─────────────────┼─────────────────┼─────────────────┼─────────────────┼─────────────────┼─────────────────┤
│.......XX.....+ │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.* │.....XX*XXXX... │ │ │ │
│.....XX..X..... │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │.......XXX..... │ │ │ │
│...XX...XX..... │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │...XXXXXXXXXXX. │ │ │ │
│.......XXXX.... │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │..XXXXXXXXXXXXX │ │ │ │
│.....XXXXXXXX.. │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │..XXXXXXXXXXXXX │ │ │ │
│....XXX...XXXX. │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │..XXXXXXXXXXXXX │ │ │ │
│...XXXX.XX.XXXX │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │............... │ │ │ │
│...XXXX.XX.XXXX │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │ │ │ │ │
│...XXXX.XX.XXXX │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │ │ │ │ │
│...XXXX.XX.XXXX │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │ │ │ │ │
│....XXX...XXXX. │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │ │ │ │ │
│.....XXXXXXXX.. │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │ │ │ │ │
│.......XXXX.... │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │ │ │ │ │
│............... │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │ │ │ │ │
│ │..X.X.X.X.X.X.X │.X.X.X.X.X.X.X.X │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
└─────────────────┴─────────────────┴─────────────────┴─────────────────┴─────────────────┴─────────────────┴─────────────────┘
```
## Graphics extract
```shell
$ st --debug extract --shape 3 --output robot.png --format png --border box ~/Downloads/shapes/NEW\ MOUSE
```
![Shape #3](images/robot.png "Robot")
```shell
$ st --debug extract --output=new-mouse-shapes.png --border=box --skip-empty --format=png ~/Downloads/shapes/NEW\ MOUSE
```
![All shapes](images/new-mouse-shapes.png "All shapes")
## Shape generation
These samples show a variety of input methods and pipes the resulting (binary) shape table back to `st` to display the results. (Otherwise it's a bit hard to demonstrate!)
### Apple 'box'
```shell
$ cat api/src/test/resources/box-longform.st
; A vector box as given by Applesoft BASIC Programmer's Reference Manual
; Notes:
; move[up|down|left|right] = move vector
; plot[up|down|left|right] = plot vector
; whitespace is ignored
; case insensitive
.long label-long
movedown 2
plotleft 2
moveup
plotup 3
moveright
plotright 3
movedown
plotdown 3
moveleft
plotleft
$ st generate --stdout api/src/test/resources/box-longform.st | st extract --stdin --stdout
+-----+
|.XXX.|
|X...X|
|X.+.X|
|X...X|
|.XXX.|
+-----+
```
### The Mouse Maze mouse
```shell
$ cat mouse.st
; extracted from NEW MOUSE
.bitmap
..........*X..
....XXXX.XX...
...XXXXXXXX...
.XXXXXXXXXXX..
XX.XXXXXXX.XX.
X...XXXXXXXXXX
XX............
.XXX.XX.......
...XXX........
$ st generate --stdout mouse.st | st extract --format=source --coding=short --stdin --stdout
.short
DDDRDDRRUlLdlLLLLLLURRRRRULLLLLLDUlLDLDDRDRRDRRURUuluuruRRRULlLLDLLUrRrrrurrrU
```
## Generate to AppleSingle
```shell
$ cat api/src/test/resources/box-longform.st | st generate --stdin --stdout --single | asu info --stdin
Real Name: SHAPES.BIN
ProDOS info:
Access: 0xC3
File Type: 0x06
Auxtype: 0x6000
File dates info:
Creation: 2018-06-20T01:36:59Z
Modification: 2018-06-20T01:36:59Z
Access: 2018-06-20T01:36:59Z
Backup: 2018-06-20T01:36:59Z
Data Fork: Present, 14 bytes
Resource Fork: Not present
```
## Generate demo disk
Demonstration of a Beagle Bros font:
```shell
st --debug extract --format=source --coding=short ~/Downloads/shapes/\]WESTERN.dump --stdout --skip-empty --optimize |
st generate --demo-code -o western.po --stdin
```
![Western Font Demo](images/western-font-demo.png "]WESTERN")
Reference in New Issue View Git Blame Copy Permalink