txt: ## dist_zef-raku-community-modules-WWW.md
  ![Logo](logotype/logo_32x32.png) | ![Test](https://github.com/raku-community-modules/WWW/workflows/Test/badge.svg)[![Test-create and publish Docker images](https://github.com/raku-community-modules/WWW/actions/workflows/test-upload-ghcr.yaml/badge.svg)](https://github.com/raku-community-modules/WWW/actions/workflows/test-upload-ghcr.yaml)
  
  # NAME
  
  WWW - No-nonsense, simple HTTPS client with JSON decoder
  
  # SYNOPSIS
  
  ```
  use WWW;
  
  # Just GET content (will return Failure on failure):
  say get 'https://httpbin.org/get?foo=42&bar=x', :SomeHeader<Value>;
  
  # GET and decode received data as JSON:
  say jget('https://httpbin.org/get?foo=42&bar=x')<args><foo>;
  
  # POST content (query args are OK; pass form as named args)
  say post 'https://httpbin.org/post?foo=42&bar=x', :some<form>, :42args;
  
  # And if you need headers, pass them inside a positional Hash:
  say post 'https://httpbin.org/post?foo=42&bar=x', %(:Some<Custom-Header>),
      :some<form>, :42args;
  
  # Same POST as above + decode response as JSON
  say jpost('https://httpbin.org/post', :some<form-arg>)<form><some>;
  
  # Also can post() or jpost() POST body directly as Str:D; headers passed as named args:
  say jpost(
      "http://httpbin.org/post",
      to-json({:42a, :foo<meows>}),
      :Authorization<Zofmeister>
  ).<json><foo>;
  
  ```
  
  Import more HTTP methods using `:extras`
  
  ```
  use WWW :extras;
  
  say jdelete 'https://httpbin.org/delete';
  say jput    'https://httpbin.org/put';
  
  ```
  
  # DESCRIPTION
  
  Exports a handful of routines to fetch data from online resources
  using HTTP verbs and optionally decode the responses as JSON.
  
  The module will set the `User-Agent` header to `Rakudo WWW`, unless you specify
  that header.
  
  # INSTALLATION
  
  On some operating systems you'll need `libssl` installed:
  
  ```
  sudo apt-get install libssl-dev
  
  ```
  
  Then just install the module with the module manager:
  
  ```
  zef install WWW
  
  ```
  
  # TESTING
  
  To run the full test suite, set `ONLINE_TESTING` environmental variable to `1`
  
  ```
  ONLINE_TESTING=1 zef install WWW
  
  ```
  
  # EXPORTED ROUTINES
  
  ## `:DEFAULT` export tag
  
  These routines get exported by default:
  
  ### `get`
  
  ```
  sub get($url where URI:D|Str:D, *%headers --> Str:D);
  
  say get 'https://httpbin.org/get?foo=42&bar=x';
  
  ```
  
  Takes either a `Str` or a [URI](https://modules.raku.org/dist/URI).
  Returns `Failure` if request fails or does not return a successful HTTP code.
  Returns `Str` with the data on success. Takes headers as named arguments.
  
  ### `jget`
  
  ```
  say jget 'https://httpbin.org/get?foo=42&bar=x';
  
  ```
  
  Same as `get()` except will also decode the response as JSON and return
  resultant data structure.
  
  ### `post`
  
  ```
  multi post($url where URI:D|Str:D, *%form --> Str:D);
  multi post($url where URI:D|Str:D, %headers, *%form --> Str:D);
  multi post($url where URI:D|Str:D, Str:D $form-body, *%headers --> Str:D);
  
  say post 'https://httpbin.org/post?meow=moo', :72foo, :bar<♵>;
  say post 'https://httpbin.org/post?meow=moo',
      %(Content-type => 'application/json'), :72foo, :bar<♵>;
  
  ```
  
  Takes either a `Str` or a [URI](https://modules.raku.org/dist/URI), followed
  by an optional `Hash` with HTTP headers to send. Form POST parameters can be
  included as named arguments. It's fine to also include query arguments in the
  URL itself. Returns `Failure` if request fails or does not return a successful
  HTTP code. Returns `Str` with the data on success.
  
  To send POST body directly, pass it as Str:D positional arg. In this calling
  form, the headers are sent as named args.
  
  ### `jpost`
  
  ```
  multi jpost($url where URI:D|Str:D, *%form);
  multi jpost($url where URI:D|Str:D, %headers, *%form);
  multi jpost($url where URI:D|Str:D, Str:D $form-body, *%headers);
  
  say jpost 'https://httpbin.org/post?meow=moo', :72foo, :bar<♵>;
  say jpost 'https://httpbin.org/post?meow=moo',
      %(Content-type => 'application/json'), :72foo, :bar<♵>;
  
  ```
  
  Same as `post()` except will also decode the response as JSON and return
  resultant data structure.
  
  ### `head`
  
  ```
  say head 'https://httpbin.org/get?foo=42&bar=x';
  
  ```
  
  Same as `get`, except it does not actually download the content, just the head.
  
  ## `:extras` Export Tag
  
  These routines get exported *in addition to* the `:DEFAULT` exports, when
  `:extras` export tag is requested:
  
  ```
  use WWW :extras;
  
  ```
  
  ### `put`
  
  ```
  multi put($url where URI:D|Str:D, *%form --> Str:D);
  multi put($url where URI:D|Str:D, %headers, *%form --> Str:D);
  multi put($url where URI:D|Str:D, Str:D $form-body, *%headers --> Str:D);
  
  say put 'https://httpbin.org/put?meow=moo', :72foo, :bar<♵>;
  say put 'https://httpbin.org/put?meow=moo',
      %(Content-type => 'application/json'), :72foo, :bar<♵>;
  
  ```
  
  Takes either a `Str` or a [URI](https://modules.raku.org/dist/URI), followed
  by an optional `Hash` with HTTP headers to send. Form PUT parameters can be
  included as named arguments. It's fine to also include query arguments in the
  URL itself. Returns `Failure` if request fails or does not return a successful
  HTTP code. Returns `Str` with the data on success.
  
  To send PUT body directly, pass it as Str:D positional arg. In this calling
  form, the headers are sent as named args.
  
  ### `jput`
  
  ```
  multi jput($url where URI:D|Str:D, *%form --> Str:D);
  multi jput($url where URI:D|Str:D, %headers, *%form --> Str:D);
  multi jput($url where URI:D|Str:D, Str:D $form-body, *%headers --> Str:D);
  
  say jput 'https://httpbin.org/put?meow=moo', :72foo, :bar<♵>;
  say jput 'https://httpbin.org/put?meow=moo',
      %(Content-type => 'application/json'), :72foo, :bar<♵>;
  
  ```
  
  Same as `put()` except will also decode the response as JSON and return
  resultant data structure.
  
  ### `delete`
  
  ```
  sub delete($url where URI:D|Str:D, *%headers --> Str:D);
  
  say delete 'https://httpbin.org/get?foo=42&bar=x';
  
  ```
  
  Performs HTTP `DELETE` request.
  Takes either a `Str` or a [URI](https://modules.raku.org/dist/URI).
  Returns `Failure` if request fails or does not return a successful HTTP code.
  Returns `Str` with the data on success; if response for a `204 No Content`,
  returns an empty string. Takes headers as named arguments.
  
  ### `jdelete`
  
  ```
  say jdelete 'https://httpbin.org/get?foo=42&bar=x';
  
  ```
  
  Same as `delete()` except will also decode the response as JSON and return
  resultant data structure.
  
  You probably want to use `delete()` instead, as `DELETE` requests can get
  return no content, causing JSON parse failures.
  
  # LIMITATIONS
  
  Due to nuances of upstream code, currently any non-RFC-conformant URL will
  be rejected; you have to ensure it's proper manually. Patches welcome.
  
  # SEE ALSO
  
  * [`LWP::Simple`](https://raku.land/zef:raku-community-modules/LWP::Simple)
  * [`HTTP::UserAgent`](https://raku.land/github:sergot/HTTP::UserAgent)
  
  ---
  
  #### REPOSITORY
  
  Fork this module on GitHub:
  <https://github.com/raku-community-modules/WWW>
  
  #### BUGS
  
  To report bugs or request features, please use
  <https://github.com/raku-community-modules/WWW/issues>
  
  #### ORIGINAL AUTHOR
  
  Zoffix Znet (<http://perl6.party/>)
  
  Now maintained by the Raku community as part of the [Raku community modules](https://github.com/raku-community-modules)
  
  #### LICENSE
  
  You can use and distribute this module under the terms of the
  The Artistic License 2.0. See the `LICENSE` file included in this
  distribution for complete details.
  
  The `META6.json` file of this distribution may be distributed and modified
  without restrictions or attribution.
  