aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/gun.patch.asciidoc
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2018-06-02 22:44:16 +0200
committerLoïc Hoguin <[email protected]>2018-06-02 22:44:16 +0200
commit5b810c924da242632a04a2c44772cb892aa1b7c0 (patch)
treee9ee81bd3b6aea1f9665914b8858edad377c24c7 /doc/src/manual/gun.patch.asciidoc
parent04b41c3cf70aba88c1dd76e4e86c39458d817219 (diff)
downloadgun-5b810c924da242632a04a2c44772cb892aa1b7c0.tar.gz
gun-5b810c924da242632a04a2c44772cb892aa1b7c0.tar.bz2
gun-5b810c924da242632a04a2c44772cb892aa1b7c0.zip
Revamp the manual, one page per function/message
Diffstat (limited to 'doc/src/manual/gun.patch.asciidoc')
-rw-r--r--doc/src/manual/gun.patch.asciidoc119
1 files changed, 119 insertions, 0 deletions
diff --git a/doc/src/manual/gun.patch.asciidoc b/doc/src/manual/gun.patch.asciidoc
new file mode 100644
index 0000000..3f7baa9
--- /dev/null
+++ b/doc/src/manual/gun.patch.asciidoc
@@ -0,0 +1,119 @@
+= gun:patch(3)
+
+== Name
+
+gun:patch - Apply a set of changes to a resource
+
+== Description
+
+[source,erlang]
+----
+patch(ConnPid, Path, Headers)
+ -> StreamRef
+
+patch(ConnPid, Path, Headers, Body)
+ -> patch(ConnPid, Path, Headers, Body, #{})
+
+patch(ConnPid, Path, Headers, Body, ReqOpts)
+ -> StreamRef
+
+ConnPid :: pid()
+Path :: iodata()
+Headers :: [{binary(), iodata()}]
+Body :: iodata()
+ReqOpts :: gun:req_opts()
+StreamRef :: reference()
+----
+
+Apply a set of changes to a resource.
+
+The behavior of this function varies depending on whether
+a body is provided.
+
+The function `patch/3` expects either a content-length
+or content-type header to indicate that a body will be
+sent afterwards. The body can then be sent using
+link:man:gun:data(3)[gun:data(3)].
+
+The function `patch/4,5` sends the entire request, including
+the request body, immediately. It is therefore not possible
+to use link:man:gun:data(3)[gun:data(3)] after that. You
+should provide a content-type header. Gun will set the
+content-length header automatically.
+
+The body sent in this request should be a patch document
+with instructions on how to update the resource.
+
+== Arguments
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+Path::
+
+Path to the resource.
+
+Headers::
+
+Additional request headers.
+
+Body::
+
+Request body.
+
+ReqOpts::
+
+Request options.
+
+== Return value
+
+A reference that identifies the newly created stream is
+returned. It is this reference that must be passed in
+subsequent calls and will be received in messages related
+to this new stream.
+
+== Changelog
+
+* *1.0*: Function introduced.
+
+== Examples
+
+.Patch a resource
+[source,erlang]
+----
+StreamRef = gun:patch(ConnPid, "/users/1",
+ [{<<"content-type">>, <<"application/json-patch+json">>}],
+ <<"[{\"op\":\"add\",\"path\":\"/baz\",\"value\":\"qux\"}]">>).
+----
+
+.Patch a resource in multiple calls
+[source,erlang]
+----
+StreamRef = gun:patch(ConnPid, "/users/1", [
+ {<<"content-type">>, <<"application/json-patch+json">>}
+]).
+gun:data(ConnPid, StreamRef, fin,
+ <<"[{\"op\":\"add\",\"path\":\"/baz\",\"value\":\"qux\"}]">>).
+----
+
+.Patch a resource with request options
+[source,erlang]
+----
+StreamRef = gun:patch(ConnPid, "/users/1",
+ [{<<"content-type">>, <<"application/json-patch+json">>}],
+ <<"[{\"op\":\"add\",\"path\":\"/baz\",\"value\":\"qux\"}]">>,
+ #{reply_to => ReplyToPid}).
+----
+
+== See also
+
+link:man:gun(3)[gun(3)],
+link:man:gun:post(3)[gun:post(3)],
+link:man:gun:put(3)[gun:put(3)],
+link:man:gun:await(3)[gun:await(3)],
+link:man:gun:await_body(3)[gun:await_body(3)],
+link:man:gun_push(3)[gun_push(3)],
+link:man:gun_inform(3)[gun_inform(3)],
+link:man:gun_response(3)[gun_response(3)],
+link:man:gun_data(3)[gun_data(3)]