From 4536b24763ed06e132617824350a341b0dcb56f3 Mon Sep 17 00:00:00 2001 From: Rob Greene Date: Sat, 26 May 2018 16:58:59 -0500 Subject: [PATCH] Split into a muti-project Gradle build in order to separate the API/lib from the command-line 'asu' tool. --- .gitignore | 4 +- README.md | 126 +----------------- api/README.md | 38 ++++++ api/build.gradle | 11 ++ .../applesingle/AppleSingle.java | 0 .../applesingle/ProdosFileInfo.java | 0 .../applesingle/AppleSingleTest.java | 0 .../src}/test/resources/hello.applesingle.bin | Bin settings.gradle | 5 + tools/asu/README.md | 100 ++++++++++++++ build.gradle => tools/asu/build.gradle | 9 +- .../applesingle/tools/asu/CreateCommand.java | 0 .../applesingle/tools/asu/ExtractCommand.java | 0 .../applesingle/tools/asu/ForkType.java | 0 .../applesingle/tools/asu/InfoCommand.java | 0 .../tools/asu/IntegerTypeConverter.java | 0 .../applesingle/tools/asu/Main.java | 0 .../tools/asu/VersionProvider.java | 0 18 files changed, 163 insertions(+), 130 deletions(-) create mode 100644 api/README.md create mode 100644 api/build.gradle rename {src => api/src}/main/java/io/github/applecommander/applesingle/AppleSingle.java (100%) rename {src => api/src}/main/java/io/github/applecommander/applesingle/ProdosFileInfo.java (100%) rename {src => api/src}/test/java/io/github/applecommander/applesingle/AppleSingleTest.java (100%) rename {src => api/src}/test/resources/hello.applesingle.bin (100%) create mode 100644 tools/asu/README.md rename build.gradle => tools/asu/build.gradle (80%) rename {src => tools/asu/src}/main/java/io/github/applecommander/applesingle/tools/asu/CreateCommand.java (100%) rename {src => tools/asu/src}/main/java/io/github/applecommander/applesingle/tools/asu/ExtractCommand.java (100%) rename {src => tools/asu/src}/main/java/io/github/applecommander/applesingle/tools/asu/ForkType.java (100%) rename {src => tools/asu/src}/main/java/io/github/applecommander/applesingle/tools/asu/InfoCommand.java (100%) rename {src => tools/asu/src}/main/java/io/github/applecommander/applesingle/tools/asu/IntegerTypeConverter.java (100%) rename {src => tools/asu/src}/main/java/io/github/applecommander/applesingle/tools/asu/Main.java (100%) rename {src => tools/asu/src}/main/java/io/github/applecommander/applesingle/tools/asu/VersionProvider.java (100%) diff --git a/.gitignore b/.gitignore index 134fdd8..127adaf 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ .gradle -/build/ -/bin/ +build/ +bin/ # Ignore Gradle GUI config gradle-app.setting diff --git a/README.md b/README.md index ab462a8..f3d0530 100644 --- a/README.md +++ b/README.md @@ -3,130 +3,12 @@ This project is an off-shoot of AppleCommander's support for the AppleSingle format in that there are multiple Java-based tools that can benefit from a pre-built library to support the AppleSingle format. -# Java Usage Examples +# Subprojects -## Read AppleSingle +This project is split into two sub-projects: -Use the factory method to... - -Reading from standard input: - -```java -AppleSingle as = AppleSingle.read(System.in); -``` - -Reading from a file: - -```java -File file = new File("myfile.as"); -AppleSingle as = AppleSingle.read(file); -``` - -The AppleSingle file can be read from an `InputStream`, `File`, `Path`, or just a byte array. - -## Create AppleSingle - -Use the builder to create a new AppleSingle file and then save it... - -```java -AppleSingle as = AppleSingle.builder() - .dataFork(dataFork) - .realName(realName) - .build(); - -Path file = Paths.get("mynewfile.as"); -as.save(file); -``` - -The `save(...)` method can save to a `File`, `Path`, or an `OutputStream`. - -# 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] [] - -Display information about an AppleSingle file -Please include a file name or indicate stdin should be read, but not both. - -Parameters: - [] File to process - -Options: - --stdin Read AppleSingle from stdin. - -h, --help Show help for subcommand -``` - -## Info subcommand - -```shell -$ asu info 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 `my-text-file` was changed to `MY.TEXT.FILE`. - -```shell -$ echo "Hello World!" | asu create --name my-text-file --stdout --filetype 0x06 --stdin-fork=data --fix-text | asu info --stdin -Real Name: MY.TEXT.FILE -ProDOS info: - Access: 0xC3 - File Type: 0x06 - Auxtype: 0x0000 -Data Fork: Present, 13 bytes -Resource Fork: Not present -``` - -The `--fix-text` file flips the high-bit and translates the newline character. - -```shell -$ echo "Hello World!" | asu create --name my-text-file --stdout --filetype 0x06 --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 06 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.) +* [api](api) is the Java API +* [asu](tools/asu) is a command-line tool for manipulating images # Resources diff --git a/api/README.md b/api/README.md new file mode 100644 index 0000000..cbdd5ea --- /dev/null +++ b/api/README.md @@ -0,0 +1,38 @@ +# Java API Examples + +Usage is catered to the factory methods and builder. Some sample are included below. + +## Read AppleSingle + +Use the factory method to... + +Reading from standard input: + +```java +AppleSingle as = AppleSingle.read(System.in); +``` + +Reading from a file: + +```java +File file = new File("myfile.as"); +AppleSingle as = AppleSingle.read(file); +``` + +The AppleSingle file can be read from an `InputStream`, `File`, `Path`, or just a byte array. + +## Create AppleSingle + +Use the builder to create a new AppleSingle file and then save it... + +```java +AppleSingle as = AppleSingle.builder() + .dataFork(dataFork) + .realName(realName) + .build(); + +Path file = Paths.get("mynewfile.as"); +as.save(file); +``` + +The `save(...)` method can save to a `File`, `Path`, or an `OutputStream`. diff --git a/api/build.gradle b/api/build.gradle new file mode 100644 index 0000000..a05f9be --- /dev/null +++ b/api/build.gradle @@ -0,0 +1,11 @@ +repositories { + jcenter() +} + +apply plugin: 'java-library' +apply plugin: 'maven' +apply plugin: 'signing' + +dependencies { + testImplementation 'junit:junit:4.12' +} diff --git a/src/main/java/io/github/applecommander/applesingle/AppleSingle.java b/api/src/main/java/io/github/applecommander/applesingle/AppleSingle.java similarity index 100% rename from src/main/java/io/github/applecommander/applesingle/AppleSingle.java rename to api/src/main/java/io/github/applecommander/applesingle/AppleSingle.java diff --git a/src/main/java/io/github/applecommander/applesingle/ProdosFileInfo.java b/api/src/main/java/io/github/applecommander/applesingle/ProdosFileInfo.java similarity index 100% rename from src/main/java/io/github/applecommander/applesingle/ProdosFileInfo.java rename to api/src/main/java/io/github/applecommander/applesingle/ProdosFileInfo.java diff --git a/src/test/java/io/github/applecommander/applesingle/AppleSingleTest.java b/api/src/test/java/io/github/applecommander/applesingle/AppleSingleTest.java similarity index 100% rename from src/test/java/io/github/applecommander/applesingle/AppleSingleTest.java rename to api/src/test/java/io/github/applecommander/applesingle/AppleSingleTest.java diff --git a/src/test/resources/hello.applesingle.bin b/api/src/test/resources/hello.applesingle.bin similarity index 100% rename from src/test/resources/hello.applesingle.bin rename to api/src/test/resources/hello.applesingle.bin diff --git a/settings.gradle b/settings.gradle index 4d8eea1..e58aeac 100644 --- a/settings.gradle +++ b/settings.gradle @@ -1 +1,6 @@ +include 'api' +include 'tools:asu' + rootProject.name = 'applesingle' +project(":api").name = 'applesingle-api' +project(":tools:asu").name = 'applesingle-tools-asu' diff --git a/tools/asu/README.md b/tools/asu/README.md new file mode 100644 index 0000000..860899c --- /dev/null +++ b/tools/asu/README.md @@ -0,0 +1,100 @@ +# 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] [] + +Display information about an AppleSingle file +Please include a file name or indicate stdin should be read, but not both. + +Parameters: + [] 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 +``` diff --git a/build.gradle b/tools/asu/build.gradle similarity index 80% rename from build.gradle rename to tools/asu/build.gradle index c72297b..9bc15a7 100644 --- a/build.gradle +++ b/tools/asu/build.gradle @@ -2,15 +2,12 @@ plugins { id 'org.springframework.boot' version '2.0.2.RELEASE' } -apply plugin: 'java' -apply plugin: 'application' -apply plugin: 'maven' -apply plugin: 'signing' - repositories { jcenter() } +apply plugin: 'application' + mainClassName = "io.github.applecommander.applesingle.tools.asu.Main" bootJar { @@ -24,5 +21,5 @@ bootJar { dependencies { compile 'info.picocli:picocli:3.0.2' - testImplementation 'junit:junit:4.12' + compile project(':applesingle-api') } diff --git a/src/main/java/io/github/applecommander/applesingle/tools/asu/CreateCommand.java b/tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/CreateCommand.java similarity index 100% rename from src/main/java/io/github/applecommander/applesingle/tools/asu/CreateCommand.java rename to tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/CreateCommand.java diff --git a/src/main/java/io/github/applecommander/applesingle/tools/asu/ExtractCommand.java b/tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/ExtractCommand.java similarity index 100% rename from src/main/java/io/github/applecommander/applesingle/tools/asu/ExtractCommand.java rename to tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/ExtractCommand.java diff --git a/src/main/java/io/github/applecommander/applesingle/tools/asu/ForkType.java b/tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/ForkType.java similarity index 100% rename from src/main/java/io/github/applecommander/applesingle/tools/asu/ForkType.java rename to tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/ForkType.java diff --git a/src/main/java/io/github/applecommander/applesingle/tools/asu/InfoCommand.java b/tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/InfoCommand.java similarity index 100% rename from src/main/java/io/github/applecommander/applesingle/tools/asu/InfoCommand.java rename to tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/InfoCommand.java diff --git a/src/main/java/io/github/applecommander/applesingle/tools/asu/IntegerTypeConverter.java b/tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/IntegerTypeConverter.java similarity index 100% rename from src/main/java/io/github/applecommander/applesingle/tools/asu/IntegerTypeConverter.java rename to tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/IntegerTypeConverter.java diff --git a/src/main/java/io/github/applecommander/applesingle/tools/asu/Main.java b/tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/Main.java similarity index 100% rename from src/main/java/io/github/applecommander/applesingle/tools/asu/Main.java rename to tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/Main.java diff --git a/src/main/java/io/github/applecommander/applesingle/tools/asu/VersionProvider.java b/tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/VersionProvider.java similarity index 100% rename from src/main/java/io/github/applecommander/applesingle/tools/asu/VersionProvider.java rename to tools/asu/src/main/java/io/github/applecommander/applesingle/tools/asu/VersionProvider.java