diff options
| -rw-r--r-- | README.md | 94 |
1 files changed, 71 insertions, 23 deletions
@@ -4,11 +4,11 @@ Janet Curl (secretly Jean Curl) A libcurl easy API wrapper for Janet. It's divided into two components: `jurl/native`, which holds the low level C interfacing, and the high level `jurl` janet wrapper. -`jurl/native` is mostly feature complete. -If something you depend on is missing, and you have a good idea on how to represent it in Janet, let me know in the issues. - -`jurl`'s core functionality is complete. -There are still some utility functions for convenience to be written, but it's perfectly usable as it is. +The library is mostly finished. +There are a few minor features missing (e.g ioctl overrides). +There's also a few niceties to think about (for example, custom cookie parsing and mapping). +However, for 90+% of use-cases, it should be more than sufficient, +and is far more complete and convenient than most http clients I've worked with so far, including in other languages. For examples of the various APIs, see the tests! P.S. There are no tests yet, soon though. @@ -16,6 +16,15 @@ P.S. There are no tests yet, soon though. ## Installation `jpm install https://github.com/cosmictoast/jurl.git` +You can add it to your `project.janet` dependency list like so: +```janet +(declare-project + :name "my-project" + :dependencies + [{:url "https://github.com/cosmictoast/jurl.git" + :tag "v1.0.0"}] +``` + This wraps around libcurl, and as such needs libcurl (library and headers for building) installed. Tested on linux and macos. @@ -26,34 +35,58 @@ I'm open to implementing what's left, but it's generally very niche things, such ## Jurl `jurl` is a requests-style API, but more complete. -For the main chunk of docs, see `jurl/init.janet`'s `request` symbol documentation. +You can use the `jurl/request` function directly (see its documentation for more details), +or the pipeline high level API. -A few basic examples. -Get with a query: +Here are a few basic examples. ```janet -(request {:url "https://pie.dev/get" - :query {:a "b" - :c "d"}}) -# -> {:body @"..." :error :ok :handle <jurl> :status 200} +# prepare and execute a GET to pie.dev/get +((http :get "https://pie.dev/get")) +# => {:body "..." :cookies [] :error :ok :handle <jurl> :status 200} ``` -A post with multipart mime (including file uploads): ```janet -(request {:url "https://pie.dev/post" - :body [{:name "field name" - :filename "remote.file" # this is what makes it a file upload - :data [:file "local.file"]}]}) +# prepare a POST to pie.dev/post +(def post (http :post "https://pie.dev/post")) +# add a body +(def post-body (body "my body" post)) +# set content-type to text/plain +(def post-body-ct (headers {:content-type "text/plain"} post-body)) +# launch the request +(post-body-ct) +# => {:body "..." :cookies [] :error :ok :handle <jurl> :status 200} ``` -A post with json: ```janet -(request {:url "https://pie.dev/post" - :body (json/encode {:a "b" - :c "d"}) - :headers {:content-type "application/json"}) -# -> {:body @"..." :error :ok :handle <jurl> :status 200} +# equivalent to the previous example +((->> "https://pie.dev/post" + (http :post) + (body "my body") + (headers {:content-type "text/plain"}))) ``` +```janet +# example of preparing and modifying a request +(def req (->> "https://pie.dev/post" + (http :post) + (body "my body") + (headers {:content-type "application/octet-stream"}))) +# oops I want it to be application/json +(def req2 (->> req + (headers {:content-type "application/json" + :custom-header "custom-value"}))) +# you can still use the old prepared request +(req) # => {:body ...} +# actually, in the end, I want text/plain +# note that custom-header is still set +(req2 {:headers {:content-type "text/plain"}}) +# => {:body ...} +``` + +For more details, have a read through `jurl/init.janet`. +I promise it's not very complex. +For instance, you'll see how to extend the pipeline yourself with custom functions (`defapi`). + ## Jurl/Native `jurl/native` attempts to implement as much of libcurl's easy API in as direct a manner as possible. @@ -66,3 +99,18 @@ Ones that are extremely common are not prefixed, such as various `:auth/` keys. Bitmaps are translated back and forth using indexables (arrays and tuples). For example, `CURLAUTH_BASIC | CURLAUTH_DIGEST` becomes `[basic digest]`. + +Here's an example of a basic POST request using `jurl/native`. +```janet +(import jurl/native) +(def output-body @"") +(def client (native/new)) +(put client :post true) +(put client :postfields "mybody") +(put client :httpheader ["my-header: header value"]) +(put client :url "https://pie.dev/post") +(put client :writefunction |(buffer/push output-body $)) +(:perform client) +(print output-body) +(print (client :response-code)) +``` |