Safe Haskell	None

Web.Bugzilla

Contents

Connecting to Bugzilla
Querying Bugzilla

Description

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:

 withBugzillaContext "bugzilla.example.org" $ \ctx -> do
   let session = anonymousSession ctx
       user = "me@example.org"
       query = AssignedToField .==. user .&&.
               FlagRequesteeField .==. user .&&.
               (FlagsField `contains` "review" .||. FlagsField `contains` "feedback")
   bugs <- searchBugs session query
   mapM_ (putStrLn . show . bugSummary) bugs

There's a somewhat more in-depth demo program included with the source code to this package.

Synopsis

Connecting to Bugzilla

newBugzillaContext :: BugzillaServer -> IO BugzillaContext Source

Creates a new BugzillaContext, suitable for connecting to the provided server. You should try to reuse BugzillaContexts whenever possible, because creating them is expensive.

closeBugzillaContext :: BugzillaContext -> IO ()Source

Closes the provided BugzillaContext. Using it afterwards is an error.

withBugzillaContext :: BugzillaServer -> (BugzillaContext -> IO a) -> IO aSource

Creates a BugzillaContext and ensures that it will be closed automatically, even if an exception is thrown.

loginSession :: BugzillaContext -> UserEmail -> Text -> IO (Maybe BugzillaSession)Source

Attempts to create a logged-in BugzillaSession using the provided username and password. Returns Nothing if login fails.

anonymousSession :: BugzillaContext -> BugzillaSession Source

Creates an anonymous BugzillaSession. Note that some content will be hidden by Bugzilla when you make queries in this state.

type BugzillaServer = Text Source

data BugzillaContext Source

Holds information about a BugzillaServer and manages outgoing connections. You can use newBugzillaContext or withBugzillaContext to create one.

data BugzillaSession Source

A session for Bugzilla queries. Use anonymousSession and loginSession, as appropriate, to create one.

Constructors

AnonymousSession BugzillaContext
LoginSession BugzillaContext BugzillaToken

data BugzillaToken Source

Instances

FromJSON BugzillaToken

Querying Bugzilla

searchBugs :: BugzillaSession -> SearchExpression -> IO [Bug]Source

Searches Bugzilla and returns a list of Bugs. The SearchExpression can be constructed conveniently using the operators in Web.Bugzilla.Search.

searchBugs' :: BugzillaSession -> SearchExpression -> IO [BugId]Source

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

searchBugsWithLimit Source

Arguments

:: BugzillaSession
-> Int	The maximum number of results to return.
-> Int	The offset from the first result to start from.
-> SearchExpression
-> IO [Bug]

Search Bugzilla and returns a limited number of results. You can call this repeatedly and use offset 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 searchBugsWithLimit with 0 for the limit.

searchBugsWithLimit'Source

Arguments

:: BugzillaSession
-> Int	The maximum number of results to return.
-> Int	The offset from the first result to start from.
-> SearchExpression
-> IO [BugId]

Like searchBugsWithLimit, but returns a list of BugIds. See searchBugs' for more discussion.

getBug :: BugzillaSession -> BugId -> IO (Maybe Bug)Source

Retrieve a bug by bug number.

getAttachment :: BugzillaSession -> AttachmentId -> IO (Maybe Attachment)Source

Retrieve a bug by attachment number.

getAttachments :: BugzillaSession -> BugId -> IO [Attachment]Source

Get all attachments for a bug.

getComments :: BugzillaSession -> BugId -> IO [Comment]Source

Get all comments for a bug.

getHistory :: BugzillaSession -> BugId -> IO History Source

Get the history for a bug.

searchUsers :: BugzillaSession -> Text -> IO [User]Source

Search user names and emails using a substring search.

getUser :: BugzillaSession -> UserEmail -> IO (Maybe User)Source

Get a user by email.

getUserById :: BugzillaSession -> UserId -> IO (Maybe User)Source

Get a user by user ID.

type BugId = Int Source

type AttachmentId = Int Source

type CommentId = Int Source

type UserId = Int Source

type EventId = Int Source

type FlagId = Int Source

type FlagType = Int Source

type UserEmail = Text Source

data Field a whereSource

A field which you can search by using searchBugs or track changes to using getHistory. To get a human-readable name for a field, use fieldName.

Constructors

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

Instances

Eq (Field a)
Show (Field a)

data User Source

A Bugzilla user.

Constructors

User
Fields userId :: !UserId userEmail :: Maybe UserEmail userName :: Text userRealName :: Text

Instances

Eq User
Ord User
Show User
FromJSON User

data Flag Source

Flags, which may be set on an attachment or on a bug directly.

Constructors

Flag
Fields flagId :: !FlagId flagTypeId :: !FlagType flagName :: Text flagSetter :: UserEmail flagStatus :: Text flagCreationDate :: UTCTime flagModificationDate :: UTCTime flagRequestee :: Maybe UserEmail

Instances

Eq Flag
Ord Flag
Show Flag
FromJSON Flag

data Bug Source

A Bugzilla bug.

Constructors

Bug

Fields

bugId :: !BugId
bugAlias :: Maybe Text
bugAssignedTo :: UserEmail
bugAssignedToDetail :: User
bugBlocks :: [BugId]
bugCc :: [UserEmail]
bugCcDetail :: [User]
bugClassification :: Text
bugComponent :: Text
bugCreationTime :: UTCTime
bugCreator :: UserEmail
bugCreatorDetail :: User
bugDependsOn :: [BugId]
bugDupeOf :: Maybe BugId
bugFlags :: [Flag]
bugGroups :: [Text]
bugIsCcAccessible :: Bool
bugIsConfirmed :: Bool
bugIsCreatorAccessible :: Bool
bugIsOpen :: Bool
bugKeywords :: [Text]
bugLastChangeTime :: UTCTime
bugOpSys :: Text
bugPlatform :: Text
bugPriority :: Text
bugProduct :: Text
bugQaContact :: UserEmail
bugResolution :: Text
bugSeeAlso :: [Text]
bugSeverity :: Text
bugStatus :: Text
bugSummary :: Text
bugTargetMilestone :: Text
bugUrl :: Text
bugVersion :: Text
bugWhiteboard :: Text
bugCustomFields :: HashMap Text Text

Instances

Eq Bug
Show Bug
FromJSON Bug

data Attachment Source

An attachment to a bug.

Constructors

Attachment

Fields

attachmentId :: !AttachmentId
attachmentBugId :: !BugId
attachmentFileName :: Text
attachmentSummary :: Text
attachmentCreator :: UserEmail
attachmentIsPrivate :: Bool
attachmentIsObsolete :: Bool
attachmentIsPatch :: Bool
attachmentFlags :: [Flag]
attachmentCreationTime :: UTCTime
attachmentLastChangeTime :: UTCTime
attachmentContentType :: Text
attachmentSize :: !Int
attachmentData :: Text

Instances

Eq Attachment
Show Attachment
FromJSON Attachment

data Comment Source

A bug comment. To display these the way Bugzilla does, you'll need to call getUser and use the userRealName for each user.

Constructors

Comment
Fields commentId :: !CommentId commentBugId :: !BugId commentAttachmentId :: Maybe AttachmentId commentCount :: !Int commentText :: Text commentCreator :: UserEmail commentCreationTime :: UTCTime commentIsPrivate :: Bool

Instances

Eq Comment
Show Comment
FromJSON Comment

data History Source

History information for a bug.

Constructors

History
Fields historyBugId :: !BugId historyEvents :: [HistoryEvent]

Instances

Eq History
Show History
FromJSON History

data HistoryEvent Source

An event in a bug's history.

Constructors

HistoryEvent
Fields historyEventId :: EventId A sequential event id. historyEventTime :: UTCTime When the event occurred. historyEventUser :: UserEmail Which user was responsible. historyEventChanges :: [Change] All the changes which are part of this event.

Instances

Eq HistoryEvent
Show HistoryEvent
FromJSON HistoryEvent

data Change Source

A single change which is part of an event. Different constructors are used according to the type of the field. The Modification describes the value of the field before and after the change.

Constructors

TextFieldChange (Field Text) (Modification Text)
ListFieldChange (Field [Text]) (Modification [Text])
IntFieldChange (Field Int) (Modification Int)
TimeFieldChange (Field UTCTime) (Modification UTCTime)
BoolFieldChange (Field Bool) (Modification Bool)

Instances

Eq Change
Show Change
FromJSON Change

data (Eq a, Show a) => Modification a Source

A description of how a field changed during a HistoryEvent.

Constructors

Modification
Fields modRemoved :: Maybe a modAdded :: Maybe a modAttachmentId :: Maybe AttachmentId

Instances

(Eq a, Show a) => Eq (Modification a)
(Eq a, Show a) => Show (Modification a)

fieldName :: Field a -> Text Source

Provides a human-readable name for a Field.

data BugzillaException Source

Constructors

BugzillaJSONParseError String
BugzillaAPIError Int String
BugzillaUnexpectedValue String

Instances

Show BugzillaException
Typeable BugzillaException
Exception BugzillaException