-- 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, typesafe interface
--   to querying Bugzilla from Haskell.
@package bugzilla
@version 0.2.1.1

module Web.Bugzilla.Search
(.==.) :: FieldType a => Field a -> a -> SearchExpression
(./=.) :: FieldType a => Field a -> a -> SearchExpression
(.<.) :: FieldType a => Field a -> a -> SearchExpression
(.<=.) :: FieldType a => Field a -> a -> SearchExpression
(.>.) :: FieldType a => Field a -> a -> SearchExpression
(.>=.) :: FieldType a => Field a -> a -> SearchExpression
(.=~.) :: 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
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
(.&&.) :: SearchExpression -> SearchExpression -> SearchExpression
(.||.) :: SearchExpression -> SearchExpression -> SearchExpression
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


-- | This package is designed to provide an easy-to-use, typesafe interface
--   to querying Bugzilla from Haskell.
--   
--   A very simple program using this package might look like this:
--   
--   <pre>
--   withBugzillaContext "bugzilla.example.org" $ \ctx -&gt; do
--     let session = anonymousSession ctx
--         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 somewhat more in-depth demo program included with the source
--   code to this package.
module Web.Bugzilla

-- | Creates a new <a>BugzillaContext</a>, suitable for connecting to the
--   provided server. You should try to reuse <a>BugzillaContext</a>s
--   whenever possible, because creating them is expensive.
newBugzillaContext :: BugzillaServer -> IO BugzillaContext

-- | Closes the provided <a>BugzillaContext</a>. Using it afterwards is an
--   error.
closeBugzillaContext :: BugzillaContext -> IO ()

-- | Creates a <a>BugzillaContext</a> and ensures that it will be closed
--   automatically, even if an exception is thrown.
withBugzillaContext :: BugzillaServer -> (BugzillaContext -> IO a) -> IO a

-- | Attempts to create a logged-in <a>BugzillaSession</a> using the
--   provided username and password. Returns <a>Nothing</a> if login fails.
loginSession :: BugzillaContext -> UserEmail -> Text -> IO (Maybe BugzillaSession)

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

-- | Holds information about a <a>BugzillaServer</a> and manages outgoing
--   connections. You can use <tt>newBugzillaContext</tt> or
--   <tt>withBugzillaContext</tt> to create one.
data BugzillaContext

-- | A session for Bugzilla queries. Use <tt>anonymousSession</tt> and
--   <tt>loginSession</tt>, as appropriate, to create one.
data BugzillaSession
AnonymousSession :: BugzillaContext -> BugzillaSession
LoginSession :: BugzillaContext -> BugzillaToken -> BugzillaSession
data BugzillaToken

-- | Searches Bugzilla and returns a list of <a>Bug</a>s. The
--   <a>SearchExpression</a> can be constructed conveniently using the
--   operators in <a>Web.Bugzilla.Search</a>.
searchBugs :: 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]

-- | 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 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)
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 -> [Flag] -> [Text] -> Bool -> Bool -> Bool -> Bool -> [Text] -> UTCTime -> Text -> Text -> Text -> Text -> UserEmail -> Text -> [Text] -> Text -> Text -> Text -> Text -> Text -> Text -> Text -> HashMap Text Text -> 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 -> [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
bugSeeAlso :: 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 -> HashMap Text 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