README.md
1# Ply
2Property list pretty-printer powered by `howett.net/plist`.
3
4_verb. work with (a tool, especially one requiring steady, rhythmic movements)._
5
6## Installation
7
8`go get howett.net/plist/cmd/ply`
9
10## Usage
11
12```
13 ply [OPTIONS]
14
15Application Options:
16 -c, --convert=<format> convert the property list to a new format (c=list for list) (pretty)
17 -k, --key=<keypath> A keypath! (/)
18 -o, --out=<filename> output filename
19 -I, --indent indent indentable output formats (xml, openstep, gnustep, json)
20
21Help Options:
22 -h, --help Show this help message
23```
24
25## Features
26
27### Keypath evaluation
28
29```
30$ ply file.plist
31{
32 x: {
33 y: {
34 z: 1024
35 }
36 }
37}
38$ ply -k x/y/z file.plist
391024
40```
41
42Keypaths are composed of a number of path expressions:
43
44* `/name` - dictionary key access
45* `[i]` - index array, string, or data
46* `[i:j]` - silce array, string, or data in the range `[i, j)`
47* `!` - parse the data value as a property list and use it as the base of evaluation for further path components
48* `$(subexpression)` - evaluate `subexpression` and paste its value
49
50#### Examples
51
52Given the following property list:
53
54```
55{
56 a = {
57 b = {
58 c = (1, 2, 3);
59 d = hello;
60 };
61 data = <414243>;
62 };
63 sub = <7b0a0974 6869733d 22612064 69637469 6f6e6172 7920696e 73696465 20616e6f 74686572 20706c69 73742122 3b7d>;
64 hello = subexpression;
65}
66```
67
68##### pretty print
69```
70$ ply file.plist
71{
72 a: {
73 b: {
74 c: (
75 [0]: 1
76 [1]: 2
77 [2]: 3
78 )
79 d: hello
80 }
81 data: 00000000 41 42 43 |ABC.............|
82 }
83 hello: subexpression
84 sub: 00000000 7b 0a 09 74 68 69 73 3d 22 61 20 64 69 63 74 69 |{..this="a dicti|
85 00000010 6f 6e 61 72 79 20 69 6e 73 69 64 65 20 61 6e 6f |onary inside ano|
86 00000020 74 68 65 72 20 70 6c 69 73 74 21 22 3b 7d |ther plist!";}..|
87}
88```
89
90##### consecutive dictionary keys
91```
92$ ply file.plist -k 'a/b/d'
93hello
94```
95
96##### array indexing
97```
98$ ply file.plist -k 'a/b/c[1]'
992
100```
101
102##### data hexdump
103```
104$ ply file.plist -k 'a/data'
10500000000 41 42 43 |ABC.............|
106```
107
108##### data and array slicing
109```
110$ ply file.plist -k 'a/data[2:3]'
11100000000 43 |C...............|
112```
113
114```
115$ ply -k 'sub[0:10]' file.plist
11600000000 7b 0a 09 74 68 69 73 3d 22 61 |{..this="a......|
117```
118
119##### subplist parsing
120```
121$ ply -k 'sub!' file.plist
122{
123 this: a dictionary inside another plist!
124}
125```
126
127##### subplist keypath evaluation
128```
129$ ply -k 'sub!/this' file.plist
130a dictionary inside another plist!
131```
132
133##### subexpression evaluation
134```
135$ ply -k '/$(/a/b/d)' file.plist
136subexpression
137```
138
139### Property list conversion
140
141`-c <format>`, or `-c list` to list them all.
142
143* Binary property list [`bplist`]
144* XML [`xml`]
145* GNUstep [`gnustep`, `gs`]
146* OpenStep [`openstep`, `os`]
147* JSON (for a subset of data types) [`json`]
148* YAML [`yaml`]
149
150#### Notes
151By default, ply will emit the most compact representation it can for a given format. The `-I` flag influences the inclusion of whitespace.
152
153Ply will overwrite the input file unless an output filename is specified with `-o <file>`.
154
155### Property list subsetting
156
157(and subset conversion)
158
159```
160$ ply -k '/a/b' -o file-a-b.plist -c openstep -I file.plist
161$ cat file-a-b.plist
162{
163 c = (
164 1,
165 2,
166 3,
167 );
168 d = hello;
169}
170```
171
172#### Subplist extraction
173
174```
175$ ply -k '/sub!' -o file-sub.plist -c openstep -I file.plist
176$ cat file-sub.plist
177{
178 this = "a dictionary inside another plist!";
179}
180```
181