diff options
Diffstat (limited to 'doc/src/manual/gun.patch.asciidoc')
-rw-r--r-- | doc/src/manual/gun.patch.asciidoc | 119 |
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)] |