hurl-mode

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 (now archived), but can be used outside emacs and also has some additional testing utilities built in.

Usage

• C-c x will execute the hurl request at point in a temporary file created using the same directory as the original.
• C-c X will execute the entire hurl file.
• C-c T will execute the hurl file in test mode.

Executing any of the commands with a prefix arg will prompt for additional hurl switches.

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.

There is some outline mode integration with the hurl response buffer to allow folding the sections.

Org Babel Integration

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

Response Output

Will try to format using json-pretty-print with font-locking by json-mode. If json-pretty-print fails we’ll fall back to using jq if its available.

In my effort to extract the response so I can do some formatting, I’ve trimmed down some of verbosity of the output from hurl. You can find the buffer that contains all the verbose output by searching for some sort of “*hurl-” buffer.

There’s a separate mode for the hurl response buffer. Outline-minor-mode is automatically enabled in the response buffer with some custom outline methods. This makes it easy to navigate and see all the responses from the very-verbose output.

Screenshot

Installation

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))

Motivation

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.

Contributing

I’m mostly using this as a nice text-based replacement for postman, hence maybe I’m not really using hurl to its fullest. I’m open to any issues for those who use some of the other features of hurl that are lacking in this little package of mine.

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.

Acknowledgements

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.