An Emacs major mode for hurl, a cli tool for sending HTTP requests (using cURL under the hood) in plain text format similar to restclient.el, but can be used outside emacs and also has some additional testing utilities built in.
A simple wrapper for the cli command is provided via: hurl-mode-send-request with a shortcut of C-c C-c
If a hurl variable file, hurl-variable-file (default is .hurl-variables) exists in the same directory as the .hurl file we’re executing, the variables will automatically be added to the request.
With one prefix arg, will run the hurl file with --very-verbose
Running with this set, will also use the “captures” section of the very verbose output to write the captures to the specified hurl-variable-file
With two or more prefix args, we run it with --very-verbbose but also allows us to specify cli options to the hurl command.
With three or more prefix args, allow editing the jq command used to filter hurl response body.
There is some outline mode integration with the hurl response buffer to allow folding the sections.
Simple org babel implementation that passes the src block vars into the –variable option for the cli command
Simple example:
#+begin_src hurl :results output :var host="https://httpbin.org/post"
POST {{host}}
#+end_src
C-c xwill execute the hurl request at point in a temporary file created using the same directory as the original.C-c Xwill execute the entire hurl file.C-c Twill execute the hurl file in test mode.
If jq is available, then it will automatically be used to format what json exists in the response.
There’s a separate mode for the hurl response buffer. If you execute any of the commands with:
- one or more prefix args,
--very-verboseoption will be added. - With two or more, prompt for additional cli args.
- With three or more, edit the
jqcommand that will be used to filter/format the output.
Outline-minor-mode is automatically enabled with some custom outline methods. This makes it easy to navigate and see all the responses from the very-verbose output.
With emacs 29 we have built in package-vc-install and use-package now
(package-vc-install "https://github.com/JasZhe/hurl-mode")
(use-package hurl-mode :mode "\\.hurl\\'")With straight:
(straight-use-package
'(hurl-mode :type git :host github :repo "jaszhe/hurl-mode"))With doom:
(package! hurl-mode :recipe (:host github :repo "jaszhe/hurl-mode" :files ("*.el")))Add to auto mode alist
(add-to-list 'auto-mode-alist '("\\.hurl\\'" . hurl-mode))Hurl does have an existing mode included here but it was lacking some QOL features that I wanted like body highlighting depending on what language the body was in i.e. json/graphql
I created this repo so that it would be easier for me to incorporate requested changes from the emacs community.
Prior to this I was using the excellent restclient.el but I liked hurl because it’s a little more portable than sharing curl scripts to non-emacs users (albeit they need to have hurl installed)
Lastly, I also used this as an exercise to learn more about emacs lisp and how major modes are structured and as a way to give back to this wonderful editor known as emacs.
My use case for hurl is actually pretty simple. I just use it to send some basic requests with some auth capturing mixed in. I don’t really make too much use of the test/assertion facilities. So if you do have some more complicated use cases that aren’t covered here, feel free to drop an issue.
I mostly wrote this for two reasons, one to have some basic font locking and stuff for hurl (and also org babel integration where I find it most useful actually) and to learn a bit more elisp.
I won’t stop people from making PR’s but given the above, I would actually like to tackle any issues myself first :) if you would bear with my inexperience. Pointers and advice in the issues would also be appreciated for the same reason.
Took a lot of inspiration for the extend region function from haml-mode (no longer using extend region, instead sort of using the same hackyish method that org babel uses)
Also found this example very useful for multi line font locking
Another good resource here
The code in org for fontifying src blocks was also very useful, more info in the code. Also found this pretty useful for demystifying how the anchored search-based fontification worked.