Add utility functions

CHANGELOG.md

@@ -17,6 +17,7 @@ New features / improvements:
 - URLs can now span multiple lines, place '\\' at the end of the URL line to continue it in the next one. Leading whitespace in the additional lines will be skipped.
 - Added new function `verb-body-lf-to-crlf` designed for use with requests sending multipart data.
 - Added new `Verb-Prelude` heading property, which can be used to specify an Emacs Lisp or JSON file to load variables from, before performing requests.
+- Added `verb-shell` and `verb-unix-epoch` utility functions.
 
 ## **2.16.0** - 2024-03-02 (MELPA Stable)
 - Fixed LF being used instead of CRLF in multipart boundaries.

README.md

@@ -385,6 +385,14 @@ You can enable completion for Emacs Lisp inside code tags. To do this, set the `
 
 Note that the point must be surrounded by the code tag delimiters (e.g. `{{` and `}}`) in the same line for completion to work. If you're using `electric-pair-mode`, matching tag delimiters will be inserted automatically, so this won't be a problem. `verb-mode` should also be enabled, as enabling it will load the completion function itself.
 
+### Utility Functions
+
+Verb offers some utility functions to be used within code tags, such as:
+- `verb-shell`: Currently, just an alias to `shell-command-to-string`.
+- `verb-unix-epoch`: Returns the current UNIX epoch (seconds) as an integer.
+- `verb-json-get`: Retrieves a value from within a JSON value.
+- `verb-read-file`: Reads the contents of a file (following some additional Verb-specific behaviour).
+
 ### Verb Variables
 
 Let's suppose that the two endpoints from the previous example now require authentication to be used. We could then modify the example to look like this:
@@ -520,7 +528,7 @@ get /{{(verb-json-get (oref verb-last body) "id")}}
 Accept: application/json
 ```
 
-The `verb-json-get` function takes a JSON-formatted text as its first argument and a list of keys as the rest, and returns the value under those keys in the JSON text (similar to how [JSONPath](https://goessner.net/articles/JsonPath/) works). This function is useful for using previous responses' contents, check its documentation for more details.
+The `verb-json-get` (mentioned earlier in this guide) function takes a JSON-formatted text as its first argument and a list of keys as the rest, and returns the value under those keys in the JSON text (similar to how [JSONPath](https://goessner.net/articles/JsonPath/) works). This function is useful for using previous responses' contents, check its documentation for more details.
 
 If you wish to use the last response's headers instead, you can use the `verb-headers-get` function. An example call may look like: `(verb-headers-get (oref verb-last headers) "Content-Type")`, which will return the string contents of the `Content-Type` response header.
 
@@ -710,6 +718,21 @@ You can export request specifications to other formats or tools by using the `ve
 > [!NOTE]
 > Code tags will be evaluated when exporting a request.
 
+### Long Lines
+
+Sometimes, lines containing URLs of your request specifications may become so long, that they may become difficult to read. You can break up these lines by using `\` followed by a newline character, like so:
+
+```
+* Make a request to an API         :verb:
+
+get https://example.com/api/users?fields=id,name,age\
+                                 &orderby=name,descending\
+                                 &filter=id>1000\
+                                 &count=false
+```
+
+The `\` character, the newline, and all the leading whitespace in the next line will be ignored. This behaviour only applies to the URL lines, not for the headers, nor the body.
+
 ### Cookies
 
 The Emacs `url` library (which Verb uses) has [support for cookies](https://www.gnu.org/software/emacs/manual/html_node/url/Cookies.html). This means that responses with the `Set-Cookie` header present will create cookies locally, that will later be sent back via the `Cookie` header.

verb.el

@@ -717,6 +717,14 @@ an error."
       (cdr val)
     (user-error "HTTP header has no value for \"%s\"" name)))
 
+
+(defalias 'verb-shell #'shell-command-to-string
+  "Alias to `shell-command-to-string'.")
+
+(defun verb-unix-epoch ()
+  "Return the current time as an integer number of seconds since the epoch."
+  (floor (time-to-seconds)))
+
 (defun verb-json-get (text &rest path)
   "Interpret TEXT as a JSON object and return value under PATH.
 The outermost JSON element in TEXT must be an object.
@@ -2056,6 +2064,7 @@ loaded into."
     (verb-kill-all-response-buffers t))
 
   (let* ((url (oref rs url))
+         (url-string (verb-request-spec-url-to-string rs))
          (url-request-method (verb--to-ascii (oref rs method)))
          (url-mime-accept-string (verb--get-accept-header (oref rs headers)))
          (url-request-extra-headers (verb--prepare-http-headers
@@ -2127,12 +2136,10 @@ loaded into."
     ;; Show user some quick information.
     (message "%s request sent to %s"
              (oref rs method)
-             (verb-request-spec-url-to-string rs))
+             url-string)
 
     ;; Log the request.
-    (verb-util--log num 'I "%s %s"
-                    (oref rs method)
-                    (verb-request-spec-url-to-string rs))
+    (verb-util--log num 'I "%s %s" (oref rs method) url-string)
 
     (pcase where
       ('other-window (switch-to-buffer-other-window response-buf))