imm

imm is a program that executes arbitrary callbacks (e.g. sending a mail, or writing a file) for each element of RSS/Atom feeds.

imm is written in Haskell, configured in Dhall. The project includes:

• a main executable imm that users run directly
• secondary executables (imm-writefile, imm-sendmail, imm-monolith) meant to be used as callbacks triggered by imm
• a Haskell library, that exports functions useful to both the main executable and callbacks; the API is documented in Hackage.

Installation

Using nix

This repository is notably a Nix flake that can be installed by running the following command at the root folder:

nix develop --command cabal build

Without nix

imm's executables can be installed using cabal-install tool:

cabal install imm

Then, the following runtime dependencies must be installed separately and provided in PATH:

• monolith (if using imm-monolith)
• pup

Configuration

Callbacks

Callbacks are configured through the $XDG_CONFIG_HOME/imm/callbacks.dhall file. A commented template file is bundled with the project.

imm will call each callback once per feed item, and will fill its standard input (stdin) with a JSON structure, which schema is described in file schema/imm.json.

Callback process is expected to return 0 in case of success, or any other exit code in case of failure, in which case the standard error output (stderr) will be displayed.

Example use cases

Online feed reader

For the sake of I-want-the-mutt-of-feed-readers zealots, it is possible to turn any mail reader into a feed reader, by having imm send an e-mail with unread elements to an arbitrary address. You can then browse your feeds through your favourite mail reader, and leverage any mail-related tool on your feeds. Bonus points if your mail reader is online as you can now access your feeds from any computer connected to the Internet.

Here is an example configuration:

let Callback : Type =
  { _executable : Text
  , _arguments : List Text
  }

let sendMail =
  { _executable = "imm-sendmail"
  , _arguments = []
  }

let config : List Callback = [ sendMail ]
in config

imm-sendmail does not have a built-in SMTP client, instead it must rely on an external SMTP client program, which is configured in $XDG_CONFIG_HOME/imm/sendmail.dhall (cf example bundled with the project.) imm-sendmail writes the mail bytestring to the standard input of the configured external program.

Offline read-it-later

imm is able to store a local copy of unread elements, to read them later while offline for example. There are 3 alternate ways of achieving this.

imm-writefile

imm-writefile will produce a light HTML file with no stylesheets, no scripts and with links to online resources (images, fonts, ...) that won't be available offline:

let Callback : Type =
  { _executable : Text
  , _arguments : List Text
  }

let writeFile =
  { _executable = "imm-writefile"
  , _arguments = [ "-d", "/path/to/folder" ]
  }

let config : List Callback = [ writeFile ]
in config

imm-monolith

imm-monolith will produce a heavy, self-contained HTML file, with embedded stylesheets, scripts, images and fonts; links to external web pages will still require an internet connection:

let Callback : Type =
  { _executable : Text
  , _arguments : List Text
  }

let downloadPage =
  { _executable = "imm-monolith"
  , _arguments = [ "-d", "/path/to/folder" ]
  }

let config : List Callback = [ downloadPage ]
in config

imm-wallabag

imm-wallabag will save webpages into a Wallabag server through its REST API:

let Callback : Type =
  { _executable : Text
  , _arguments : List Text
  }

let wallabag =
  { _executable = "imm-wallabag"
  , _arguments =
      [ "--host"
      , "INSERT_HOST"
      , "--port"
      , "INSERT_PORT"
      , "--client-id"
      , "INSERT_CLIENT_ID"
      , "--client-secret"
      , "INSERT_CLIENT_SECRET"
      , "--username"
      , "INSERT_WALLABAG_USERNAME"
      , "--password"
      , "INSERT_WALLABAG_PASSWORD"
      ]
  }

let config : List Callback = [ wallabag ]
in config

imm-shiori

imm-shiori will save webpages into Shiori bookmark manager:

let Callback : Type =
  { _executable : Text
  , _arguments : List Text
  }

let wallabag =
  { _executable = "imm-shiori"
  , _arguments =
      [ "--tags"
      , "TAG1,TAG2,TAG3"
      ]
  }

let config : List Callback = [ shiori ]
in config

Example usage

• Subscribe to a feed through direct URL:

  imm subscribe http://your.feed.org

• Subscribe to a feed through an alternate link:

  imm subscribe http://your.website.org

• List subscribed feeds:

  imm list

• Show details about a feed:

  imm show 10  # 10 is the index of a subscribed feed, as shown with `imm list`

• Unsubscribe from a feed:

  imm unsubscribe 10  # 10 is the index of a subscribed feed, as shown with `imm list`

• Check for new elements without executing any action:

  imm --read-only run --no-callbacks

• Execute configured callbacks for each new element from all subscribed feeds:

  imm run --all