From b2ca4e9b12c5b6169d4283d66246a3a3ce3f83d5 Mon Sep 17 00:00:00 2001 From: Geoff Bourne Date: Wed, 19 Feb 2025 21:57:06 -0600 Subject: [PATCH] Added README docs for toml-query command --- README.md | 172 +++++++++++------- .../java/me/itzg/helpers/McImageHelper.java | 8 +- ...QueryCommand.java => TomlPathCommand.java} | 45 +++-- .../YamlPathCommand.java} | 4 +- ...mandTest.java => TomlPathCommandTest.java} | 4 +- .../YamlPathCommandTest.java} | 6 +- 6 files changed, 142 insertions(+), 97 deletions(-) rename src/main/java/me/itzg/helpers/files/{TomlQueryCommand.java => TomlPathCommand.java} (58%) rename src/main/java/me/itzg/helpers/{singles/YamlPathCmd.java => files/YamlPathCommand.java} (92%) rename src/test/java/me/itzg/helpers/files/{TomlQueryCommandTest.java => TomlPathCommandTest.java} (89%) rename src/test/java/me/itzg/helpers/{singles/YamlPathCmdTest.java => files/YamlPathCommandTest.java} (82%) diff --git a/README.md b/README.md index b8f4b36a..f2a7ea82 100644 --- a/README.md +++ b/README.md @@ -14,28 +14,65 @@ Usage: mc-image-helper [-hs] [--debug] [COMMAND] -h, --help Show this usage and exit -s, --silent Don't output logs even if there's an error Commands: - asciify Converts UTF-8 on stdin to ASCII by escaping Unicode - characters - assert Provides assertion operators for verifying container - setup - compare-versions Used for shell scripting, exits with success(0) when - comparison is satisfied or 1 when not - find Specialized replacement for GNU's find - get Download a file - hash Outputs an MD5 hash of the standard input - install-forge Downloads and installs a requested version of Forge - interpolate Interpolates existing files in one or more directories - java-release Outputs the Java release number, such as 8, 11, 17 - maven-download Downloads a maven artifact from a Maven repository - modrinth Automates downloading of modrinth resources - patch Patches one or more existing files using JSON path - based operations - sync Synchronizes the contents of one directory to another. - sync-and-interpolate Synchronizes the contents of one directory to another - with conditional variable interpolation. - yaml-path Extracts a path from a YAML file using json-path syntax - vanillatweaks Downloads Vanilla Tweaks resource packs, data packs, or - crafting tweaks given a share code or pack file + asciify Converts UTF-8 on stdin to ASCII by escaping + Unicode characters + assert Provides assertion operators for verifying + container setup + compare-versions Used for shell scripting, exits with success(0) + when comparison is satisfied or 1 when not + curseforge-files Download and manage individual mod/plugin files + from CurseForge + find Specialized replacement for GNU's find + get Download a file + github + hash Outputs an MD5 hash of the standard input + install-curseforge Downloads, installs, and upgrades CurseForge + modpacks + install-fabric-loader Provides a few ways to obtain a Fabric loader with + simple cleanup of previous loader instances + install-forge Downloads and installs a requested version of Forge + install-modrinth-modpack Supports installation of Modrinth modpacks along + with the associated mod loader + install-neoforge Downloads and installs a requested version of + NeoForge + install-paper Installs selected PaperMC + install-purpur Downloads latest or selected version of Purpur + install-quilt Installs Quilt mod loader + interpolate Interpolates existing files in one or more + directories + java-release Outputs the Java release number, such as 8, 11, 17 + manage-users + maven-download Downloads a maven artifact from a Maven repository + modrinth Automates downloading of modrinth resources + mcopy Multi-source file copy operation with with managed + cleanup. Supports auto-detected sourcing from + file list, directories, and URLs + network-interfaces Provides simple operations to list network + interface names and check existence + patch Patches one or more existing files using JSON path + based operations + Supports the file formats: + - JSON + - JSON5 + - Yaml + - TOML, but processed output is not pretty + resolve-minecraft-version Resolves and validate latest, snapshot, and + specific versions + set-properties Maps environment variables to a properties file + show-all-subcommand-usage Renders all of the subcommand usage as markdown + sections for README + sync Synchronizes the contents of one directory to + another. + sync-and-interpolate Synchronizes the contents of one directory to + another with conditional variable interpolation. + test-logging-levels + toml-path Extracts a path from a TOML file using json-path + syntax + yaml-path Extracts a path from a YAML file using json-path + syntax + vanillatweaks Downloads Vanilla Tweaks resource packs, data + packs, or crafting tweaks given a share code or + pack file ``` For [patch](#patch) command [see below](#patch-schemas) for a description of [PatchSet](#patchset) and [PatchDefinition](#patchdefinition) JSON schemas. @@ -86,13 +123,12 @@ Usage: mc-image-helper curseforge-files [-h] [--disable-api-caching] [--mod-loader=] [-o=DIR] [[--api-cache-ttl=OPERATION=DURATION]... [--api-cache-default-ttl=DURATION]] - [[--connection-pool-max-idle-timeout=DUR - ATION] + [[--http-response-timeout=DURATION] [--tls-handshake-timeout=DURATION] [--connection-pool-pending-acquire-timeo ut=DURATION] - [--http-response-timeout=DURATION]] [REF - [,REF...]...] + [--connection-pool-max-idle-timeout=DURA + TION]] [REF[,REF...]...] Download and manage individual mod/plugin files from CurseForge [REF[,REF...]...] Can be |':', |'@', ...]]... [[--exclude-include-file=FILE|URI] [[--exclude-mods=PROJECT_ID|SLUG[,|PROJECT_ID|SLUG...]]... [--force-include-mods=PROJECT_ID|SLUG[,|PROJECT_ID|SLUG...]]...]] - [[--connection-pool-max-idle-timeout=DURATION] - [--tls-handshake-timeout=DURATION] + [[--http-response-timeout=DURATION] [--tls-handshake-timeout=DURATION] [--connection-pool-pending-acquire-timeout=DURATION] - [--http-response-timeout=DURATION]] + [--connection-pool-max-idle-timeout=DURATION]] [[--api-cache-ttl=OPERATION=DURATION]... [--api-cache-default-ttl=DURATION]] [COMMAND] Downloads, installs, and upgrades CurseForge modpacks @@ -407,11 +442,12 @@ Usage: mc-image-helper install-forge [-h] [--force-reinstall] [--results-file=FILE] [--forge-installer= | [--forge-version=]] - [[--connection-pool-max-idle-timeout=DURATI - ON] [--tls-handshake-timeout=DURATION] + [[--http-response-timeout=DURATION] + [--tls-handshake-timeout=DURATION] [--connection-pool-pending-acquire-timeout= DURATION] - [--http-response-timeout=DURATION]] + [--connection-pool-max-idle-timeout=DURATIO + N]] Downloads and installs a requested version of Forge --connection-pool-max-idle-timeout=DURATION @@ -455,11 +491,10 @@ Usage: mc-image-helper install-modrinth-modpack [--force-modloader-reinstall] [--ignore-missing-files=[, |...]]... [--overrides-exclusions=[NL or , - ...]]... - [[--connection-pool-max-idle-timeout=DURATION] + ...]]... [[--http-response-timeout=DURATION] [--tls-handshake-timeout=DURATION] [--connection-pool-pending-acquire-timeout=DURATION] - [--http-response-timeout=DURATION]] + [--connection-pool-max-idle-timeout=DURATION]] Supports installation of Modrinth modpacks along with the associated mod loader --api-base-url= Default: https://api.modrinth.com @@ -531,12 +566,12 @@ Usage: mc-image-helper install-neoforge [-h] [--force-reinstall] [--neoforge-version=] [--output-directory=DIR] [--results-file=FILE] - [[--connection-pool-max-idle-timeout=DUR - ATION] + [[--http-response-timeout=DURATION] [--tls-handshake-timeout=DURATION] [--connection-pool-pending-acquire-timeo ut=DURATION] - [--http-response-timeout=DURATION]] + [--connection-pool-max-idle-timeout=DURA + TION]] Downloads and installs a requested version of NeoForge --connection-pool-max-idle-timeout=DURATION @@ -571,11 +606,12 @@ Usage: mc-image-helper install-paper [--check-updates] [--base-url=] | [[--project=] [--build=] [--channel=] [--version=]]] - [--connection-pool-max-idle-timeout=DURATIO - N | [--tls-handshake-timeout=DURATION] | + [[--http-response-timeout=DURATION] | + [--tls-handshake-timeout=DURATION] | --connection-pool-pending-acquire-timeout=D URATION | - [--http-response-timeout=DURATION]] + --connection-pool-max-idle-timeout=DURATION + ] Installs selected PaperMC --base-url= --build= @@ -610,11 +646,12 @@ Usage: mc-image-helper install-purpur [--base-url=] [--url= | [[--version=] [--build=]]] - [--connection-pool-max-idle-timeout=DURATI - ON | [--tls-handshake-timeout=DURATION] | + [[--http-response-timeout=DURATION] | + [--tls-handshake-timeout=DURATION] | --connection-pool-pending-acquire-timeout= DURATION | - [--http-response-timeout=DURATION]] + --connection-pool-max-idle-timeout=DURATIO + N] Downloads latest or selected version of Purpur --base-url= --build= @@ -646,11 +683,12 @@ Usage: mc-image-helper install-quilt [-h] [--force-reinstall] [--repo-url=] [--results-file=FILE] [--installer-url=URL | --installer-version=VERSION] - [[--connection-pool-max-idle-timeout=DURATI - ON] [--tls-handshake-timeout=DURATION] + [[--http-response-timeout=DURATION] + [--tls-handshake-timeout=DURATION] [--connection-pool-pending-acquire-timeout= DURATION] - [--http-response-timeout=DURATION]] + [--connection-pool-max-idle-timeout=DURATIO + N]] Installs Quilt mod loader --connection-pool-max-idle-timeout=DURATION @@ -722,12 +760,12 @@ Usage: mc-image-helper manage-users [-fh] [--existing=] >] -t= [--user-api-provider=] [--version=] - [[--connection-pool-max-idle-timeout=DURATIO - N] [--tls-handshake-timeout=DURATION] + [[--http-response-timeout=DURATION] + [--tls-handshake-timeout=DURATION] [--connection-pool-pending-acquire-timeout=D URATION] - [--http-response-timeout=DURATION]] [INPUT[, - INPUT...]...] + [--connection-pool-max-idle-timeout=DURATION + ]] [INPUT[,INPUT...]...] [INPUT[,INPUT...]...] One or more Mojang usernames, UUID, or ID (UUID without dashes); however, when offline, only UUID/IDs can be provided. @@ -770,11 +808,12 @@ Usage: mc-image-helper maven-download [-h] [--print-filename] [--skip-existing] [--output-directory=] [--packaging=] [-r=] [-v=] - [[--connection-pool-max-idle-timeout=DURAT - ION] [--tls-handshake-timeout=DURATION] + [[--http-response-timeout=DURATION] + [--tls-handshake-timeout=DURATION] [--connection-pool-pending-acquire-timeout =DURATION] - [--http-response-timeout=DURATION]] + [--connection-pool-max-idle-timeout=DURATI + ON]] Downloads a maven artifact from a Maven repository -a, -m, --module, --artifact= @@ -842,10 +881,11 @@ Usage: mc-image-helper modrinth [--skip-existing] [--skip-up-to-date] [--output-directory=DIR] [--world-directory=] [--projects=id|slug[,|id|slug...]]... - [[--connection-pool-max-idle-timeout=DURATION] + [[--http-response-timeout=DURATION] [--tls-handshake-timeout=DURATION] [--connection-pool-pending-acquire-timeout=DURAT - ION] [--http-response-timeout=DURATION]] + ION] + [--connection-pool-max-idle-timeout=DURATION]] Automates downloading of modrinth resources --allowed-version-type= Valid values: release, beta, alpha @@ -914,10 +954,9 @@ Supports the file formats: ``` Usage: mc-image-helper resolve-minecraft-version - [[--connection-pool-max-idle-timeout=DURATION] - [--tls-handshake-timeout=DURATION] + [[--http-response-timeout=DURATION] [--tls-handshake-timeout=DURATION] [--connection-pool-pending-acquire-timeout=DURATION] - [--http-response-timeout=DURATION]] + [--connection-pool-max-idle-timeout=DURATION]] Resolves and validate latest, snapshot, and specific versions --connection-pool-max-idle-timeout=DURATION @@ -1001,6 +1040,14 @@ interpolation. Usage: mc-image-helper test-logging-levels ``` +### toml-path + +``` +Usage: mc-image-helper toml-path query [file] + query JSON path expression where root element $ can be omitted + [file] TOML file or reads stdin +``` + ### vanillatweaks ``` @@ -1010,11 +1057,12 @@ Usage: mc-image-helper vanillatweaks [--force-synchronize] [--world-subdir=] [--pack-files=FILE[,|FILE...]]... [--share-codes=CODE[,|CODE...]]... - [[--connection-pool-max-idle-timeout=DURATI - ON] [--tls-handshake-timeout=DURATION] + [[--http-response-timeout=DURATION] + [--tls-handshake-timeout=DURATION] [--connection-pool-pending-acquire-timeout= DURATION] - [--http-response-timeout=DURATION]] + [--connection-pool-max-idle-timeout=DURATIO + N]] Downloads Vanilla Tweaks resource packs, data packs, or crafting tweaks given a share code or pack file --base-url= diff --git a/src/main/java/me/itzg/helpers/McImageHelper.java b/src/main/java/me/itzg/helpers/McImageHelper.java index 37ca1dc6..3ef8c92c 100644 --- a/src/main/java/me/itzg/helpers/McImageHelper.java +++ b/src/main/java/me/itzg/helpers/McImageHelper.java @@ -20,7 +20,8 @@ import me.itzg.helpers.errors.ExceptionHandler; import me.itzg.helpers.errors.ExitCodeMapper; import me.itzg.helpers.fabric.InstallFabricLoaderCommand; -import me.itzg.helpers.files.TomlQueryCommand; +import me.itzg.helpers.files.TomlPathCommand; +import me.itzg.helpers.files.YamlPathCommand; import me.itzg.helpers.find.FindCommand; import me.itzg.helpers.forge.InstallForgeCommand; import me.itzg.helpers.forge.InstallNeoForgeCommand; @@ -38,7 +39,6 @@ import me.itzg.helpers.singles.HashCommand; import me.itzg.helpers.singles.NetworkInterfacesCommand; import me.itzg.helpers.singles.TestLoggingCommand; -import me.itzg.helpers.singles.YamlPathCmd; import me.itzg.helpers.sync.InterpolateCommand; import me.itzg.helpers.sync.MulitCopyCommand; import me.itzg.helpers.sync.Sync; @@ -92,8 +92,8 @@ Sync.class, SyncAndInterpolate.class, TestLoggingCommand.class, - TomlQueryCommand.class, - YamlPathCmd.class, + TomlPathCommand.class, + YamlPathCommand.class, VanillaTweaksCommand.class, } ) diff --git a/src/main/java/me/itzg/helpers/files/TomlQueryCommand.java b/src/main/java/me/itzg/helpers/files/TomlPathCommand.java similarity index 58% rename from src/main/java/me/itzg/helpers/files/TomlQueryCommand.java rename to src/main/java/me/itzg/helpers/files/TomlPathCommand.java index 9c4d95eb..e1bd435b 100644 --- a/src/main/java/me/itzg/helpers/files/TomlQueryCommand.java +++ b/src/main/java/me/itzg/helpers/files/TomlPathCommand.java @@ -1,11 +1,12 @@ package me.itzg.helpers.files; -import com.fasterxml.jackson.core.JsonParser; import com.fasterxml.jackson.core.type.TypeReference; -import com.fasterxml.jackson.dataformat.toml.TomlFactory; import com.fasterxml.jackson.dataformat.toml.TomlMapper; +import com.jayway.jsonpath.Configuration; +import com.jayway.jsonpath.DocumentContext; import com.jayway.jsonpath.JsonPath; -import java.io.IOException; +import com.jayway.jsonpath.ParseContext; +import com.jayway.jsonpath.spi.json.JacksonJsonProvider; import java.nio.file.Path; import java.util.Map; import java.util.concurrent.Callable; @@ -13,8 +14,8 @@ import picocli.CommandLine.ExitCode; import picocli.CommandLine.Parameters; -@Command(name = "toml-query") -public class TomlQueryCommand implements Callable { +@Command(name = "toml-path", description = "Extracts a path from a TOML file using json-path syntax") +public class TomlPathCommand implements Callable { public static final TypeReference> MAP_TYPE = new TypeReference>() { }; @@ -31,16 +32,22 @@ public class TomlQueryCommand implements Callable { @Override public Integer call() throws Exception { - final Map content; - try (JsonParser parser = loadParser()) { - if (path != null) { - content = new TomlMapper().readValue(parser, MAP_TYPE); - } - else { - content = new TomlMapper().readValue(parser, MAP_TYPE); - } + + final ParseContext parseContext = JsonPath.using( + Configuration.builder() + .jsonProvider(new JacksonJsonProvider(new TomlMapper())) + .build() + ); + + final DocumentContext context; + if (path != null) { + context = parseContext.parse(path.toFile()); + } + else { + context = parseContext.parse(System.in); } - final Object result = JsonPath.read(content, + + final Object result = context.read( // if user left off root element reference, then add it // maybe using a shell where $ triggers interpolation query.startsWith("$") ? query : "$" + query @@ -51,14 +58,4 @@ public Integer call() throws Exception { return ExitCode.OK; } - private JsonParser loadParser() throws IOException { - final JsonParser parser; - if (path != null) { - parser = new TomlFactory().createParser(path.toFile()); - } - else { - parser = new TomlFactory().createParser(System.in); - } - return parser; - } } diff --git a/src/main/java/me/itzg/helpers/singles/YamlPathCmd.java b/src/main/java/me/itzg/helpers/files/YamlPathCommand.java similarity index 92% rename from src/main/java/me/itzg/helpers/singles/YamlPathCmd.java rename to src/main/java/me/itzg/helpers/files/YamlPathCommand.java index e2aa6df9..dadcafd5 100644 --- a/src/main/java/me/itzg/helpers/singles/YamlPathCmd.java +++ b/src/main/java/me/itzg/helpers/files/YamlPathCommand.java @@ -1,4 +1,4 @@ -package me.itzg.helpers.singles; +package me.itzg.helpers.files; import com.fasterxml.jackson.dataformat.yaml.YAMLMapper; import com.jayway.jsonpath.Configuration; @@ -13,7 +13,7 @@ import picocli.CommandLine.Parameters; @Command(name = "yaml-path", description = "Extracts a path from a YAML file using json-path syntax") -public class YamlPathCmd implements Callable { +public class YamlPathCommand implements Callable { @Option(names = "--file", description = "A YAML file to query") File yamlFile; diff --git a/src/test/java/me/itzg/helpers/files/TomlQueryCommandTest.java b/src/test/java/me/itzg/helpers/files/TomlPathCommandTest.java similarity index 89% rename from src/test/java/me/itzg/helpers/files/TomlQueryCommandTest.java rename to src/test/java/me/itzg/helpers/files/TomlPathCommandTest.java index 660fa8f7..f6661148 100644 --- a/src/test/java/me/itzg/helpers/files/TomlQueryCommandTest.java +++ b/src/test/java/me/itzg/helpers/files/TomlPathCommandTest.java @@ -9,13 +9,13 @@ import picocli.CommandLine; import picocli.CommandLine.ExitCode; -class TomlQueryCommandTest { +class TomlPathCommandTest { @ParameterizedTest @ValueSource(strings = {"$.bind", ".bind"}) void extractsVelocityBind(String queryPath) throws Exception { final String out = tapSystemOut(() -> { - final int exitCode = new CommandLine(new TomlQueryCommand()) + final int exitCode = new CommandLine(new TomlPathCommand()) .execute( queryPath, Paths.get("src/test/resources/velocity.toml").toString() diff --git a/src/test/java/me/itzg/helpers/singles/YamlPathCmdTest.java b/src/test/java/me/itzg/helpers/files/YamlPathCommandTest.java similarity index 82% rename from src/test/java/me/itzg/helpers/singles/YamlPathCmdTest.java rename to src/test/java/me/itzg/helpers/files/YamlPathCommandTest.java index 45c7e7ec..e048f689 100644 --- a/src/test/java/me/itzg/helpers/singles/YamlPathCmdTest.java +++ b/src/test/java/me/itzg/helpers/files/YamlPathCommandTest.java @@ -1,4 +1,4 @@ -package me.itzg.helpers.singles; +package me.itzg.helpers.files; import static com.github.stefanbirkner.systemlambda.SystemLambda.tapSystemOut; import static org.assertj.core.api.Assertions.assertThat; @@ -6,12 +6,12 @@ import org.junit.jupiter.api.Test; import picocli.CommandLine; -class YamlPathCmdTest { +class YamlPathCommandTest { @Test void pickOutFieldFromServerSetupConfig() throws Exception { final String output = tapSystemOut(() -> { - final int exitCode = new CommandLine(new YamlPathCmd()) + final int exitCode = new CommandLine(new YamlPathCommand()) .execute( "--file", "src/test/resources/server-setup-config.yaml", ".install.baseInstallPath"