Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/chshersh/iris
🌈 Haskell CLI Framework supporting Command Line Interface Guidelines
https://github.com/chshersh/iris
cli framework haskell
Last synced: 13 days ago
JSON representation
🌈 Haskell CLI Framework supporting Command Line Interface Guidelines
- Host: GitHub
- URL: https://github.com/chshersh/iris
- Owner: chshersh
- License: mpl-2.0
- Created: 2022-05-11T20:21:36.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-11-12T10:23:07.000Z (almost 1 year ago)
- Last Synced: 2024-05-05T21:43:07.297Z (6 months ago)
- Topics: cli, framework, haskell
- Language: Haskell
- Homepage: https://hackage.haskell.org/package/iris
- Size: 19.5 MB
- Stars: 170
- Watchers: 7
- Forks: 21
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# iris
[](https://github.com/chshersh/iris/actions)
[](https://hackage.haskell.org/package/iris)
[](LICENSE)
**Iris** is a Haskell framework for building CLI applications that follow
[Command Line Interface Guidelines](https://clig.dev/).
> 🌈 Iris (/ˈaɪrɪs/) is a Greek goddess associated with communication, messages,
> the rainbow, and new endeavors.
> ℹ️ **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](https://github.com/sponsors/chshersh) to support
> the development of this project.
## Goals
Iris development is guided by the following principles:
1. **Support [Command Line Interface Guidelines](https://clig.dev/).**
Features or changes that violate these guidelines are not accepted
in the project.
2. **Beginner-friendliness.** 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 effort to improve the situation.
5. **Single-line access.** Iris is designed for qualified imports, and you
should be able to get all the needed API by writing a single import line:
```haskell
import qualified Iris
```
🧱 Iris focuses solely on CLI applications. If you're interested in
building TUI app with Haskell, check out
[brick](https://hackage.haskell.org/package/brick).
## Features
CLI apps built with Iris offer the following features for end users:
* Automatic detection of colouring support in the terminal
* Ability to check required external tools if you need e.g. `curl` or
`git`
* Support for standard CLI options out-of-the-box:
* `--help`
* `--version`
* `--numeric-version`: helpful for detecting required tools versions
* `--no-input`: for disabling all interactive features
* `--colour=(auto|never|always)`: to set colour mode
* `--no-colour`: to disable terminal colouring
* Utilities to open files in a browser
## Quick Start Guide
> 📚 Refer to [the complete Iris tutorial][simple-grep] for more details and
> examples of more Iris features.
[simple-grep]: https://github.com/chshersh/iris/blob/main/examples/simple-grep/README.md
`iris` is compatible with the following GHC
versions - [supported versions](https://matrix.hackage.haskell.org/#/package/iris)
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:
```haskell
build-depends:
, base ^>= LATEST_SUPPORTED_BASE
, iris ^>= LATEST_VERSION
```
2. To use this package, refer to the below example.
```haskell
{-# LANGUAGE DerivingStrategies #-}
{-# 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](https://github.com/chshersh/iris/blob/main/CONTRIBUTING.md)
for contributing guidelines.
## Development
To build the project and run the tests locally, you can use either
`cabal` or `stack`.
> See the [First time](#first-time) section if you don't have Haskell
> development environment locally.
### Cabal
Build the project:
```shell
cabal build all
```
Run all unit tests:
```shell
cabal test --enable-tests --test-show-details=direct
```
### Stack
Build the project:
```shell
stack build --test --no-run-tests
```
Run all unit tests:
```shell
stack test
```
### First time
If this is your first time dealing with Haskell tooling, we recommend
using [GHCup](https://www.haskell.org/ghcup/).
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, type the following commands in the terminal:
```shell
ghcup install ghc 9.2.5
ghcup set ghc 9.2.5
ghcup install cabal 3.8.1.0
```
> If you are using Linux or macOS, you may find `ghcup tui` command a
> more attractive option.