-- | Cartel - a library to specify Cabal files in Haskell
--
-- The Cabal file format works very well for small projects.
-- However, in big projects with a library, many executables, and
-- test suites, some irritations emerge.  You need to specify
-- dependencies in multiple places, leading to redundancy.  You also
-- have to manually add in new modules, make sure you list all
-- modules (a real pain with executables, as problems may arise only
-- after you build a distribution tarball), and update your module
-- lists when you refactor.
--
-- Specifying your Cabal files in Haskell rather than in a
-- plain-text file format helps deal with a lot of these problems.
-- You have the full power of Haskell to make definitions in one
-- place and then reuse them.  You can also dynamically read a tree
-- of modules and use the result, thus avoiding the need to manually
-- update your module lists.
--
-- A disadvantage to Cartel is that it can be a bit more verbose
-- than a vanilla Cabal file.  In addition, you also have to
-- remember to generate the new Cabal file whenever you change the
-- script that generates your Cabal file.
--
-- Cabal already has an AST that it uses.  Cartel could, perhaps,
-- have re-used these structures.  Cartel does not do this for three
-- reasons.  First, the Cabal API is a bit untidy, partially because
-- it has to do things that Cartel doesn't have to worry about, but
-- also because the comments in the Cabal modules themselves
-- indicate that the whole thing could use a refactoring.  Second,
-- the Cabal developers make no commitment to keep that API stable.
-- Third, the Cartel API tries only to replicate format of the
-- plain-text Cabal file, which will be much more stable than the
-- Cabal API.
--
-- To get started, first study the "Cartel.Ast" module.  It contains
-- the data types that mirror the structure of a Cabal file.  You
-- will find that every Cabal feature, including test suites,
-- benchmarks, and conditionals, is represented.  Then look at
-- "Cartel.Tools", which has short functions to make Cartel easier
-- to use.  "Cartel.Render" has functions to transform "Cartel.Ast"
-- types to plain text; the necessary bits from here are exported
-- through "Cartel.Tools" so you shouldn't need to use this module
-- much if at all.
--
-- Also, examine the genCabal.hs file, which generates Cartel's own
-- Cabal file using Cartel.  To test it out, after installing Cartel
-- just run "runhaskell genCabal.hs".

module Cartel
  ( module Cartel.Ast
  , module Cartel.Defaults
  , module Cartel.Tools
  ) where

import Cartel.Ast
import Cartel.Defaults
import Cartel.Tools