-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy patheasy.1
315 lines (315 loc) · 8.72 KB
/
easy.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
.\"Modified from man(1) of FreeBSD, the NetBSD mdoc.template, and mdoc.samples.
.\"See Also:
.\"man mdoc.samples for a complete listing of options
.\"man mdoc for the short list of editing options
.\"/usr/share/misc/mdoc.template
.Dd January 12, 2013 \" DATE
.Dt EASY 1 \" Program name and manual section number
.\" .An Yves Arrouye
.\" Copyright (C) 2013, Yves Arrouye. All rights reserved.
.Os Darwin
.Sh NAME \" Section Header - required - don't modify
.Nm easy
.\" The following lines are read in generating the apropos(man -k) database. Use only key
.\" words here as the database is built based on the words here and in the .ND line.
.Nd easy interaction with HTTP servers and services
.Sh SYNOPSIS \" Section Header - required - don't modify
.Nm
.Op Fl Fl help \" [--help]
.Op Fl Fl print [ [ Fl s | Fl p Ar prefix ] Ar options | Fl P
.Op Fl Fl cmd Ar file | Fl Fl script Ar file
.Op Fl Fl no-env
.Op Fl Fl no-extras
.Op Fl j , Fl Fl json | Fl f , Fl Fl form | Fl a , Fl Fl as-is
.Op Fl A
.Op Fl B , Fl Fl baked
.Op Fl W , Fl Fl wet
.Op Fl C , Fl Fl cooked | Fl c
.Op Fl R , Fl Fl raw
.Op Fl E , Fl Fl endpoint Ar endpoint
.Op Fl q , Fl Fl query [ Ar query ]
.Op Fl O , Fl Fl override
.Op Fl V
.Ar method
.Ar resource
.Op Ar data
.Op Ar curlopt ...
.Sh DESCRIPTION \" Section Header - required - don't modify
.Nm
(also known as
.Cm rest )
makes interacting with HTTP servers easy.
It allows one to use the name of an HTTP method followed by a resource path
(relative to a given
.Ar endpoint )
or URI in order to interact with it.
.Pp
.Nm
constructs and executes a command line for
.Xr curl 1
in order to actually communicate with the HTTP server. It exits with the
status code from
.Xr curl 1 .
.Pp
When invoked as
.Cm rest ,
.Nm
behaves as if the options
.Fl jBc
were passed to it.
This makes it very easy to use
.Xr rest 1
for interacting with REST services.
The command provides other options to
negate those defaults (e.g.
.Fl f
to use form data instead of JSON).
.Pp
The following options are available:
.Bl -tag -width -indent \" Differs from above in tag removed
.It Fl Fl help \"-a flag as a list item
Print a help usage message documenting each option.
.It Fl Fl print [ [ Fl s | Fl p Ar prefix ] Ar options ]
Print shell commands that can be evaluated to set environment variables,
define shortcut functions or aliases depending on the shell used, or both.
The following arguments are valid:
.Bl -tag -width ".Fl p Ar prefix" -indent
.It Fl s
Define self-sustaining functions or aliases, i.e. include options for the
.Ar endpoint
in the definitions. This makes the function or alias unaffected by a change
in the value of the
.Ev EASYENDPOINT
environment variable. Also bake in the value of
.Ev EASYOPTS
unless
.Fl Fl no-env
is used.
.It Fl p Ar prefix
Prefix function and alias names with
.Ar prefix .
.El
.Pp
The
.Ar options
argument determines what is printed. Multiple printing options
can be separated by commas. The following printing options
are available:
.Bl -tag -width ".Cm func \fR|\fP nofunc" -indent
.It Cm func \fR|\fP nofunc
Print function definitions or aliases. If
.Cm nofunc
is specified then do not print them even if
.Cm all
is specified.
.It Cm env \fR|\fP noenv
Print commands to set environment variables. If
.Cm noenv
is specified then do not print them even if
.Cm all
is specified.
.It Cm all
Print everything. If the
.Fl s
option is used,
.Cm env
is not included except if it is being explicitly listed.
.El
.It Fl P
Same as
.Fl Fl print Fl s all .
.It Fl Fl cmd Ar file
Print the exact command line that was used to invoke
.Xr curl 1
after it has been called.
.It Fl Fl script Ar file
Generate a script equivalent to the command invocation. The invocation is
the same as with
.Fl Fl cmd .
In addition, if data are written to an input file for
.Xr curl 1
to process, the command line is preceded with commands to generate that
input file.
.It Fl Fl no-env
Ignore environment variables.
.It Fl Fl no-extras
Do not add hidden arguments to the
.Xr curl 1
command line. By default,
.Nm
uses such arguments to suppress the progress meter, follow redirections, etc.
.It Fl j , Fl Fl json
Indicate that data sent is JSON and automatically includes an
.Cm Accept
header
for
.Cm application/json .
.It Fl j , Fl Fl form
Send data encoded as
.Cm application/x-www-form-urlencoded
which is the default encoding for data submission.
This does not affect any
.Cm Accept
header set by another option (see
.Fl A ).
.It Fl a , Fl Fl as-is
Send data as-is. This option is convenient to revert the effects of the
.Fl j , Fl Fl json
option on data submission.
This does not affect any
.Cm Accept
header set by another option (see
.Fl A ).
.It Fl A
Set an
.Cm Accept
header for
.Cm */*
allowing any content type in the response.
.It Fl B , Fl Fl baked
Bake arguments into the proper data format for submission. Any
consecutive arguments
.Ar arg
of the form
.Ar key\fR=[\fPvalue\fR]\fP ,
.Ar key\fR:=[\fPvalue\fR]\fP
or
.Ar key
(where
.Ar key
cannot start with a hyphen) are concatenated either into an
.Cm application/x-www-form-urlencoded
string, or, if
.Fl j
or
.Fl Fl json
is present, into a JSON object.
.Pp
The \fB:=\fP form means to use
.Ar value
literaly rather than encoding it (either in
.Cm application/x-www-form-urlencoded
form or as a JSON string).
If only
.Ar key
is specified,
then no
.Ar value
is specified, which in JSON is translated as assigning the value
.Cm null .
.Pp
Arguments of the form
.Ar key\fR==[\fPvalue\fR]\fP
are added to the query part of the URL regardless of
the method. If no
.Ar value
is specified, no assignment is made. See also
.Fl q .
.It Fl W , Fl Fl wet
Do not bake arguments.
.It Fl C , Fl Fl cooked
Cook the response, i.e. format all response headers and the response contents
using
.Xr pretty 1 .
Cooked responses are very easy for humans to process. If
.Nm
is not writing to a terminal then colors are not used unless the option
is given twice.
.It Fl c
Tentatively cook the response, i.e. only cooks it if writing to a terminal.
.It Fl E , Fl Fl endpoint Ar endpoint
Set the endpoint of the server or service to be called.
.It Fl q , Fl Fl query [ Ar query ]
Pass the given
.Ar query
on the resource path by appending a question mark and the
.Ar query
to it.
.It Fl O , Fl Fl override
Override the
.B POST
method and pass the requested
.Ar method
in an X-HTTP-Override
header.
.It Fl V
Create data using an editor. The editor is determined by looking for
an existing editor in the
.Ev VISUAL
and
.Ev EDITOR
environment variables. If there is no such editor, then
.Nm
will look for
.Xref vim 1
and then
.Xref vi 1 .
If
.Fl V
is passed a second time then
.Ar data
will be edited in the editor too.
.It Ar method
Set the HTTP method to call.
.It Ar resource
Set the resource to operate on. If
.Ar resource
is a URI then use it as is. Otherwise its value is
appended to the service
.Ar endpoint
in order to make up the full resource URI.
.It Ar data
Data to be sent to the server or service. The method used to send the
data depends on the HTTP method. For GET, data are passed
on the command line as part of query parameters unless the
.Fl q , Fl Fl query
option was used to specify a query,
in which case data are passed with the body of the
request. Also see
.Fl B , Fl Fl baked .
.It Ar curlopt ...
Any
.Ar curlopt
is appended to the
.Xr curl 1
command line generate by
.Nm .
.El
.Sh ENVIRONMENT
.Bl -tag -width "EASYCURLOPTS" -indent
.It Ev TMPDIR
Directory into which to write temporary files. Defaults to
.Pa /tmp .
.It Ev EASYENDPOINT
Endpoint to use if an
.Ar endpoint
is not specified on the command line.
.It Ev EASYOPTS
Options to always use.
.It Ev EASYCURLOPTS
Options to pass to
.Xr curl 1 .
These options are passed before the ones present on the command line if any.
.It Ev SHELL
Determine the syntax (Bourne shell or C shell) of the commands printed by
.Fl Fl print .
.\" .It Ev ENV_VAR_1
.\" Description of ENV_VAR_1
.\" .It Ev ENV_VAR_2
.\" Description of ENV_VAR_2
.\" .El
.\" .Sh DIAGNOSTICS \" May not be needed
.\" .Bl -diag
.\" .It Diagnostic Tag
.\" Diagnostic informtion here.
.\" .It Diagnostic Tag
.\" Diagnostic informtion here.
.\" .El
.Sh SEE ALSO
.\" List links in ascending order by section, alphabetically within a section.
.\" Please do not reference files that do not exist without filing a bug report
.Xr curl 1 ,
.Xr mime 1 ,
.Xr pretty 1
.\" .Sh BUGS \" Document known, unremedied bugs
.\" .Sh HISTORY \" Document history if command behaves in a unique manner