     [file version.texi not included]

Copyright © 2017, 2018, 2019 Ricardo Wurmus

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Guile Debbugs
*************

This document describes Guile Debbugs version VERSION, the Guile bindings for the Debbugs bug tracker's SOAP service.

Introduction
************

This package provides a Guile library to communicate with a Debbugs bug tracker's SOAP service.

Here is a short Guile REPL session demonstrating some of the things you can do with this library:

     ,use (debbugs)
     ,use (email email)
     (soap-invoke %debian newest-bugs 3)
     $1 = (880882 880881 880880)
     (soap-invoke %debian get-status $1)
     $2 = (#<bug 880882 ...> #<bug 880881 ...> #<bug 880880 ...>)
     (map bug-originator $2)
     $3 = ("ringo" "paul" "george")
     (soap-invoke %debian get-bug-log (car $1))
     $4 = (#<email 1 ...> #<email 2 ...> #<email 3 ...>)
     (email-body (car $4))
     $5 = "Hello world! ..."

For documentation of the supported operations see Operations.

Installation
************

Guile Debbugs uses the GNU build system.  To install Guile Debbugs from a release tarball just unpack it and run the usual commands:

     ./configure
     make
     make install

If you want to build the sources from the source repository you need to bootstrap the build system first.  Run the bootstrap.sh script first and then perform the above steps.

Programming Interface
*********************

Guile Debbugs provides rudimentary procedures to make requests to a SOAP service, and it defines operations that can be invoked on it.  It does not provide a full implementation of SOAP and it has only been tested with Debbugs.

The following modules are included:

(debbugs base64)
     Procedures for decoding and encoding base64 strings.

(debbugs bug)
     Procedures to parse bugs as returned by Debbugs, and to access their properties.

(debbugs email)
     Procedures to parse emails as returned by Debbugs.

(debbugs operations)
     Implementations of SOAP operations supported by Debbugs.

(debbugs rfc822)
     Parser for email headers.

(debbugs soap)
     Procedures for talking with SOAP services.

The modules (debbugs rfc822) and (debbugs base64) won't be documented here as they are primarily for internal use.

SOAP helpers
============

The module (debbugs soap) provides procedures to invoke operations on a SOAP service, to retrieve responses, and to convert those responses to Scheme values.

 -- Scheme Procedure: soap-request BODY [CALLBACK]
     Return a <soap-request>, which combines a SOAP request envelope enclosing the SXML expression BODY and the single-argument response handler procedure CALLBACK.  The response handler is to be called on the SOAP response SXML.  When no handler is provided the response expression is not processed.

 -- Scheme Procedure: soap-request? RECORD
     Return #t when RECORD is a <soap-request> object.

 -- Scheme Procedure: soap-request-body REQUEST
     Return the SXML body of the SOAP request REQUEST, a <soap-request> object.

 -- Scheme Procedure: soap-request-callback REQUEST
     Return the response handler procedure callback of the SOAP request REQUEST, a <soap-request> object.

 -- Scheme Procedure: soap-invoke URI OP [ARGS ...]
     Invoke the SOAP operation OP, a <soap-request> object, with all provided arguments ARGS on the SOAP service at the provided URI URI.  Return the response body after processing it with the handler procedure that is part of OP.

 -- Scheme Procedure: soap->scheme SXML [PLAIN]
     Recursively convert a SOAP SXML expression SXML for a named value to a Scheme value.  If PLAIN is #T return only the value, otherwise return a pair of a name and the value.

Operations
==========

This module implements SOAP operations that can be used with a Debbugs SOAP service.  Each of the procedures in this module returns a <soap-request> value, i.e. a message in SXML format and an optional response handler procedure.

 -- Scheme Procedure: newest-bugs AMOUNT
     This operation returns the identifiers of the newest bugs as a list of numbers.  The integer AMOUNT must be specified to limit the number of bugs returned by Debbugs.

 -- Scheme Procedure: get-status BUG-IDS
     This operation returns <bug> records containing the details for the bugs identified by BUG-IDS, a list of bug numbers.  See Bug helpers for procedures that can be used on the return values.

 -- Scheme Procedure: get-bugs ARGS
     This operation returns bug numbers for bugs that match the conditions given by ARGS, an alist of key-value pairs.  Possible keys are package, submitter, maint, src, severity, status, tag, owner, bugs, affects, and archive.

     All keys and values must be provided as strings.  Valid values for status are the strings done, forwarded, and open.  For archive the valid values are either the string both, the string 1 (meaning ``archived''), or the string 0 (meaning ``not archived'').

 -- Scheme Procedure: get-bug-log BUG-ID
     This operation requests all emails associated with the bug identified by BUG-ID.  All emails are returned as <email> values. See Email helpers for procedures that can be used on the return values.

 -- Scheme Procedure: get-usertag EMAIL
     This operation returns an association list of tag names (as strings) to lists of bug numbers for all bugs that have been tagged by EMAIL, a string holding an email address.

 -- Scheme Procedure: search-est PHRASE [SKIP] [MAX] [ATTRIBUTES]
     Return the result of a full text search according to the string PHRASE.  When SKIP is provided, the given number of hits will be skipped; this is useful for paged results.  At most MAX results are returned when MAX is provided.  The number of returned results is always limited by the absolute maximum returned by the Debbugs server.

     The list of ATTRIBUTES can be used to limit the search.  Each attribute element is a list of three items: the attribute symbol, a value for that attribute, and an operator.  Here is an example of an attribute list that limits the search to the packages ``guix'' and ``guix-patches'' by matching the ``package'' attribute exactly against one of the strings:

          '((package string-prefix "guix"))

     Note that this operation may not be supported by all Debbugs instances.

     The following attributes are recognized:

     @title
          The subject of a message.  Note that in spite of this attribute's name this is not necessarily the title of the bug.

     severity
          The bug severity, such as ``minor'', ``normal'', ``important'', or ``serious''.

     submitter
          The name and email address of the bug submitter.

     @author
          The message author.  (Not the submitter of the first bug message.)

     subject
          The bug title, not the message subject.  (I know that this is confusing.)

     status
          The bug status.  At least the GNU instance of Debbugs does not seem to record a bug status at all, so this will always be the empty string.

     @cdate
          The message date.

     package
          The name of the package to which the bug applies, such as ``emacs'' or ``guix''.q

     tags
          Tags that have been added to a message, such as ``patch'' for messages containing patches.

     date
          The bug submission date.

     The following operators for numeric arguments are available:

     =
          Numeric equality.

     /=
          Numeric inequality.

     >
          The number must be greater than the given value.

     >=
          The number must be greater than or equal to the given value.

     <
          The number must be less than the given value.

     <=
          The number must be less than or equal to the given value.

     ><
          The number must be between the two numeric arguments.

     The following operators for string arguments are available:

     string=
          String equality.

     string-not-equal
          String inequality.

     string-contains
          The item must include the given string.

     string-prefix
          The item must begin with the given string.

     string-suffix
          The item must end with the given string.

     string-and
          The matched item includes all tokens.

     string-or
          The matched item includes at least one of the space-separated strings.

     string-or-equal
          The matched item is equal to at least one of the space-separated tokens.

     string-regex
          The item must match the provided regular expression.

Bug helpers
===========

Being a bug tracker, Debbugs tracks bugs.  Bugs are created and modified through email messages, and Debbugs reveals the internal state that is affected by these messages through the get-status operation.  The Guile bindings parse the returned state to a value of the record type <bug>.

 -- Scheme Procedure: soap-bug->bug BUG-ITEM
     This procedure takes an SXML expression BUG-ITEM, which describes the state of a single bug, and returns a record of type <bug>. It is used to parse the SOAP response of the get-status operation.  This is the only way to obtain a value of type <bug>.

 -- Scheme Procedure: bug? RECORD
     Return #t when RECORD is a <bug> object.

Debbugs records a large number of properties for each bug.  For each of these properties Guile Debbugs provides an accessor procedure, which returns the parsed value.  In the table below the properties are described.  Each property can be accessed with a procedure named bug-PROPERTY, where PROPERTY is the property name.

package
     The package to which this bug report applies.

severity
     The severity of the bug report.

num
     The bug number, a unique numeric identifier.

subject
     The current title of the bug report.

summary
     An arbitrary summary text.

msgid
     The message ID of the email that caused the bug to be registered.

originator
     The email address of the submitter of the bug report.

owner
     The email address of the person assigned to fix this bug.

done
     The email address of the person who closed the bug.

archived
     A boolean indicating whether the bug is archived.

unarchived
     A boolean indicating whether the bug has been unarchived and can be archived again.

pending
     Either the string ``pending'' or the string ``done''.

blocks
     A list of bug numbers for bugs that are blocked by this bug.

blockedby
     A list of bug numbers of bugs blocking this bug.

mergedwith
     A list of bug numbers for bugs that have been merged with this bug.

affects
     A list of package names that are affected by this bug.

date
     The date and time when this bug was reported.

log-modified
     The date and time when this bug was last modified.

last-modified
     Honestly, I don't know what the difference is compared to log-modified.

forwarded
     A URL or an email address.

fixed-versions
     A list of version strings for versions of the affected package in which the bug has been fixed.

found-versions
     A list of version strings for versions of the package in which the bug has been found.

source
     Source package of the bug report.

outlook
     Unknown.

tags
     A list of tag strings.

found
     Apparantly this field is not fully implemented in Debbugs yet.

location
     In the Debian version of Debbugs this will always be ``db-h'' or ``archive''.

Email helpers
=============

Debbugs is an email-driven bug tracker---bug reports are created by sending email and their state is updated by sending control messages. Every bug has an associated message log, an ordered list of user-sent emails and internal control messages.  The (debbugs email) module provides the record type <email> that represents those email messages.

 -- Scheme Procedure: soap-email->email EMAIL-ITEM
     This procedure takes an SXML expression EMAIL-ITEM, which describes a single email with headers, body, message number, and attachments, and returns a record of type <email>.  It is used to parse the SOAP response of the get-bug-log operation.  This is the only way to obtain a value of type <email>.

     It parses the email headers to an association list of headers to values. It does not process other properties.

 -- Scheme Procedure: email? RECORD
     Return #t when RECORD is an object of type <email>.

An email consists of headers, a body, a message number, and an optional list of attachments.  This module provides accessor procedures to extract these values from a given object of type <email>.

 -- Scheme Procedure: email-headers EMAIL
     Return the parsed RFC822 headers of the EMAIL as an association list.  The headers are parsed when the object is first created.

 -- Scheme Procedure: email-body EMAIL
     Return the email's body as a string.

 -- Scheme Procedure: email-msg-num EMAIL
     Return the email's message number.  Emails in a bug log can be sorted using the message number.

 -- Scheme Procedure: email-attachments EMAIL
     Return a list of attachments or the empty list if there are none.

Acknowledgments
***************

Thanks to the following people who contributed to Guile-Debbugs through bug reports or patches:

  * Your Name Here nobody@yet

Also thanks to the people who reviewed Guile Debbugs for hosting on Savannah and for joining the GNU project.

  * Ineiev ineiev@gnu.org

  * Mike Gerwitz mtg@gnu.org

Thank you.

GNU Free Documentation License
******************************

     [file fdl-1.3.texi not included]