{"id":13837543,"url":"https://github.com/chshersh/iris","last_synced_at":"2025-04-06T00:09:41.727Z","repository":{"id":39673649,"uuid":"491261030","full_name":"chshersh/iris","owner":"chshersh","description":"🌈 Haskell CLI Framework supporting Command Line Interface Guidelines","archived":false,"fork":false,"pushed_at":"2023-11-12T10:23:07.000Z","size":20427,"stargazers_count":181,"open_issues_count":19,"forks_count":22,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-10-29T21:10:52.276Z","etag":null,"topics":["cli","framework","haskell"],"latest_commit_sha":null,"homepage":"https://hackage.haskell.org/package/iris","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chshersh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":"FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["chshersh"]}},"created_at":"2022-05-11T20:21:36.000Z","updated_at":"2024-10-26T22:50:58.000Z","dependencies_parsed_at":"2023-11-12T11:24:29.934Z","dependency_job_id":"4c749f9b-c008-435a-9f6a-176109fe525a","html_url":"https://github.com/chshersh/iris","commit_stats":{"total_commits":65,"total_committers":13,"mean_commits":5.0,"dds":0.4307692307692308,"last_synced_commit":"e9b6c25df2bf179dc8d9f32f05c55aa8f7febcce"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chshersh%2Firis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chshersh%2Firis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chshersh%2Firis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chshersh%2Firis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chshersh","download_url":"https://codeload.github.com/chshersh/iris/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247415967,"owners_count":20935387,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","framework","haskell"],"created_at":"2024-08-04T15:01:13.297Z","updated_at":"2025-04-06T00:09:41.712Z","avatar_url":"https://github.com/chshersh.png","language":"Haskell","readme":"# iris\n\n[![GitHub CI](https://github.com/chshersh/iris/workflows/CI/badge.svg)](https://github.com/chshersh/iris/actions)\n[![Hackage](https://img.shields.io/hackage/v/iris.svg?logo=haskell)](https://hackage.haskell.org/package/iris)\n[![MPL-2.0 license](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](LICENSE)\n\n**Iris** is a Haskell framework for building CLI applications that follow\n[Command Line Interface Guidelines](https://clig.dev/).\n\n\u003e 🌈 Iris (/ˈaɪrɪs/) is a Greek goddess associated with communication, messages,\n\u003e the rainbow, and new endeavors.\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\"  srcset=\"https://raw.githubusercontent.com/chshersh/iris/main/images/iris-dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/chshersh/iris/main/images/iris-light.png\"\u003e\n  \u003cimg alt=\"Iris changing her workflow and hair colour depending on the time of day.\" src=\"https://raw.githubusercontent.com/chshersh/iris/main/images/iris-dark-always.png\"\u003e\n\u003c/picture\u003e\n\n\u003e ℹ️ **DISCLAIMER #1:** Currently, Iris is in experimental phase and\n\u003e mostly for early adopters. It may lack documentation or have\n\u003e significant breaking changes. We appreciate anyone's help in\n\u003e improving the documentation! At the same time, the maintainers will\n\u003e strive to provide helpful migration guides.\n\n\u003e ℹ️ **DISCLAIMER #2:** Iris is developed and maintained in free time\n\u003e by volunteers. The development may continue for decades or may stop\n\u003e tomorrow. You can use\n\u003e [GitHub Sponsorship](https://github.com/sponsors/chshersh) to support\n\u003e the development of this project.\n\n## Goals\n\nIris development is guided by the following principles:\n\n1. **Support [Command Line Interface Guidelines](https://clig.dev/).**\n   Features or changes that violate these guidelines are not accepted\n   in the project.\n2. **Beginner-friendliness.** Haskell beginners should be able to build\n   CLI applications with Iris. Hence, the implementation of Iris API\n   that uses less fancy Haskell features are preferred. When the\n   complexity is justified, the cost of introducing this extra\n   complexity should be mitigated by having better documentation.\n3. **Reasonable batteries-included.** Iris is not trying to be\n   minimalistic as possible, it strives to provide out-of-the-box\n   solutions for most common problems. But at the same time, we don't\n   want to impose unnecessary heavy dependencies.\n4. **Excellent documentation.** Iris documentation should be as\n   helpful as possible in using the framework.\n\n   \u003e **NOTE:** Currently, Iris may lack documentation but there's an\n   \u003e ongoing effort to improve the situation.\n\n5. **Single-line access.** Iris is designed for qualified imports, and you\n   should be able to get all the needed API by writing a single import line:\n\n   ```haskell\n   import qualified Iris\n   ```\n\n🧱 Iris focuses solely on CLI applications. If you're interested in\nbuilding TUI app with Haskell, check out\n[brick](https://hackage.haskell.org/package/brick).\n\n## Features\n\nCLI apps built with Iris offer the following features for end users:\n\n* Automatic detection of colouring support in the terminal\n* Ability to check required external tools if you need e.g. `curl` or\n  `git`\n* Support for standard CLI options out-of-the-box:\n    * `--help`\n    * `--version`\n    * `--numeric-version`: helpful for detecting required tools versions\n    * `--no-input`: for disabling all interactive features\n    * `--colour=(auto|never|always)`: to set colour mode\n    * `--no-colour`: to disable terminal colouring\n* Utilities to open files in a browser\n\n## Quick Start Guide\n\n\u003e 📚 Refer to [the complete Iris tutorial][simple-grep] for more details and\n\u003e examples of more Iris features.\n\n[simple-grep]: https://github.com/chshersh/iris/blob/main/examples/simple-grep/README.md\n\n`iris` is compatible with the following GHC\nversions - [supported versions](https://matrix.hackage.haskell.org/#/package/iris)\n\nIn order to start using `iris` in your project, you\nwill need to set it up with these steps:\n\n1. Add the dependency on `iris` in your project's\n   `.cabal` file. For this, you should modify the `build-depends`\n   section according to the below section:\n\n   ```haskell\n   build-depends:\n     , base ^\u003e= LATEST_SUPPORTED_BASE\n     , iris ^\u003e= LATEST_VERSION\n   ```\n\n2. To use this package, refer to the below example.\n\n   ```haskell\n   {-# LANGUAGE DerivingStrategies #-}\n   {-# LANGUAGE GeneralizedNewtypeDeriving #-}\n\n   module Main (main) where\n\n   import Control.Monad.IO.Class (MonadIO (..))\n\n   import qualified Iris\n\n\n   newtype App a = App\n       { unApp :: Iris.CliApp () () a\n       } deriving newtype\n           ( Functor\n           , Applicative\n           , Monad\n           , MonadIO\n           )\n\n   appSettings :: Iris.CliEnvSettings () ()\n   appSettings = Iris.defaultCliEnvSettings\n       { Iris.cliEnvSettingsHeaderDesc = \"Iris usage example\"\n       , Iris.cliEnvSettingsProgDesc = \"A simple 'Hello, world!' utility\"\n       }\n\n   app :: App ()\n   app = liftIO $ putStrLn \"Hello, world!\"\n\n   main :: IO ()\n   main = Iris.runCliApp appSettings $ unApp app\n   ```\n\n## For contributors\n\nCheck [CONTRIBUTING.md](https://github.com/chshersh/iris/blob/main/CONTRIBUTING.md)\nfor contributing guidelines.\n\n## Development\n\nTo build the project and run the tests locally, you can use either\n`cabal` or `stack`.\n\n\u003e See the [First time](#first-time) section if you don't have Haskell\n\u003e development environment locally.\n\n### Cabal\n\nBuild the project:\n\n```shell\ncabal build all\n```\n\nRun all unit tests:\n\n```shell\ncabal test --enable-tests --test-show-details=direct\n```\n\n### Stack\n\nBuild the project:\n\n```shell\nstack build --test --no-run-tests\n```\n\nRun all unit tests:\n\n```shell\nstack test\n```\n\n### First time\n\nIf this is your first time dealing with Haskell tooling, we recommend\nusing [GHCup](https://www.haskell.org/ghcup/).\n\nDuring the installation, GHCup will suggest you installing all the\nnecessary tools. If you have GHCup installed but miss some of the\ntooling for some reason, type the following commands in the terminal:\n\n```shell\nghcup install ghc 9.2.5\nghcup set     ghc 9.2.5\nghcup install cabal 3.8.1.0\n```\n\n\u003e If you are using Linux or macOS, you may find `ghcup tui` command a\n\u003e more attractive option.\n","funding_links":["https://github.com/sponsors/chshersh"],"categories":["Haskell","cli"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchshersh%2Firis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchshersh%2Firis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchshersh%2Firis/lists"}