From 905cbdc769c4e439f7721608534cb4c46bce54be Mon Sep 17 00:00:00 2001 From: Christoph Strebin <50327203+ChristophS-md@users.noreply.github.com> Date: Fri, 31 Jul 2026 15:55:48 +0200 Subject: [PATCH] docs(readme): inputs and outputs --- README.md | 48 +++++++++++++++++++++++++++++++++++++++++++++++- action.yml | 2 +- 2 files changed, 48 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c265174..105d738 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,52 @@ # read-java-properties -GitHub Action to read a Java .properties file and output one, multiple, or all properties as plain strings or JSON. +GitHub Action to read a Java .properties file and convert one, multiple, or all properties to plain strings or JSON. + +The result can be GitHub outputs, environment variables, or a file, depending on input `resultType`. + +Missing property keys are not considered an error, but result in an empty output, unset environment variable, or a JSON +object where the corresponding key is mapped to value `null`, depending on input `resultType`. +The behavior on missing property file is controlled by input `onMissingFile`. + +## Inputs and outputs + +### Inputs +- `file` (required): the properties file name +- `onMissingFile` (default: "error"): What to do if `file` does not exist or is not readable. One of: + - "debug-message": write a debug message and continue with an empty properties map, + - "notice-message": write a notice message and continue with an empty properties map, + - "warning-message": write a warning message and continue with an empty properties map, + - "error": write an error message and exit with non-zero status. + + Note that these situations are always treated as an error: + - `file` is a directory, + - `file` is readable, but not in the correct format. +- `keys` (default: all): Selects the property keys (names). Format: `keySeparator`-separated list. + If not specified or empty, all properties are returned. +- `keySeparator` (default: " "): The separator string used in `keys` +- `resultNameSeparator` (default: " "): The separator string used in some types of `resultType` +- `resultType` (default: "output"): The result format and target. One of: + - "output": For each¹ property key k, set an output named \_k, but with special characters encoded. (The leading underscore serves to avoid conflicts with future output names used by this action.) + Encoding replaces all punctuation or whitespace characters except the underscore ("_") with "-" followed by four hex digits + of its unicode code point. For example, for a property key "a.b-c_d", `resultType` "output" sets an output with name + "_a-002Eb-002Dc_d". + Additionally, set output "value" to the last found value, unless `keys` is empty. I.e. last given key wins. If `keys` is given, but none is found, "value" is set to empty. (Without keys, this output is not set, because it would be arbitrary due to the "random" iteration order of the used Java class java.util.Properties.) + - "output-named:names": names is a `resultNameSeparator`-separated list of output names of the same length as (the `keySeparator`-separated list) `keys`. The value for `keys`[i] is set as output names[i]. In order not to hide any future builtin outputs of this action, it is recommended to prefix each name with an underscore ("_"). In this mode, `keys` is required. Unlike "output", names are taken as-is. (This is because no official output naming rules seem to exist yet; so maybe a future user will know better how to choose valid characters than we would implement now.) The output for a missing property is set to empty. If you need to distinguish between empty and undefined properties, `resultType` "json" or "json-file" is recommended. + - "output-named:name": Special case: A single name is supported even with multiple `keys`. All found values for the keys are set as the same output; the last found key wins. In this mode, `keys` is required. If none is found, the output is set to empty. + - "env": For each¹ property key k, set an environment variable k. + In order not to pollute the environment with hard to understand variables, this should only be used to set some specifically named variables. I.e. you know that the property file can only contain such properties or you are selecting only such properties with `keys`. + - "env:prefix": For each¹ property key K, set an environment variable prefixK. + - "env-named:names": names is a `resultNameSeparator`-separated list of variable names of the same length as (the `keySeparator`-separated list) `keys`. The value for `keys`[i] is set as environment variable names[i]. In this mode, `keys` is required. The environment variable for a missing property is not set. + - "env-named:name": Special case: A single name is supported even with multiple `keys`. All found values for the keys are set as the same environment variable; the last found key wins. In this mode, `keys` is required. + - "json": Set an action output "json" to all¹ properties as a JSON object, formatted as a single-line string. Selected keys for missing properties are included with value null. + - "json-file:name": Write a file with name name with contents: all¹ properties as a JSON object (formatting not specified). Selected keys for missing properties are included with value null. + + ¹Here, "each property" etc. means each property selected by input `keys` if it is non-empty. + +### Outputs +- `value`: The (plain) property value. Only set in certain modes, see input `resultType`. +- `json`: All found properties matching the `keys` input as a single-line JSON object. Only set in certain modes, see input `resultType`. + ## Usage examples: diff --git a/action.yml b/action.yml index b1804b2..0cf85b2 100644 --- a/action.yml +++ b/action.yml @@ -35,7 +35,7 @@ inputs: resultType: description: |- The result format and target. One of: - - "output": For each¹ property key , set an output named "_", but with special characters encoded. (The leading underscore serves to avoid conflicts with future output names used by this action.) + - "output": For each¹ property key , set an output named _, but with special characters encoded. (The leading underscore serves to avoid conflicts with future output names used by this action.) Encoding replaces all punctuation or whitespace characters except the underscore ("_") with "-" followed by four hex digits of its unicode code point. For example, for a property key "a.b-c_d", resultType "output" sets an output with name "_a-002Eb-002Dc_d".