# Command-Line Examples

For the included command-line utility, we are using `asu` for the name.
`as` is the GNU Assembler while `applesingle` is already on Macintoshes.
Hopefully that will prevent some confusion!

Note that all runs are with the `asu` alias defined as `alias asu='java -jar build/libs/applesingle-1.0.0.jar'`
(adjust as necessary).

## Basic usage

```shell
$ asu
Usage: asu [-hV] [--debug] [COMMAND]

AppleSingle utility

Options:
      --debug     Dump full stack trackes if an error occurs
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.

Commands:
  help     Displays help information about the specified command
  info     Display information about an AppleSingle file
  create   Create an AppleSingle file
  extract  Extract contents of an AppleSingle file
```

## Subcommand help

```shell
$ asu info --help
Usage: asu info [-h] [--stdin] [<file>]

Display information about an AppleSingle file
Please include a file name or indicate stdin should be read, but not both.

Parameters:
      [<file>]   File to process

Options:
      --stdin    Read AppleSingle from stdin.
  -h, --help     Show help for subcommand
```

## Info subcommand 

```shell
$ asu info api/src/test/resources/hello.applesingle.bin 
Real Name: -Unknown-
ProDOS info:
  Access: 0xC3
  File Type: 0x06
  Auxtype: 0x0803
Data Fork: Present, 2,912 bytes
Resource Fork: Not present
```

## Sample runs

Using pipes to create a text file and display information.  Note that the invalid filename of `my-text-file` was changed to `MY.TEXT.FILE`.

```shell
$ echo "Hello World!" | asu create --name my-text-file --stdout --filetype 0x04 --stdin-fork=data --fix-text | asu info --stdin
Real Name: MY.TEXT.FILE
ProDOS info:
  Access: 0xC3
  File Type: 0x04
  Auxtype: 0x0000
Data Fork: Present, 13 bytes
Resource Fork: Not present
```

The `--fix-text` flag flips the high-bit and translates the newline character:

```shell
$ echo "Hello World!" | asu create --name my-text-file --stdout --filetype 0x04 --stdin-fork=data --fix-text | hexdump -C
00000000  00 05 16 00 00 02 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 03 00 00 00 03 00 00  |................|
00000020  00 3e 00 00 00 0c 00 00  00 0b 00 00 00 4a 00 00  |.>...........J..|
00000030  00 08 00 00 00 01 00 00  00 52 00 00 00 0d 4d 59  |.........R....MY|
00000040  2e 54 45 58 54 2e 46 49  4c 45 00 c3 00 04 00 00  |.TEXT.FILE......|
00000050  00 00 c8 e5 ec ec ef a0  d7 ef f2 ec e4 a1 8d     |...............|
0000005f
```
(The message is at 0x52 through 0x5e.)

Without the `--fix-text` flag:

```shell
$ echo "Hello World!" | asu create --name my-text-file --stdout --filetype 0x04 --stdin-fork=data | hexdump -C
00000000  00 05 16 00 00 02 00 00  00 00 00 00 00 00 00 00  |................|
00000010  00 00 00 00 00 00 00 00  00 03 00 00 00 03 00 00  |................|
00000020  00 3e 00 00 00 0c 00 00  00 0b 00 00 00 4a 00 00  |.>...........J..|
00000030  00 08 00 00 00 01 00 00  00 52 00 00 00 0d 4d 59  |.........R....MY|
00000040  2e 54 45 58 54 2e 46 49  4c 45 00 c3 00 04 00 00  |.TEXT.FILE......|
00000050  00 00 48 65 6c 6c 6f 20  57 6f 72 6c 64 21 0a     |..Hello World!.|
0000005f
```