Home

Awesome

Import of Postman collections in Emacs

Build Status MELPA MELPA Stable

Postman collections and environments can be imported and used with these Emacs HTTP clients:

Requirements

This package requires:

Optional dependencies:

Note: without these optional dependencies, you can still convert to all formats, but the mode will not be set in the buffer once converted.

Installation

You can install Impostman with package-install command, either from MELPA or MELPA Stable:

<kbd>M-x</kbd> package-install <kbd>RET</kbd> impostman <kbd>RET</kbd>

Alternatively, you can deploy impostman.el into your site-lisp as usual, then add this line to your Emacs initialization file:

(require 'impostman)

Usage

Two functions can be called interactively to import a Postman collection, with an optional environment:

The function impostman-import-file takes three optional parameters (they are asked interactively if not provided):

Example:

(impostman-import-file "/path/to/collection.json" "/path/to/environment.json" "verb")

The function impostman-import-string takes three parameters (the third is optional and asked interactively if not provided):

Example:

(impostman-import-string "{}" "" "verb")

The result is displayed in a new buffer with the Emacs HTTP client, and the mode is set to:

Customization

Some options can be customized to alter the output, you can list and change them with:

<kbd>M-x</kbd> customize-group <kbd>RET</kbd> impostman <kbd>RET</kbd>

List of variables:

Add new output

Two low-level functions can also be called (non interactively), with a custom output (alist).

This alist must be defined like this, for example if your output is for walkman (another HTTP client for Emacs):

(defconst my-impostman-walkman-alist
  '((init . my-impostman-walkman-init)
    (replace-vars . my-impostman-walkman-replace-vars)
    (header . my-impostman-walkman-header)
    (item . my-impostman-walkman-item)
    (request . my-impostman-walkman-request)
    (footer . my-impostman-walkman-footer)
    (end . my-impostman-walkman-end))
  "Emacs walkman output")

Keys are fixed symbols and values are callback functions.

A function can be ignore, in this case it is simply ignored, for example if you don't have anything to do for init and end:

(defconst my-impostman-walkman-alist
  '((init . ignore)
    (replace-vars . my-impostman-walkman-replace-vars)
    (header . my-impostman-walkman-header)
    (item . my-impostman-walkman-item)
    (request . my-impostman-walkman-request)
    (footer . my-impostman-walkman-footer)
    (end . ignore))
  "Emacs walkman output")

Then you can call for a file:

(impostman-parse-file "/path/to/collection.json" "/path/to/environment.json" my-impostman-walkman-alist)

And for a string:

(impostman-parse-string "{}" "" my-impostman-walkman-alist)

You can also add your output to the list of impostman outputs, so you can use it with impostman-import-file and impostman-import-string:

(push '("walkman" . my-impostman-walkman-alist) impostman-outputs-alist)

This will put your output at the beginning of the alist, so it will be the default output.

Callback functions

init

(defun xxx-init (variables)
  (...))

Function called when the output buffer is created and before parsing the collection.

Arguments:

replace-vars

(defun xxx-replace-vars (string variables)
  (...))

Function called to replace Postman variables (format: {{variable}}) in a string. It must return a string where the Postman variables have been replaced by the appropriate value (according to the output).

Note: according to the option impostman-use-variables, a variable is either replaced with a reference (by default and the format depends on the output) or directly with its value, if the option is set to nil.

Arguments:

header

(defun xxx-header (name description variables)
  (...))

Function called after init and before parsing the collection. It must return a string which is inserted in the output buffer.

Arguments:

item

(defun xxx-item (level name description variables)
  (...))

Function called for each item read (a folder in Postman). It must return a string which is inserted in the output buffer.

Arguments:

request

(defun xxx-request (description method url headers body variables)
  (...))

Function called for each request read. It must return a string which is inserted in the output buffer.

Arguments:

footer

(defun xxx-footer (name variables)
  (...))

Function called at the end of parsing. It must return a string which is inserted in the output buffer.

Arguments:

end

(defun xxx-end (variables)
  (...))

Function called at the end. It can be used to enable a major or minor mode.

Arguments:

Known limitations

For now the package offers a basic support of Postman collections and environments, the following features are partially implemented:

Pull requests are welcome to add missing features.

Copyright

Copyright © 2020-2024 Sébastien Helleu

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.