Skip to content

Commit acba546

Browse files
committed
docs(readme): add PowerShell, replace example
Emphasize initool never changes the input file.
1 parent 7742fef commit acba546

File tree

1 file changed

+55
-2
lines changed

1 file changed

+55
-2
lines changed

README.md

Lines changed: 55 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ Rather than modify an INI file in place, it prints the modified contents of the
1212
- [POSIX](#posix)
1313
- [Windows](#windows)
1414
- [Both](#both)
15+
- [PowerShell](#powershell)
16+
- [Most shells](#most-shells)
1517
- [Whitespace](#whitespace)
1618
- [Nonexistent sections and properties](#nonexistent-sections-and-properties)
1719
- [Unparsable lines](#unparsable-lines)
@@ -53,6 +55,7 @@ The global options `-i`/`--ignore-case` and `-p`/`--pass-through` must precede t
5355
When given a valid command, initool first reads the INI file `filename` in its entirety.
5456
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.
5557
For `exists`, it reports whether the section or the property exists through its exit status.
58+
**Initool never modifies the original file.**
5659

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

134137
#### Both
135138

139+
##### PowerShell
140+
141+
You can use pipelines in PowerShell without the issues with `cmd.exe`.
142+
The variable `$?` will be `True` only if all commands in the pipeline succeed.
143+
144+
```powershell
145+
# We assume `initool.exe` (Windows) or the binary `initool` (Linux and macOS)
146+
# is in the current directory.
147+
./initool delete settings.ini test | ./initool set - '' cache 1024 > settings.ini.new
148+
if ($?) { move -Force settings.ini.new settings.ini }
149+
```
150+
151+
### Most shells
152+
153+
These examples work in POSIX-compatible shells, fish, `cmd.exe`, PowerShell, and others.
154+
The `>` at the beginning of the line represents the shell's prompt.
155+
136156
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`:
137157

138158
```sh
139-
$ initool get tests/test.ini foo name1
159+
> initool get tests/test.ini foo name1
140160
[foo]
141161
name1=foo1
142-
$ initool get tests/test.ini foo name1 --value-only
162+
> initool get tests/test.ini foo name1 --value-only
143163
foo1
144164
```
145165

166+
To replace text in a value, use `replace`.
167+
168+
```sh
169+
> initool get tests/replace-part.ini
170+
key=A longer value.
171+
another-key=ABAABBAAABBB
172+
empty=
173+
> initool replace tests/replace-part.ini "" key value string > updated.ini
174+
```
175+
176+
The text of `updated.ini` will be:
177+
178+
```ini
179+
key=A longer string.
180+
another-key=ABAABBAAABBB
181+
empty=
182+
```
183+
184+
Now let's change the value of the key `empty`,
185+
but only if it is empty.
186+
187+
```sh
188+
> ./initool replace tests/replace-part.ini "" empty "" no > updated.ini
189+
```
190+
191+
The text of `updated.ini` will be:
192+
193+
```ini
194+
key=A longer value.
195+
another-key=ABAABBAAABBB
196+
empty=no
197+
```
198+
146199
### Whitespace
147200

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

0 commit comments

Comments
 (0)