GitHub.REST.Monad

Defines GitHubT and MonadGitHubREST, a monad transformer and type class that gives a monad m the capability to query the GitHub REST API.

MonadGitHubREST API

class Monad m => MonadGitHubREST m where

A type class for monads that can query the GitHub REST API.

Example:

-- create the "foo" branch
queryGitHub GHEndpoint
  { method = POST
  , endpoint = "/repos/:owner/:repo/git/refs"
  , endpointVals =
    [ "owner" := "alice"
    , "repo" := "my-project"
    ]
  , ghData =
    [ "ref" := "refs/heads/foo"
    , "sha" := "1234567890abcdef"
    ]
  }

It's recommended that you create functions for the API endpoints you're using:

deleteBranch branch = queryGitHub GHEndpoint
  { method = DELETE
  , endpoint = "/repos/:owner/:repo/git/refs/:ref"
  , endpointVals =
    [ "owner" := "alice"
    , "repo" := "my-project"
    , "ref" := "heads/" <> branch
    ]
  , ghData = []
  }

Minimal complete definition

queryGitHubPage

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> m (a, PageLinks)

Query GitHub, returning (payload, links) if successful, where payload is the response that GitHub sent back and links containing any pagination links GitHub may have sent back. If the response could not be decoded as JSON, returns Left (error message, response from server).

Errors on network connection failures, if GitHub sent back an error message, or if the response could not be decoded as JSON. Use githubTry if you wish to handle GitHub errors.

queryGitHub :: FromJSON a => GHEndpoint -> m a

queryGitHubPage, except ignoring pagination links.

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> m a

Repeatedly calls queryGitHubPage for each page returned by GitHub and concatenates the results.

queryGitHub_ :: GHEndpoint -> m ()

queryGitHub, except ignores the result.

Instances

MonadGitHubREST m => MonadGitHubREST (MaybeT m)

Defined in GitHub.REST.Monad.Class

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> MaybeT m (a, PageLinks)

queryGitHub :: FromJSON a => GHEndpoint -> MaybeT m a

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> MaybeT m a

queryGitHub_ :: GHEndpoint -> MaybeT m ()

MonadIO m => MonadGitHubREST (GitHubT m)

Defined in GitHub.REST.Monad

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> GitHubT m (a, PageLinks)

queryGitHub :: FromJSON a => GHEndpoint -> GitHubT m a

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> GitHubT m a

queryGitHub_ :: GHEndpoint -> GitHubT m ()

MonadGitHubREST m => MonadGitHubREST (IdentityT m)

Defined in GitHub.REST.Monad.Class

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> IdentityT m (a, PageLinks)

queryGitHub :: FromJSON a => GHEndpoint -> IdentityT m a

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> IdentityT m a

queryGitHub_ :: GHEndpoint -> IdentityT m ()

MonadGitHubREST m => MonadGitHubREST (ExceptT e m)

Defined in GitHub.REST.Monad.Class

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> ExceptT e m (a, PageLinks)

queryGitHub :: FromJSON a => GHEndpoint -> ExceptT e m a

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> ExceptT e m a

queryGitHub_ :: GHEndpoint -> ExceptT e m ()

MonadGitHubREST m => MonadGitHubREST (ReaderT r m)

Defined in GitHub.REST.Monad.Class

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> ReaderT r m (a, PageLinks)

queryGitHub :: FromJSON a => GHEndpoint -> ReaderT r m a

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> ReaderT r m a

queryGitHub_ :: GHEndpoint -> ReaderT r m ()

MonadGitHubREST m => MonadGitHubREST (StateT s m)

Defined in GitHub.REST.Monad.Class

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> StateT s m (a, PageLinks)

queryGitHub :: FromJSON a => GHEndpoint -> StateT s m a

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> StateT s m a

queryGitHub_ :: GHEndpoint -> StateT s m ()

MonadGitHubREST m => MonadGitHubREST (StateT s m)

Defined in GitHub.REST.Monad.Class

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> StateT s m (a, PageLinks)

queryGitHub :: FromJSON a => GHEndpoint -> StateT s m a

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> StateT s m a

queryGitHub_ :: GHEndpoint -> StateT s m ()

(Monoid w, MonadGitHubREST m) => MonadGitHubREST (WriterT w m)

Defined in GitHub.REST.Monad.Class

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> WriterT w m (a, PageLinks)

queryGitHub :: FromJSON a => GHEndpoint -> WriterT w m a

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> WriterT w m a

queryGitHub_ :: GHEndpoint -> WriterT w m ()

(Monoid w, MonadGitHubREST m) => MonadGitHubREST (WriterT w m)

Defined in GitHub.REST.Monad.Class

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> WriterT w m (a, PageLinks)

queryGitHub :: FromJSON a => GHEndpoint -> WriterT w m a

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> WriterT w m a

queryGitHub_ :: GHEndpoint -> WriterT w m ()

(Monoid w, MonadGitHubREST m) => MonadGitHubREST (RWST r w s m)

Defined in GitHub.REST.Monad.Class

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> RWST r w s m (a, PageLinks)

queryGitHub :: FromJSON a => GHEndpoint -> RWST r w s m a

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> RWST r w s m a

queryGitHub_ :: GHEndpoint -> RWST r w s m ()

(Monoid w, MonadGitHubREST m) => MonadGitHubREST (RWST r w s m)

Defined in GitHub.REST.Monad.Class

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> RWST r w s m (a, PageLinks)

queryGitHub :: FromJSON a => GHEndpoint -> RWST r w s m a

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> RWST r w s m a

queryGitHub_ :: GHEndpoint -> RWST r w s m ()

queryGitHubPageIO :: FromJSON a => GitHubManager -> GHEndpoint -> IO (a, PageLinks)

Same as queryGitHubPage, except explicitly taking in GitHubManager and running in IO.

Useful for implementing MonadGitHubREST outside of GitHubT.

GitHubManager

data GitHubManager

initGitHubManager :: GitHubSettings -> IO GitHubManager

Initialize a GitHubManager.

GitHubSettings

data GitHubSettings

Constructors

GitHubSettings

Fields

• token :: Maybe Token

  The token to use to authenticate with the API.

• userAgent :: ByteString

  The user agent to use when interacting with the API: https://developer.github.com/v3/#user-agent-required

• apiVersion :: ByteString

  The media type will be sent as: application/vnd.github.VERSION+json. For the standard API endpoints, "v3" should be sufficient here. See https://developer.github.com/v3/media/

GitHubT

data GitHubT m a

A simple monad that can run REST calls.

Instances

MonadTrans GitHubT

Defined in GitHub.REST.Monad

Methods

lift :: Monad m => m a -> GitHubT m a

Monad m => Monad (GitHubT m)

Defined in GitHub.REST.Monad

Methods

(>>=) :: GitHubT m a -> (a -> GitHubT m b) -> GitHubT m b

(>>) :: GitHubT m a -> GitHubT m b -> GitHubT m b

return :: a -> GitHubT m a

Functor m => Functor (GitHubT m)

Defined in GitHub.REST.Monad

Methods

fmap :: (a -> b) -> GitHubT m a -> GitHubT m b

(<$) :: a -> GitHubT m b -> GitHubT m a

MonadFail m => MonadFail (GitHubT m)

Defined in GitHub.REST.Monad

Methods

fail :: String -> GitHubT m a

Applicative m => Applicative (GitHubT m)

Defined in GitHub.REST.Monad

Methods

pure :: a -> GitHubT m a

(<*>) :: GitHubT m (a -> b) -> GitHubT m a -> GitHubT m b

liftA2 :: (a -> b -> c) -> GitHubT m a -> GitHubT m b -> GitHubT m c

(*>) :: GitHubT m a -> GitHubT m b -> GitHubT m b

(<*) :: GitHubT m a -> GitHubT m b -> GitHubT m a

MonadIO m => MonadIO (GitHubT m)

Defined in GitHub.REST.Monad

Methods

liftIO :: IO a -> GitHubT m a

MonadUnliftIO m => MonadUnliftIO (GitHubT m)

Defined in GitHub.REST.Monad

Methods

withRunInIO :: ((forall a. GitHubT m a -> IO a) -> IO b) -> GitHubT m b

MonadIO m => MonadGitHubREST (GitHubT m)

Defined in GitHub.REST.Monad

Methods

queryGitHubPage :: FromJSON a => GHEndpoint -> GitHubT m (a, PageLinks)

queryGitHub :: FromJSON a => GHEndpoint -> GitHubT m a

queryGitHubAll :: (FromJSON a, Monoid a) => GHEndpoint -> GitHubT m a

queryGitHub_ :: GHEndpoint -> GitHubT m ()

runGitHubT :: MonadIO m => GitHubSettings -> GitHubT m a -> m a

Run the given GitHubT action with the given token and user agent.

The token will be sent with each API request -- see Token. The user agent is also required for each API request -- see https://developer.github.com/v3/#user-agent-required.