iris

Iris is a Haskell framework for building CLI applications that follow Command Line Interface Guidelines.

ℹ️ DISCLAIMER #1: Currently, Iris is in experimental phase and mostly for early adopters. It may lack documentation or have significant breaking changes. We appreciate anyone's help in improving the documentation! At the same time, the maintainers will strive to provide helpful migration guides.

ℹ️ DISCLAIMER #2: Iris is developed and maintained in free time by volunteers. The development may continue for decades or may stop tomorrow. You can use GitHub Sponsorship to support the development of this project.

Goals

Iris development is guided by the following principles:

1. Support Command Line Interface Guidelines. Features or changes that violate these guidelines are not accepted in the project.

2. Beginner-friendliess. Haskell beginners should be able to build CLI applications with Iris. Hence, the implementation of Iris API that uses less fancy Haskell features are preferred. When the complexity is justified, the cost of introducing this extra complexity should be mitigated by having better documentation.

3. Reasonable batteries-included. Iris is not trying to be minimalistic as possible, it strives to provide out-of-the-box solutions for most common problems. But at the same time, we don't want to impose unnecessary heavy dependencies.

4. Excellent documentation. Iris documentation should be as helpful as possible in using the framework.

   NOTE: Currently, Iris may lack documentation but there's an ongoing effor to improve the situation.

Features

Iris offers the following features:

• Automatic detection of colouring support and colour-formatting functions
• Standard CLI flags --version and --numeric-version (the latter is helpful for detecting required tools versions)
• Ability to check required external tools if you need e.g. curl or git or for your app
• Utilities to open files in a browser

How to use?

iris is compatible with the following GHC versions - supported versions

In order to start using iris in your project, you will need to set it up with these steps:

1. Add the dependency on iris in your project's .cabal file. For this, you should modify the build-depends section according to the below section:

   build-depends:
     , base ^>= LATEST_SUPPORTED_BASE
     , iris ^>= LATEST_VERSION

2. To use this package, refer to the below example.

   {-# LANGUAGE GeneralizedNewtypeDeriving #-}
   
   module Main (main) where
   
   import Control.Monad.IO.Class (MonadIO (..))
   
   import qualified Iris
   
   
   newtype App a = App
       { unApp :: Iris.CliApp () () a
       } deriving newtype
           ( Functor
           , Applicative
           , Monad
           , MonadIO
           )
   
   appSettings :: Iris.CliEnvSettings () ()
   appSettings = Iris.defaultCliEnvSettings
       { Iris.cliEnvSettingsHeaderDesc = "Iris usage example"
       , Iris.cliEnvSettingsProgDesc = "A simple 'Hello, world!' utility"
       }
   
   app :: App ()
   app = liftIO $ putStrLn "Hello, world!"
   
   main :: IO ()
   main = Iris.runCliApp appSettings $ unApp app

For contributors

Check CONTRIBUTING.md for contributing guidelines.

Building the project

To build the project and run the tests locally, you can use either cabal or stack:

cabal build all
cabal test --enable-tests --test-show-details=direct

or

stack build
stack test

If this is your first time dealing with Haskell tooling, we recommend using GHCup (which you can get here) for the initial setup.

During the installation, GHCup will suggest you installing all the necessary tools. If you have GHCup installed but miss some of the tooling for some reason, just enter

ghcup install <tool>

into the terminal.

(Also, if you are using Linux or macOS, you may find ghcup tui command a more attractive option.)