View Source CurlReq (CurlReq v0.99.0)

Req is awesome, but the world speaks curl.

Next time you're debugging a 3rd party API and need to ask for support, you can just toss in this line:

|> CurlReq.inspect()

And you'll have the full curl command.

Read the announcement here.

Usage

Req to Curl 

# Turn a Req request into a `curl` command.

iex> Req.new(url: "/fact", base_url: "https://example.com/")
...> |> CurlReq.to_curl()
"curl --compressed -X GET https://example.com/fact" 

# Or use `CurlReq.inspect/2` to inspect inline.

Req.new(url: "https://example.com")
|> CurlReq.inspect()
|> Req.request!()
#=> curl --compressed -X GET https://example.com

Curl to Req

CurlReq also implements the ~CURL sigil, which converts a curl command to its corresponding Req request.

iex> import CurlReq
...> ~CURL(curl https://www.example.com)
...> # |> Req.request!()

or use CurlReq.from_curl/1:

iex> CurlReq.from_curl("curl https://example.com")
...> # |> Req.request!()

Req Plugin

One final feature to note the Req plugin, CurlReq.Plugin. Use CurlReq.Plugin.attach/2 to set up curl logging (inspired by TeslaCurl).

iex> Req.new(url: "/fact", base_url: "https://example.com/")
...> |> CurlReq.Plugin.attach()
...> # |> Req.request!()

Summary

Types

flags()
flavor()
inspect_opt()
to_curl_opts()

Functions

from_curl(curl_command)

Transforms a curl command into a Req request.

inspect(req, opts \\ [])

Inspect a Req struct in curl syntax.

sigil_CURL(curl_command, modifiers)

Same as from_curl/1 but as a sigil. The benefit here is, that the Req.Request struct will be created at compile time and you don't need to escape the string

to_curl(req, options \\ [])

Transforms a Req request into a curl command.

Types

flags()

@type flags() :: :short | :long

flavor()

@type flavor() :: :curl | :req

inspect_opt()

@type inspect_opt() :: {:label, String.t()}

to_curl_opts()

@type to_curl_opts() :: [
  flags: flags(),
  flavor: flavor(),
  flavour: flavor(),
  run_steps: boolean() | [{:only, [atom()]}] | [{:except, [atom()]}]
]

Functions

from_curl(curl_command)

(since 0.98.4) 
@spec from_curl(String.t()) :: Req.Request.t()

Transforms a curl command into a Req request.

Supported curl command line flags are supported:

  • -H/--header
  • -X/--request
  • -d/--data
  • -b/--cookie
  • -I/--head
  • -F/--form
  • -L/--location
  • -u/--user
  • -x/--proxy
  • -U/--proxy-user
  • --compressed

The curl command prefix is optional

Info

Only string inputs are supported. That means for example -d @data.txt will not load the file or -d @- will not read from stdin

Examples 

iex> CurlReq.from_curl("curl https://www.example.com")
%Req.Request{method: :get, url: URI.parse("https://www.example.com")}

iex> ~S(curl -d "some data" https://example.com) |> CurlReq.from_curl()
%Req.Request{method: :get, body: "some data", url: URI.parse("https://example.com")}

iex> CurlReq.from_curl("curl -I https://example.com")
%Req.Request{method: :head, url: URI.parse("https://example.com")}

iex> CurlReq.from_curl("curl -b cookie_key=cookie_val https://example.com")
%Req.Request{method: :get, headers: %{"cookie" => ["cookie_key=cookie_val"]}, url: URI.parse("https://example.com")}

inspect(req, opts \\ [])

@spec inspect(Req.Request.t(), [inspect_opt()]) :: Req.Request.t()

Inspect a Req struct in curl syntax.

Returns the unchanged req, just like IO.inspect/2.

Examples 

Req.new(url: "https://example.com")
|> CurlReq.inspect()
|> Req.request!()
#=> curl --compressed -X GET https://example.com

sigil_CURL(curl_command, modifiers)

(macro)

Same as from_curl/1 but as a sigil. The benefit here is, that the Req.Request struct will be created at compile time and you don't need to escape the string

Examples 

iex> import CurlReq
...> ~CURL(curl "https://www.example.com")
%Req.Request{method: :get, url: URI.parse("https://www.example.com")}

iex> import CurlReq
...> ~CURL(curl -d "some data" "https://example.com")
%Req.Request{method: :get, body: "some data", url: URI.parse("https://example.com")}

iex> import CurlReq
...> ~CURL(curl -I "https://example.com")
%Req.Request{method: :head, url: URI.parse("https://example.com")}

iex> import CurlReq
...> ~CURL(curl -b "cookie_key=cookie_val" "https://example.com")
%Req.Request{method: :get, headers: %{"cookie" => ["cookie_key=cookie_val"]}, url: URI.parse("https://example.com")}

to_curl(req, options \\ [])

@spec to_curl(Req.Request.t(), to_curl_opts()) :: String.t()

Transforms a Req request into a curl command.

Supported curl flags are:

  • -b/--cookie
  • -H/--header
  • -X/--request
  • -L/--location
  • -I/--head
  • -d/--data/--data-ascii
  • --data-raw
  • -x/--proxy
  • -U/--proxy-user
  • -u/--user
  • -n/--netrc
  • --netrc-file

Options:

  • run_steps: Run the Req.Steps before generating the curl command to have fine-tuned control over the Req.Request. Default: true.
    • true: Run all steps
    • false: Run no steps
    • only: [atom()]: A list of step names as atoms and only they will be executed
    • except: [atom()]: A list of step names as atoms and these steps will be excluded from the executed steps
  • flags: Specify the style the argument flags are constructed. Can either be :short or :long, Default: :short
  • flavor or flavour: With the :curl flavor (the default) it will try to use native curl representations for compression, auth and will use the native user agent. If flavor is set to :req the headers will not be modified and the curl command is constructed to stay as true as possible to the original Req.Request

Examples 

iex> Req.new(url: URI.parse("https://www.example.com"))
...> |> CurlReq.to_curl()
~S(curl --compressed -X GET https://www.example.com)

iex> Req.new(url: URI.parse("https://www.example.com"))
...> |> CurlReq.to_curl(flags: :long, flavor: :req)
~S(curl --header "accept-encoding: gzip" --header "user-agent: req/0.5.8" --request GET https://www.example.com)

iex> Req.new(url: "https://www.example.com")
...> |> CurlReq.to_curl(run_steps: [except: [:compressed]])
~S(curl -X GET https://www.example.com)