-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A Haskell interface to the Bugzilla native REST API
--   
--   This package is designed to provide an easy-to-use, type-safe
--   interface to querying Bugzilla from Haskell.
--   
--   This is a friendly fork of Seth Fowler's library, with updates and API
--   tweaks needed for bugzilla.redhat.com.
@package bugzilla-redhat
@version 1.0.1.1


-- | This package is designed to provide an easy-to-use, typesafe interface
--   to querying Bugzilla from Haskell.
--   
--   A modified version of Web.Bugzilla to support the list fields in Red
--   Hat's modified bugzilla API.
--   
--   A very simple program using this package might look like this:
--   
--   <pre>
--   let session = anonymousSession "https://bugzilla.redhat.com"
--       user = "me@example.org"
--       query = AssignedToField .==. user .&amp;&amp;.
--               FlagRequesteeField .==. user .&amp;&amp;.
--               (FlagsField `contains` "review" .||. FlagsField `contains` "feedback")
--   bugs &lt;- searchBugs session query
--   mapM_ (putStrLn . show . bugSummary) bugs
--   </pre>
--   
--   There's a more in-depth demo program included with the source code to
--   this package.
module Web.RedHatBugzilla

-- | Creates a <a>BugzillaSession</a> using the provided api key.
apikeySession :: BugzillaServer -> BugzillaApiKey -> BugzillaSession

-- | Creates an anonymous <a>BugzillaSession</a>. Note that some content
--   will be hidden by Bugzilla when you make queries in this state.
anonymousSession :: BugzillaServer -> BugzillaSession
type BugzillaServer = Text

-- | A session for Bugzilla queries. Use <tt>anonymousSession</tt> and
--   <tt>loginSession</tt>, as appropriate, to create one.
data BugzillaSession
AnonymousSession :: BugzillaServer -> BugzillaSession
ApiKeySession :: BugzillaServer -> BugzillaApiKey -> BugzillaSession
newtype BugzillaApiKey
BugzillaApiKey :: Text -> BugzillaApiKey

-- | Searches Bugzilla and returns a list of <a>Bug</a>s. The
--   <a>SearchExpression</a> can be constructed using the operators in
--   <a>Web.Bugzilla.Search</a>.
searchBugs :: BugzillaSession -> SearchExpression -> IO [Bug]

-- | Similar to <a>searchBugs</a>, but return _all fields.
searchBugsAll :: BugzillaSession -> SearchExpression -> IO [Bug]

-- | Like <a>searchBugs</a>, but returns a list of <a>BugId</a>s. You can
--   retrieve the <a>Bug</a> for each <a>BugId</a> using <a>getBug</a>. The
--   combination of <a>searchBugs'</a> and <a>getBug</a> is much less
--   efficient than <a>searchBugs</a>. <a>searchBugs'</a> is suitable for
--   cases where you won't need to call <a>getBug</a> most of the time -
--   for example, polling to determine whether the set of bugs returned by
--   a query has changed.
searchBugs' :: BugzillaSession -> SearchExpression -> IO [BugId]

-- | Search Bugzilla and returns a limited number of results. You can call
--   this repeatedly and use <tt>offset</tt> to retrieve the results of a
--   large query incrementally. Note that most Bugzillas won't return all
--   of the results for a very large query by default, but you can request
--   this by calling <a>searchBugsWithLimit</a> with 0 for the limit.
searchBugsWithLimit :: BugzillaSession -> Int -> Int -> SearchExpression -> IO [Bug]

-- | Similar to <a>searchBugsWithLimit</a>, but return _all fields.
searchBugsAllWithLimit :: BugzillaSession -> Int -> Int -> SearchExpression -> IO [Bug]

-- | Like <a>searchBugsWithLimit</a>, but returns a list of <a>BugId</a>s.
--   See <a>searchBugs'</a> for more discussion.
searchBugsWithLimit' :: BugzillaSession -> Int -> Int -> SearchExpression -> IO [BugId]

-- | Retrieve a bug by bug number.
getBug :: BugzillaSession -> BugId -> IO (Maybe Bug)

-- | Retrieve all bug field by bug number
getBugAll :: BugzillaSession -> BugId -> IO (Maybe Bug)

-- | Retrieve a bug by attachment number.
getAttachment :: BugzillaSession -> AttachmentId -> IO (Maybe Attachment)

-- | Get all attachments for a bug.
getAttachments :: BugzillaSession -> BugId -> IO [Attachment]

-- | Get all comments for a bug.
getComments :: BugzillaSession -> BugId -> IO [Comment]

-- | Get the history for a bug.
getHistory :: BugzillaSession -> BugId -> IO History

-- | Search user names and emails using a substring search.
searchUsers :: BugzillaSession -> Text -> IO [User]

-- | Get a user by email.
getUser :: BugzillaSession -> UserEmail -> IO (Maybe User)

-- | Get a user by user ID.
getUserById :: BugzillaSession -> UserId -> IO (Maybe User)
newBzRequest :: BugzillaSession -> [Text] -> QueryText -> Request
sendBzRequest :: FromJSON a => Request -> IO a
intAsText :: Int -> Text
data () => Request
type BugId = Int
type AttachmentId = Int
type CommentId = Int
type UserId = Int
type EventId = Int
type FlagId = Int
type FlagType = Int
type UserEmail = Text

-- | A field which you can search by using <a>searchBugs</a> or track
--   changes to using <a>getHistory</a>. To get a human-readable name for a
--   field, use <a>fieldName</a>.
data Field a
[AliasField] :: Field [Text]
[AssignedToField] :: Field UserEmail
[AttachmentCreatorField] :: Field UserEmail
[AttachmentDataField] :: Field Text
[AttachmentDescriptionField] :: Field Text
[AttachmentFilenameField] :: Field Text
[AttachmentIsObsoleteField] :: Field Bool
[AttachmentIsPatchField] :: Field Bool
[AttachmentIsPrivateField] :: Field Bool
[AttachmentMimetypeField] :: Field Text
[BlocksField] :: Field Int
[BugIdField] :: Field Int
[CcField] :: Field UserEmail
[CcListAccessibleField] :: Field Bool
[ClassificationField] :: Field Text
[CommentField] :: Field Text
[CommentIsPrivateField] :: Field Text
[CommentTagsField] :: Field Text
[CommenterField] :: Field UserEmail
[ComponentField] :: Field [Text]
[ContentField] :: Field Text
[CreationDateField] :: Field UTCTime
[DaysElapsedField] :: Field Int
[DependsOnField] :: Field Int
[EverConfirmedField] :: Field Bool
[FlagRequesteeField] :: Field UserEmail
[FlagSetterField] :: Field UserEmail
[FlagsField] :: Field Text
[GroupField] :: Field Text
[KeywordsField] :: Field [Text]
[ChangedField] :: Field UTCTime
[CommentCountField] :: Field Int
[OperatingSystemField] :: Field Text
[HardwareField] :: Field Text
[PriorityField] :: Field Text
[ProductField] :: Field Text
[QaContactField] :: Field UserEmail
[ReporterField] :: Field UserEmail
[ReporterAccessibleField] :: Field Bool
[ResolutionField] :: Field Text
[RestrictCommentsField] :: Field Bool
[SeeAlsoField] :: Field Text
[SeverityField] :: Field Text
[StatusField] :: Field Text
[WhiteboardField] :: Field Text
[SummaryField] :: Field Text
[TagsField] :: Field Text
[TargetMilestoneField] :: Field Text
[TimeSinceAssigneeTouchedField] :: Field Int
[BugURLField] :: Field Text
[VersionField] :: Field Text
[VotesField] :: Field Text
[CustomField] :: Text -> Field Text

-- | A Bugzilla user.
data User
User :: !UserId -> Maybe UserEmail -> Text -> Text -> User
[userId] :: User -> !UserId
[userEmail] :: User -> Maybe UserEmail
[userName] :: User -> Text
[userRealName] :: User -> Text

-- | Flags, which may be set on an attachment or on a bug directly.
data Flag
Flag :: !FlagId -> !FlagType -> Text -> UserEmail -> Text -> UTCTime -> UTCTime -> Maybe UserEmail -> Flag
[flagId] :: Flag -> !FlagId
[flagTypeId] :: Flag -> !FlagType
[flagName] :: Flag -> Text
[flagSetter] :: Flag -> UserEmail
[flagStatus] :: Flag -> Text
[flagCreationDate] :: Flag -> UTCTime
[flagModificationDate] :: Flag -> UTCTime
[flagRequestee] :: Flag -> Maybe UserEmail

-- | A Bugzilla bug.
data Bug
Bug :: !BugId -> Maybe [Text] -> UserEmail -> User -> [BugId] -> [UserEmail] -> [User] -> Text -> [Text] -> UTCTime -> UserEmail -> User -> [BugId] -> Maybe BugId -> Maybe [Flag] -> [Text] -> Bool -> Bool -> Bool -> Bool -> [Text] -> UTCTime -> Text -> Text -> Text -> Text -> UserEmail -> Text -> Text -> Text -> Text -> Text -> Text -> [Text] -> Text -> KeyMap Text -> Maybe [ExternalBug] -> Bug
[bugId] :: Bug -> !BugId
[bugAlias] :: Bug -> Maybe [Text]
[bugAssignedTo] :: Bug -> UserEmail
[bugAssignedToDetail] :: Bug -> User
[bugBlocks] :: Bug -> [BugId]
[bugCc] :: Bug -> [UserEmail]
[bugCcDetail] :: Bug -> [User]
[bugClassification] :: Bug -> Text
[bugComponent] :: Bug -> [Text]
[bugCreationTime] :: Bug -> UTCTime
[bugCreator] :: Bug -> UserEmail
[bugCreatorDetail] :: Bug -> User
[bugDependsOn] :: Bug -> [BugId]
[bugDupeOf] :: Bug -> Maybe BugId
[bugFlags] :: Bug -> Maybe [Flag]
[bugGroups] :: Bug -> [Text]
[bugIsCcAccessible] :: Bug -> Bool
[bugIsConfirmed] :: Bug -> Bool
[bugIsCreatorAccessible] :: Bug -> Bool
[bugIsOpen] :: Bug -> Bool
[bugKeywords] :: Bug -> [Text]
[bugLastChangeTime] :: Bug -> UTCTime
[bugOpSys] :: Bug -> Text
[bugPlatform] :: Bug -> Text
[bugPriority] :: Bug -> Text
[bugProduct] :: Bug -> Text
[bugQaContact] :: Bug -> UserEmail
[bugResolution] :: Bug -> Text
[bugSeverity] :: Bug -> Text
[bugStatus] :: Bug -> Text
[bugSummary] :: Bug -> Text
[bugTargetMilestone] :: Bug -> Text
[bugUrl] :: Bug -> Text
[bugVersion] :: Bug -> [Text]
[bugWhiteboard] :: Bug -> Text
[bugCustomFields] :: Bug -> KeyMap Text
[bugExternalBugs] :: Bug -> Maybe [ExternalBug]

-- | An external bug.
data ExternalBug
ExternalBug :: Text -> Int -> Text -> Text -> Text -> Int -> ExternalType -> ExternalBug
[externalDescription] :: ExternalBug -> Text
[externalBzId] :: ExternalBug -> Int
[externalPriority] :: ExternalBug -> Text
[externalBugId] :: ExternalBug -> Text
[externalStatus] :: ExternalBug -> Text
[externalId] :: ExternalBug -> Int
[externalType] :: ExternalBug -> ExternalType

-- | An external bug type
data ExternalType
ExternalType :: Text -> Text -> Int -> Text -> Text -> ExternalType
[externalTypeDescription] :: ExternalType -> Text
[externalTypeUrl] :: ExternalType -> Text
[externalTypeId] :: ExternalType -> Int
[externalTypeType] :: ExternalType -> Text
[externalTypeFullUrl] :: ExternalType -> Text

-- | An attachment to a bug.
data Attachment
Attachment :: !AttachmentId -> !BugId -> Text -> Text -> UserEmail -> Bool -> Bool -> Bool -> [Flag] -> UTCTime -> UTCTime -> Text -> !Int -> Text -> Attachment
[attachmentId] :: Attachment -> !AttachmentId
[attachmentBugId] :: Attachment -> !BugId
[attachmentFileName] :: Attachment -> Text
[attachmentSummary] :: Attachment -> Text
[attachmentCreator] :: Attachment -> UserEmail
[attachmentIsPrivate] :: Attachment -> Bool
[attachmentIsObsolete] :: Attachment -> Bool
[attachmentIsPatch] :: Attachment -> Bool
[attachmentFlags] :: Attachment -> [Flag]
[attachmentCreationTime] :: Attachment -> UTCTime
[attachmentLastChangeTime] :: Attachment -> UTCTime
[attachmentContentType] :: Attachment -> Text
[attachmentSize] :: Attachment -> !Int
[attachmentData] :: Attachment -> Text

-- | A bug comment. To display these the way Bugzilla does, you'll need to
--   call <tt>getUser</tt> and use the <a>userRealName</a> for each user.
data Comment
Comment :: !CommentId -> !BugId -> Maybe AttachmentId -> !Int -> Text -> UserEmail -> UTCTime -> Bool -> Comment
[commentId] :: Comment -> !CommentId
[commentBugId] :: Comment -> !BugId
[commentAttachmentId] :: Comment -> Maybe AttachmentId
[commentCount] :: Comment -> !Int
[commentText] :: Comment -> Text
[commentCreator] :: Comment -> UserEmail
[commentCreationTime] :: Comment -> UTCTime
[commentIsPrivate] :: Comment -> Bool

-- | History information for a bug.
data History
History :: !BugId -> [HistoryEvent] -> History
[historyBugId] :: History -> !BugId
[historyEvents] :: History -> [HistoryEvent]

-- | An event in a bug's history.
data HistoryEvent
HistoryEvent :: EventId -> UTCTime -> UserEmail -> [Change] -> HistoryEvent

-- | A sequential event id.
[historyEventId] :: HistoryEvent -> EventId

-- | When the event occurred.
[historyEventTime] :: HistoryEvent -> UTCTime

-- | Which user was responsible.
[historyEventUser] :: HistoryEvent -> UserEmail

-- | All the changes which are part of this event.
[historyEventChanges] :: HistoryEvent -> [Change]

-- | A single change which is part of an event. Different constructors are
--   used according to the type of the field. The <a>Modification</a>
--   describes the value of the field before and after the change.
data Change
TextFieldChange :: Field Text -> Modification Text -> Change
ListFieldChange :: Field [Text] -> Modification [Text] -> Change
IntFieldChange :: Field Int -> Modification Int -> Change
TimeFieldChange :: Field UTCTime -> Modification UTCTime -> Change
BoolFieldChange :: Field Bool -> Modification Bool -> Change

-- | A description of how a field changed during a <a>HistoryEvent</a>.
data (Eq a, Show a) => Modification a
Modification :: Maybe a -> Maybe a -> Maybe AttachmentId -> Modification a
[modRemoved] :: Modification a -> Maybe a
[modAdded] :: Modification a -> Maybe a
[modAttachmentId] :: Modification a -> Maybe AttachmentId

-- | Provides a human-readable name for a <a>Field</a>.
fieldName :: Field a -> Text
data BugzillaException
BugzillaJSONParseError :: String -> BugzillaException
BugzillaAPIError :: Int -> String -> BugzillaException
BugzillaUnexpectedValue :: String -> BugzillaException


-- | A modified version of Web.Bugzilla.Search to support the list fields
--   in Red Hat's modified bugzilla API.
module Web.RedHatBugzilla.Search
(.==.) :: FieldType a => Field a -> a -> SearchExpression
infix 4 .==.
(./=.) :: FieldType a => Field a -> a -> SearchExpression
infix 4 ./=.
(.<.) :: FieldType a => Field a -> a -> SearchExpression
infix 4 .<.
(.<=.) :: FieldType a => Field a -> a -> SearchExpression
infix 4 .<=.
(.>.) :: FieldType a => Field a -> a -> SearchExpression
infix 4 .>.
(.>=.) :: FieldType a => Field a -> a -> SearchExpression
infix 4 .>=.
(.=~.) :: FieldType a => Field a -> a -> SearchExpression
(./=~.) :: FieldType a => Field a -> a -> SearchExpression
equalsAny :: FieldType a => Field a -> [a] -> SearchExpression
contains :: Field Text -> Text -> SearchExpression
containsCase :: Field Text -> Text -> SearchExpression
containsAny :: Field Text -> [Text] -> SearchExpression
containsAll :: Field Text -> [Text] -> SearchExpression
changedBefore :: FieldType a => Field a -> UTCTime -> SearchExpression
changedAfter :: FieldType a => Field a -> UTCTime -> SearchExpression

-- | Filter bug changed since UTCTime
changedSince :: UTCTime -> SearchExpression

-- | Filter bug changed until UTCTime
changedUntil :: UTCTime -> SearchExpression

-- | Filter bug changed in range
changedRange :: UTCTime -> UTCTime -> SearchExpression
changedFrom :: FieldType a => Field a -> a -> SearchExpression
changedTo :: FieldType a => Field a -> a -> SearchExpression
changedBy :: FieldType a => Field a -> UserEmail -> SearchExpression
contentMatches :: Text -> SearchExpression
isEmpty :: FieldType a => Field a -> SearchExpression
isNotEmpty :: FieldType a => Field a -> SearchExpression
(.&&.) :: SearchExpression -> SearchExpression -> SearchExpression
infixr 3 .&&.
(.||.) :: SearchExpression -> SearchExpression -> SearchExpression
infixr 2 .||.
not' :: SearchExpression -> SearchExpression

-- | A field which you can search by using <a>searchBugs</a> or track
--   changes to using <a>getHistory</a>. To get a human-readable name for a
--   field, use <a>fieldName</a>.
data Field a
[AliasField] :: Field [Text]
[AssignedToField] :: Field UserEmail
[AttachmentCreatorField] :: Field UserEmail
[AttachmentDataField] :: Field Text
[AttachmentDescriptionField] :: Field Text
[AttachmentFilenameField] :: Field Text
[AttachmentIsObsoleteField] :: Field Bool
[AttachmentIsPatchField] :: Field Bool
[AttachmentIsPrivateField] :: Field Bool
[AttachmentMimetypeField] :: Field Text
[BlocksField] :: Field Int
[BugIdField] :: Field Int
[CcField] :: Field UserEmail
[CcListAccessibleField] :: Field Bool
[ClassificationField] :: Field Text
[CommentField] :: Field Text
[CommentIsPrivateField] :: Field Text
[CommentTagsField] :: Field Text
[CommenterField] :: Field UserEmail
[ComponentField] :: Field [Text]
[ContentField] :: Field Text
[CreationDateField] :: Field UTCTime
[DaysElapsedField] :: Field Int
[DependsOnField] :: Field Int
[EverConfirmedField] :: Field Bool
[FlagRequesteeField] :: Field UserEmail
[FlagSetterField] :: Field UserEmail
[FlagsField] :: Field Text
[GroupField] :: Field Text
[KeywordsField] :: Field [Text]
[ChangedField] :: Field UTCTime
[CommentCountField] :: Field Int
[OperatingSystemField] :: Field Text
[HardwareField] :: Field Text
[PriorityField] :: Field Text
[ProductField] :: Field Text
[QaContactField] :: Field UserEmail
[ReporterField] :: Field UserEmail
[ReporterAccessibleField] :: Field Bool
[ResolutionField] :: Field Text
[RestrictCommentsField] :: Field Bool
[SeeAlsoField] :: Field Text
[SeverityField] :: Field Text
[StatusField] :: Field Text
[WhiteboardField] :: Field Text
[SummaryField] :: Field Text
[TagsField] :: Field Text
[TargetMilestoneField] :: Field Text
[TimeSinceAssigneeTouchedField] :: Field Int
[BugURLField] :: Field Text
[VersionField] :: Field Text
[VotesField] :: Field Text
[CustomField] :: Text -> Field Text

-- | A Boolean expression which can be used to query Bugzilla.
data SearchExpression
evalSearchExpr :: SearchExpression -> [QueryPart]
