Skip to content

Commit

Permalink
docs(readme): add PowerShell, replace example
Browse files Browse the repository at this point in the history
Emphasize initool never changes the input file.
  • Loading branch information
dbohdan committed Jun 10, 2024
1 parent 7742fef commit acba546
Showing 1 changed file with 55 additions and 2 deletions.
57 changes: 55 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ Rather than modify an INI file in place, it prints the modified contents of the
- [POSIX](#posix)
- [Windows](#windows)
- [Both](#both)
- [PowerShell](#powershell)
- [Most shells](#most-shells)
- [Whitespace](#whitespace)
- [Nonexistent sections and properties](#nonexistent-sections-and-properties)
- [Unparsable lines](#unparsable-lines)
Expand Down Expand Up @@ -53,6 +55,7 @@ The global options `-i`/`--ignore-case` and `-p`/`--pass-through` must precede t
When given a valid command, initool first reads the INI file `filename` in its entirety.
If the filename is `-`, initool reads standard input. For the commands `get`, `set`, `replace`, and `delete`, it then prints to standard output the file's contents with the desired change.
For `exists`, it reports whether the section or the property exists through its exit status.
**Initool never modifies the original file.**

An INI file consists of properties (`key=value` lines) and sections (designated with a `[section name]` header line).
A property can be at the "top level" of the file (before any section headers) or in a section (after a section header).
Expand Down Expand Up @@ -133,16 +136,66 @@ move /y settings.ini.new settings.ini

#### Both

##### PowerShell

You can use pipelines in PowerShell without the issues with `cmd.exe`.
The variable `$?` will be `True` only if all commands in the pipeline succeed.

```powershell
# We assume `initool.exe` (Windows) or the binary `initool` (Linux and macOS)
# is in the current directory.
./initool delete settings.ini test | ./initool set - '' cache 1024 > settings.ini.new
if ($?) { move -Force settings.ini.new settings.ini }
```

### Most shells

These examples work in POSIX-compatible shells, fish, `cmd.exe`, PowerShell, and others.
The `>` at the beginning of the line represents the shell's prompt.

To retrieve only the value of a property rather than the whole property (the section, key, and value), use the flag `-v` or `--value-only`:

```sh
$ initool get tests/test.ini foo name1
> initool get tests/test.ini foo name1
[foo]
name1=foo1
$ initool get tests/test.ini foo name1 --value-only
> initool get tests/test.ini foo name1 --value-only
foo1
```

To replace text in a value, use `replace`.

```sh
> initool get tests/replace-part.ini
key=A longer value.
another-key=ABAABBAAABBB
empty=
> initool replace tests/replace-part.ini "" key value string > updated.ini
```

The text of `updated.ini` will be:

```ini
key=A longer string.
another-key=ABAABBAAABBB
empty=
```

Now let's change the value of the key `empty`,
but only if it is empty.

```sh
> ./initool replace tests/replace-part.ini "" empty "" no > updated.ini
```

The text of `updated.ini` will be:

```ini
key=A longer value.
another-key=ABAABBAAABBB
empty=no
```

### Whitespace

Initool defines whitespace as any mix of space and tab characters.
Expand Down

0 comments on commit acba546

Please sign in to comment.