javaproperties-cli — Command-line manipulation of Java .properties files

GitHub | PyPI | Documentation | Issues | Changelog

javaproperties-cli is a wrapper around the javaproperties package (from which it was split off) that provides programs for basic command-line manipulation of Java .properties files, including getting, setting, & deleting values and converting to & from JSON.

Currently, the programs only support .properties files in the simple line-oriented format, not the XML variant.

javaproperties

NAME

javaproperties — Basic manipulation of Java .properties files

SYNOPSIS

javaproperties get    [<OPTIONS>] <file> <key> ...
javaproperties select [<OPTIONS>] <file> <key> ...
javaproperties set    [<OPTIONS>] <file> <key> <value>
javaproperties delete [<OPTIONS>] <file> <key> ...
javaproperties format [<OPTIONS>] [<file>]

get

javaproperties get [<OPTIONS>] <file> <key> ...

Print out the values of the given keys in the given .properties file. Each value is printed out on a separate line with escape sequences interpolated.

If you want the output to also be in .properties format, see select.

Options

-d <value>, --default-value <value>

Default value for undefined keys. If this option is not specified, keys requested on the command line that are not defined in either the main .properties file or the --defaults file will (unless the --quiet option is given) cause a warning to be printed to stderr and the command to exit with a failure status.

-D <file>, --defaults <file>

.properties file of default values. If this option is specified, keys requested on the command line that are not defined in the main .properties file will be looked up in this file.

-e, --escaped

Parse the keys and default value specified on the command line for .properties-style escape sequences (specifically, those supported by javaproperties.unescape)

-E <encoding>, --encoding <encoding>

Specifies the encoding of the input file(s); default value: iso-8859-1 (a.k.a. Latin-1). Output always uses the locale’s encoding.

-q, --quiet

Added in version 0.7.0.

Do not warn about or fail due to missing keys

select

javaproperties select [<OPTIONS>] <file> <key> ...

Print out the key-value entries in the given .properties file for the given keys. The output is in .properties format, reformatted as though by format.

Options

-A, --ascii

Added in version 0.6.0.

Escape all non-ASCII characters in the output with \uXXXX escape sequences. This overrides --unicode. This is the default behavior.

-d <value>, --default-value <value>

Default value for undefined keys. If this option is not specified, keys requested on the command line that are not defined in either the main .properties file or the --defaults file will (unless the --quiet option is given) cause a warning to be printed to stderr and the command to exit with a failure status.

-D <file>, --defaults <file>

.properties file of default values. If this option is specified, keys requested on the command line that are not defined in the main .properties file will be looked up in this file.

-e, --escaped

Parse the keys and default value specified on the command line for .properties-style escape sequences (specifically, those supported by javaproperties.unescape)

-E <encoding>, --encoding <encoding>

Specifies the encoding of the input and output files; default value: iso-8859-1 (a.k.a. Latin-1)

-o <file>, --outfile <file>

Write output to this file instead of standard output

-s <sep>, --separator <sep>

Use <sep> as the key-value separator in the output; default value: =

-q, --quiet

Added in version 0.7.0.

Do not warn about or fail due to missing keys

-U, --unicode

Added in version 0.6.0.

Output non-ASCII characters literally, except for characters that are not supported by the output encoding, which are escaped with \uXXXX escape sequences. This overrides --ascii.

set

javaproperties set [<OPTIONS>] <file> <key> <value>

Set the value of <key> in the .properties file <file> to <value> and output the results. The other entries in the file (including comments, possibly not including the timestamp; see below) will be left as-is.

Options

-A, --ascii

Added in version 0.6.0.

Escape all non-ASCII characters in the new key & value with \uXXXX escape sequences on output. This overrides --unicode. This is the default behavior.

-e, --escaped

Parse <key> and <value> for .properties-style escape sequences (specifically, those supported by javaproperties.unescape)

-E <encoding>, --encoding <encoding>

Specifies the encoding of the input and output files; default value: iso-8859-1 (a.k.a. Latin-1)

-o <file>, --outfile <file>

Write output to this file instead of standard output

-s <sep>, --separator <sep>

Separate <key> and <value> in the output with <sep>; default value: =

-T, --preserve-timestamp

Do not modify the timestamp in the .properties file. By default, if a timestamp is found, it is updated to the current time, even if the rest of the file is unchanged.

-U, --unicode

Added in version 0.6.0.

Output non-ASCII characters in the new key & value literally, except for characters that are not supported by the output encoding, which are escaped with \uXXXX escape sequences. This overrides --ascii.

delete

javaproperties delete [<OPTIONS>] <file> <key> ...

Remove all entries for the given keys from the given .properties file and output the results. The other entries in the file (including comments, possibly not including the timestamp; see below) will be left as-is.

Options

-e, --escaped

Parse the keys specified on the command line for .properties-style escape sequences (specifically, those supported by javaproperties.unescape)

-E <encoding>, --encoding <encoding>

Specifies the encoding of the input and output files; default value: iso-8859-1 (a.k.a. Latin-1)

-o <file>, --outfile <file>

Write output to this file instead of standard output

-T, --preserve-timestamp

Do not modify the timestamp in the .properties file. By default, if a timestamp is found, it is updated to the current time, even if the rest of the file is unchanged.

format

javaproperties format [<OPTIONS>] [<file>]

Normalize the formatting of the given .properties file (or standard input if no file is given) and output the results. All comments, excess whitespace, invalid escapes, and duplicate keys are removed, and the entries are sorted lexicographically.

Options

-A, --ascii

Added in version 0.6.0.

Escape all non-ASCII characters in the output with \uXXXX escape sequences. This overrides --unicode. This is the default behavior.

-E <encoding>, --encoding <encoding>

Specifies the encoding of the input and output files; default value: iso-8859-1 (a.k.a. Latin-1)

-o <file>, --outfile <file>

Write output to this file instead of standard output

-s <sep>, --separator <sep>

Use <sep> as the key-value separator in the output; default value: =

-U, --unicode

Added in version 0.6.0.

Output non-ASCII characters literally, except for characters that are not supported by the output encoding, which are escaped with \uXXXX escape sequences. This overrides --ascii.

json2properties

NAME

json2properties — Convert a JSON object to a Java .properties file

SYNOPSIS

json2properties [<OPTIONS>] [<infile> [<outfile>]]

DESCRIPTION

Convert a JSON file infile to a .properties file and write the results to outfile. If not specified, infile and outfile default to standard input and standard output, respectively.

The JSON document must be an object with scalar (i.e., string, numeric, boolean, and/or null) values; anything else will result in an error.

Key ordering is preserved in the output by default (unless the --sort-keys option is given), and numeric, boolean, & null values are output using their JSON representations; e.g., the input:

{
    "yes": true,
    "no": "false",
    "nothing": null
}

becomes:

#Mon Sep 26 18:57:44 UTC 2016
yes=true
no=false
nothing=null

Changed in version 0.7.0: Key ordering is now preserved by default instead of always being sorted

OPTIONS

-A, --ascii

Added in version 0.6.0.

Escape all non-ASCII characters in the output with \uXXXX escape sequences. This overrides --unicode. This is the default behavior.

-c <comment>, --comment <comment>

Added in version 0.5.0.

Show the given string as a comment at the top of the output

-E <encoding>, --encoding <encoding>

Use <encoding> as the output encoding; default value: iso-8859-1 (a.k.a. Latin-1)

-s <sep>, --separator <sep>

Use <sep> as the key-value separator in the output; default value: =

-S, --sort-keys

Added in version 0.7.0.

Sort entries in output by key

-U, --unicode

Added in version 0.6.0.

Output non-ASCII characters literally, except for characters that are not supported by the output encoding, which are escaped with \uXXXX escape sequences. This overrides --ascii.

properties2json

NAME

properties2json — Convert a Java .properties file to JSON

SYNOPSIS

properties2json [<OPTIONS>] [<infile> [<outfile>]]

DESCRIPTION

Convert a .properties file infile to a JSON object and write the results to outfile. If not specified, infile and outfile default to standard input and standard output, respectively. The output is encoded in UTF-8.

Changed in version 0.6.0: Output encoding is now always UTF-8 instead of being determined by the locale.

Changed in version 0.7.0: Key ordering is now preserved by default instead of always being sorted

OPTIONS

-A, --ascii

Added in version 0.6.0.

Escape all non-ASCII characters in the output with \uXXXX escape sequences. This overrides --unicode. This is the default behavior.

-E <encoding>, --encoding <encoding>

Specifies the encoding of the input file; default value: iso-8859-1 (a.k.a. Latin-1)

-S, --sort-keys

Added in version 0.7.0.

Sort entries in output by key

-U, --unicode

Added in version 0.6.0.

Output non-ASCII characters literally. This overrides --ascii.

Changelog

v0.9.0 (in development)

  • Support Python 3.10, 3.11, and 3.12

  • Drop support for Python 3.6 and 3.7

  • Migrated from setuptools to hatch

v0.8.0 (2021-05-12)

  • Support Click 8

v0.7.1 (2020-11-28)

  • Support Python 3.9

  • Drop support for Python 2.7 and 3.5

  • Support javaproperties 0.8.*

v0.7.0 (2020-07-16)

  • properties2json and json2properties now preserve the input ordering of keys by default; use the new --sort-keys option to get the old behavior

  • Drop support for Python 3.4

  • Gave javaproperties’ get and select subcommands --quiet options for suppressing warnings about missing keys

v0.6.1 (2020-03-09)

  • Require javaproperties 0.7.*

v0.6.0 (2020-03-02)

  • Require javaproperties 0.6.*

  • Use 'javapropertiesreplace' error handler when opening output files

  • Gave javaproperties’ format, select, and set subcommands --ascii and --unicode options for controlling the escaping of non-ASCII characters in output

  • Gave properties2json and json2properties --ascii and --unicode options for controlling the escaping of non-ASCII characters in output

  • properties2json now always outputs UTF-8

  • By default, comments output by json2properties now have all non-ASCII characters escaped rather than all non-Latin-1 characters

v0.5.0 (2020-01-24)

  • Include installation instructions, GitHub links, and changelog in the Read the Docs site

  • Gave json2properties a --comment <comment> option

  • Support Python 3.8

v0.4.1 (2018-09-18)

  • Drop support for Python 2.6 and 3.3

  • Support javaproperties 0.5.0

v0.4.0 (2017-04-22)

v0.3.0 (2017-04-13)

  • Added the PropertiesFile class for preserving comments in files [#1]

  • The ordereddict package is now required under Python 2.6

v0.2.1 (2017-03-20)

  • Bugfix to javaproperties command: Don’t die horribly on missing non-ASCII keys

  • PyPy now supported

v0.2.0 (2016-11-14)

  • Added a javaproperties command for basic command-line manipulating of .properties files

  • Gave json2properties a --separator option

  • Gave json2properties and properties2json --encoding options

  • Exported the java_timestamp() function

  • to_comment() now converts CR LF and CR line endings inside comments to LF

  • Some minor documentation improvements

v0.1.0 (2016-10-02)

Initial release

Installation

javaproperties-cli requires Python 3.8 or higher. Just use pip for Python 3 (You have pip, right?) to install javaproperties-cli and its dependencies:

python3 -m pip install javaproperties-cli

Quickstart

javaproperties get    <file> <key> ...

Output the values of the given keys in the given .properties file

javaproperties select <file> <key> ...

Output the key-value pairs for the given keys in the given .properties file

javaproperties set    <file> <key> <value>

Set <key> in <file> to <value> and output the result

javaproperties delete <file> <key> ...

Output the given .properties file with the given keys deleted

javaproperties format [<file>]

Reformat the given .properties file, removing comments & extraneous whitespace and putting keys in sorted order

json2properties [<infile> [<outfile>]]

Convert a JSON object to a .properties file

properties2json [<infile> [<outfile>]]

Convert a .properties file to a JSON object

Indices and tables