lib: bump SONAME

Based on discussions with amdragon, tschwinge, and others on IRC, I concluded that

1) symbol versioning was probably overkill for libnotmuch
2) It was also probably GNU ld specific
3) Most importantly, nobody could tell me on short notice how exactly it works.

So since the change to the notmuch_database_find_message breaks the
previous ABI, we need to bump the SONAME.

ruby: Fix macros, use quoting

Fix Data_Get_Notmuch_* macro definitions broken by prev. commit
Adequate quoting for Data_Get_Notmuch_* macros
Remove duplicated RSTRING_PTR() macros, move it to defs.h

ruby: Really add wrappers for database_find_message*

Commit 898613116db746aa0f915ae43da8aba28545203d only added wrapper
functions but did not register them. Register the functions in module's
initialization function.

ruby: be consistent with notmuch's coding style

No functional change, just indentation

ruby: Add wrappers for database_find_message*

Two new wrappers:
Notmuch::Database.find_message(id) => Notmuch::Message or nil
Notmuch::Database.find_message_by_filename(path) => Notmuch::Message or nil

Merge remote-tracking branch 'alip/find_message-v3'

lib: make find_message{,by_filename) report errors

Previously, the functions notmuch_database_find_message() and
notmuch_database_find_message_by_filename() functions did not properly
report error condition to the library user.

For more information, read the thread on the notmuch mailing list
starting with my mail "id:871uv2unfd.fsf@gmail.com"

Make these functions accept a pointer to 'notmuch_message_t' as argument
and return notmuch_status_t which may be used to check for any error
condition.

restore: Modify for the new notmuch_database_find_message()
new: Modify for the new notmuch_database_find_message_by_filename()

lib: destroy message object after message removal

notmuch_database_remove_message() must call notmuch_message_destroy()
once it is done handling message removal.

python: fix Message.get_filenames()

Previously, the Filenames generator only yielded *one* filename before
returning, making Message.get_filenames() behave as Message.get_filename(). This
commit fixes this incorrect behavior: now the generator yields all the
filenames, as expected.

python: rework creating of Subclasses

Add some smart magic, so that when we invoke a
NotmuchError(STATUSVALUE), a nicely derived subclass is created, e.g. a
OutOfMemoryError. This way users can easily distinguish between error
types, while still catching NotmuchError.

I have tested this, and hope it works for others too.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

python: provide more exception classes

To make the exception handling more effective in code using the
python bindings it is necessary to differentiate between the
different kind of failures.

Add an exception class for each status code and add a decode
classmethod to the NotmuchError class that acts as a factory.

Import the new classes in __init__.py so they can be easily
imported by anyone.

Patch modifed by Sebastian Spaeth.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>
Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de>

python: fix docstring of Message.get_header()

Update the docstring from notmuch.h.

Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de>

python: Add new functions in API documentation

Add documentation for the three new functions and add in which version
they have been added.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

python: Improve code documentation

1) Fix added .gitignore from commit dc8a1745 to work on the docs folder
2) Improve in-code developer documentation to produce better
   sphinx-generated documentation. No code changes.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

NEWS: Note implementation bug for python binding

Make note that find_message_by_name currently crashes the python process
if the Database is READ-ONLY. This should be fixed in the underlying
libnotmuch.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

NEWS: Update with python binding news

List major changes.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

properly raise exceptions in python bindings

There are various locations where exceptions are constructed but
not raised. This patch adds the necessary raise statements.

Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de>

python: raise a more specific error in Messages.print_messages

Raising Exception is considered bad since the only way to catch
it is to do 'except Exception'. Raising a TypeError is more
appropriate.

Since the format parameter has already been validated, checking
it again is not necessary. Simplify this conditional.

Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de>

python: rename _verify_dir_initialized to _assert_dir_is_initialized

Rename the function to clarify its effect and remove all the comments
accompanying each call to the function.

Modified by Sebastian Spaeth to apply cleanly again and remove some
blank lines.

Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de>
Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

python: rename _verify_initialized_db to _assert_db_is_initialized

Rename the function to clarify its effect and remove all the comments
accompanying each call to the function.

Modified slightly by Sebastian Spaeth to catch all new instances and
remove some blank lines too.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>
Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de>

python: fix NotmuchError.__str__ if status == None

Passing None to STATUS.status2str raises an ArgumentError. Add a
check for this case and provide a generic message.

Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de>

python: add status and message attributes to NotmuchError

Providing exception objects with meaningful attribute names
is much nicer than using e.args[].

Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de>

python: add a .gitignore file and refine the toplevel one

The line 'notmuch' in the toplevel .gitignore file is to broad
and matches bindings/python/notmuch making it cumbersome to
git-add files within that directory.

Refine the toplevel file to only match the generated notmuch
executable and add a more specialized .gitignore file to the
python directory.

Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de>

python: add begin|end_atomic bindings

* Add UNBALANCED_ATOMIC status code
  Catch up with the notmuch status codes, and add the UNBALANCED_ATOMIC
  one.
* Add the begin_atomic and end_atomic calls to libnotmuch

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

python: Add database_find_message_by_filename bindings

Add it :-)

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

NEWS: add item for python bindings.

Just the one unicode related change this release.

NEWS: add item for Ruby bindings.

This is based on a quick scan of git log.

NEWS: start release notes for 0.9

Thanks to Austin Clements for providing these notes, and the patches
they describe.

debian: add brief summary of changes since 0.8

debian: build-depend on gdb

This is needed to enable the atomicity tests at build time.

test/atomicity: redirect output from "which"

Without redirection, this produced some slightly confusing output in
case gdb was present.

debian: close bug 642240

The bug was really closed by the commit that updated the dependency,
of course.

test: make atomicity setup conditional on gdb being present.

The setup is useless if gdb is not present, so it doesn't hurt to skip
it.  The diff here is huge, but the commit is really just moving most
of the script inside the initial if, and adding an else block to print
a warning.

lib: bump library minor version because of new symbols.

This bump is because of the new symbols introduced by the atomicity
patches.

debian: set versioned dependency on notmuch for notmuch-emacs

As long as we have no version information in the json output, this
seems like the only possible way of ensuring that the emacs client
code understands the output from the command line tool notmuch.

version: bump to 0.9~rc1

This version number change should not be taken as definitive, rather
refer to the signed tag.

debian: changlog stanza for release candidate

debian: new symbols for atomicity api

There are three new symbols in libnotmuch. In addition to notmuch_{begin,end)_atomic,
notmuch_database_find_message_by_filename was exposed.

lib: Improve notmuch_database_{add,remove}_message documentation.

State up front that these functions may add a filename to an existing
message or remove only a filename (and not the message), respectively.
Previously, this key information was buried in return value
documentation or in "notes", which made it seem secondary to these
functions' semantics.

new: Wrap adding and removing messages in atomic sections.

This addresses atomicity of tag synchronization, the last atomicity
problems in notmuch new.  Each message add or remove is wrapped in its
own atomic section, so interrupting notmuch new doesn't lose progress.

new: Synchronize maildir flags eagerly.

Because flag synchronization is stateless, it can be performed at any
time as long as it's guaranteed to be performed after any change to a
message's filename list.  Take advantage of this to synchronize tags
immediately after a filename is added or removed.

This does not yet make adding or removing a message atomic, but it is
a big step toward atomicity because it reduces the window where the
database tags are inconsistent from nearly the entire notmuch-new to
just around when the message is added or removed.

new: Cleanup.  De-duplicate file name removal code.

Previously, file name removal was implemented identically in two
places.  Now it's captured in one function.

This is important because file name removal is about to get slightly
more complicated with eager tag synchronization and correct removal
atomicity.

new: Cleanup.  Put removed/renamed message count in add_files_state_t.

Previously, pointers to these variables were passed around
individually.  This was okay when only one function needed them, but
we're about to need them in a few more places.

lib: Wrap notmuch_database_add_message in an atomic section.

Adding a message may involve changes to multiple database documents,
and thus needs to be done in a transaction.  This makes add_message
(and, I think, the whole library) atomicity-safe: library callers only
needs to use atomic sections if they needs atomicity across multiple
library calls.

lib: Add an API to find a message by filename.

notmuch_database_find_message_by_filename is mostly stolen from
notmuch_database_remove_message, so this patch also vastly simplfies
the latter using the former.

This API is also useful in its own right and will be used in a later
patch for eager maildir flag synchronization.

ruby: New exception Notmuch::UnbalancedAtomicError

This exception wraps NOTMUCH_STATUS_UNBALANCED_ATOMIC which was added
with the commit e59cc0031fbf84f49e32dedb9927f427d2c49309.

ruby: Wrap notmuch_database_{begin,end}_atomic

Adding ruby wrappers for functions:
- notmuch_database_begin_atomic()
- notmuch_database_end_atomic()
added by 957f1ba3fc1d737887029ff1787fc6bea94de00b

New functions:
Notmuch::Database.begin_atomic()
Notmuch::Database.end_atomic()

ruby: Rename destroy to destroy!

According to the common Ruby function naming convention, potentially
dangerous functions or functions which operate on the object itself are
suffixed with an exclamation mark. Both of these are true for object
destroying functions.

The following modules are affected:
- Notmuch::Directory
- Notmuch::FileNames
- Notmuch::Query
- Notmuch::Threads
- Notmuch::Thread
- Notmuch::Messages
- Notmuch::Message
- Notmuch::Tags

lib: Remove message document directly after removing the last file name.

Previously, notmuch_database_remove_message would remove the message
file name, sync the change to the message document, re-find the
message document, and then delete it if there were no more file names.
An interruption after sync'ing would result in a file-name-less,
permanently un-removable zombie message that would produce errors and
odd results in searches.  We could wrap this in an atomic section, but
it's much simpler to eliminate the round-about approach and just
delete the message document instead of sync'ing it if we removed the
last filename.

lib: Indicate if there are more filenames after removal.

Make _notmuch_message_remove_filename return
NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID if the message has more filenames
and fix callers to handle this.

lib: Add support for nested atomic sections.

notmuch_database_t now keeps a nesting count and we only start a
transaction or commit for the outermost atomic section.

Introduces a new error, NOTMUCH_STATUS_UNBALANCED_ATOMIC.

lib: Add notmuch_database_{begin,end}_atomic.

These operations translate into non-flushed Xapian transactions,
allowing arbitrary groups of database operations to be performed
atomically.

new: Defer updating directory mtimes until the end.

Previously, if notmuch new were interrupted between updating the
directory mtime and handling removals from that directory, a
subsequent notmuch new would not handle those removals until something
else changed in that directory.  This defers recording the updated
mtime until after removals are handled to eliminate this problem.

python: Ensure that we pass utf-8 encoded string to libnotmuch

If we use unicode objects, libnotmuch would not cope with null bytes in
the byte array, so we need to make sure they are nicely formatted as
utf-8.

Introduce a helper function _str which does this throughout the code.

Patch slightly modified by Sebastian Spaeth.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

new: Don't lose messages on SIGINT.

Previously, message removals were always performed, even after a
SIGINT.  As a result, when a message was moved from one folder to
another, a SIGINT between processing the directory the message was
removed from and processing the directory it was added to would result
in notmuch removing that message from the database.

test: use test_expect_equal_file in atomicity

The documentation claims this is more robust, and it seems to work
fine to switch to the _file variant.

test: Convert atomicity test to use test_subtest_known_broken

This is required because test_expect_equal_failure went away.

test: Test atomicity of notmuch new.

This tests notmuch new's ability to recover from arbitrary stopping
failures.  It interrupts notmuch new after every database commit and,
on every resulting database snapshot, re-runs notmuch new to
completion and checks that the final database state is invariant.

lib: Add missing status check in _notmuch_message_remove_filename.

Previously, this function would synchronize the folder list even if
removing the file name failed.  Now it returns immediately if removing
the file name fails.

test: Report test failures from test_expect_*

This makes test_expect_* return non-zero if the test fails, so the
caller can make decisions based on this, such as setting test
prerequisites.

test: Fix message when skipping test_expect_equal* tests

For these types of tests, the test name is previously recorded in a
variable, not passed to the test function, so pass this variable to
test_skip.

test: reset test_subtest_known_broken_ after each success/failure.

This means that test_subtest_known_broken needs to be called before
every known broken subtest, which is no different than what is
documented for the test_begin_subtest case.

The assumption is that every test ends up calling either skipping,
calling test_ok_ or test_failure_ and and the latter in turn delegate
to the known_broken versions in the case where
test_subtest_known_broken_ is set.

Add missing call to g_type_init()

The Glib docs state "Prior to any use of the type system, g_type_init() has to
be called".[1] To not do so can lead to segfaults.  The g_type system is
currently used by various "filters" that operate on uuencoded text, message
headers, etc.

[1] http://developer.gnome.org/gobject/2.28/gobject-Type-Information.html#g-type-init

test: mark multipart rfc822 part test as broken

Using the new test_subtest_known_broken support thanks to Dmitry
Kurochkin.  This makes the output less scary until we can fix the
underlying problems.

test: remove documentation for test_expect_equal_failure.

The actual function was deleted in commit 4cc67276

test: add emacs test for hiding a message following an HTML part

Human-friendly scenario:

* open a thread where a message which ends with an HTML part is
  followed by another message

* make the first message visible

* goto the beginning of the second message (first line, first colon)

* hit "RET"

Result: nothing happens except for "No URL at point" message

Expected result: the second message is shown/hidden

The root cause is that the HTML part has `keymap' text property set.
In particular, "RET" is bound to visit a URL at point.  The problem is
that `keymap' property affects the next character following the region
it is set to (see elisp manual [1]).  Hence, the first character of
the next message has a keymap inherited from the HTML part.

[1] http://www.gnu.org/software/emacs/elisp/html_node/Special-Properties.html

test: improve known broken tests support

There is existing support for broken tests.  But it is not convenient
to use.  The primary issue is that we have to maintain a set of
test_expect_*_failure functions which are equivalent to the normal
test_expect_* counterparts except for what functions are called for
result reporting.  The patch adds test_subtest_known_broken function
which marks a subset as broken, making the normal test_expect_*
functions behave as test_expect_*_failure.  All test_expect_*_failure
functions are removed.  Test_known_broken_failure_ is changed to
format details the same way as test_failure_ does.

Another benefit of this change is that the diff when a broken test is
fixed would be small and nice.

Documentation is updated accordingly.

test: update documentation for test_emacs in test/README

Update test_emacs documentation in test/README according to the latest
changes in emacs tests.  Move the note regarding setting variables
from test/emacs to test/README.

Merge branch 'release'

update date in NEWS to better approximate real release date for 0.8

debian: update changelog for 0.8

update versions for release 0.8

See commit 6979b65 for more discussion.

NEWS: add blurb for python bindings changes

add news item for ruby

NEWS: add item for build system fixes

Sed was POSIXed and use of nm dumbed down, replaced by awk hackery.

Do not attempt to output part raw if part is not GMimePart.

This was a minor oversite in checking of part type when outputing
content raw.  This was causing gmime was to throw an exception to
stderr.

Unfortunately the gmime exception was not being caught by notmuch, or
the test suite.  I'm not sure if notmuch should have done anything in
this case, but certainly the test suite should be capable of detecting
that something unexpected was output to stderr.

update versions for release candidate

we now have three files to keep in sync. That seems wrong, but I guess
we will live with it for now.

The main problem is that the python code is distributed separately, so
it can't get the version from 'version'.

The choice ~rcX is for convenience with debian versioning.

Add NEWS item output improvements to rfc822 part handling.

emacs: Improve support for message/rfc822 parts.

The insert-part-message/rfc822 function is overhauled to properly
processes the new formatting of message/rfc822 parts.  The json output
for message parts now includes "headers" and "body" fields, which are
now parsed and output appropriately.

Improve handling of message/rfc822 parts by adding a new header_message_part function to the formating structure.

This new function takes a GMimeMessage as input, and outputs the
formatted headers.  This allows for message/rfc822 parts to be
formatted on output in a similar way to full messages (see previous
patch that overhauls the multipart test for more info).

test: overhaul multipart test to test for improved message/rfc822 handling

The main goal of this overhaul is to define how message/rfc822 parts
should be handled.  message/rfc822 parts should be output in a similar
fashion to the outer message, including some subset of the rfc822
headers.  The following decisions about formatting of message/rfc822
parts were made:

The format and content of message/rfc822 parts shall be as similar as
possible to that of full messages.  In particular, for formatted
outputs, the "content" of rfc822 part output should include "headers"
and "body" fields).

The "body" field shall include the body of the message.

The "headers" field shall include the following headers, since these
are the ones available from the GMimeMessage:

  "From"
  "To"
  "Cc"
  "Subject"
  "Date"

However, for the case of --format=raw the raw rfc822 should be output,
including all headers.

A subset of relevant headers shall be output in reply.

The test embedded rfc822 message is also modified to be itself
multipart, so we can more fully test how all sub parts of the message
part are output.

Note added by Committer:

Currently, expect one test (--format=raw --part=3, rfc822 part) to fail.

Merge branch 'master' of ssh://notmuchmail.org/git/notmuch

python: Make Database take unicode paths

Decode and Encode from/to unicode objects as required to be able to take
unicode path names. Previously we would error out when an unicode object
were handed it.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

test: Fix date in test message in multipart test.

The test message date, "Tue, 05 Jan 2001 15:43:57 -0000", is not
actually a real date.  05 Jan 2001 was in fact a Friday, not a
Tuesday.  Date parsers (such as "date" in coreutils) will return "Fri"
as the day for this string, even if "Tue" is specified.

Also, the time zone "-0000" is actually always returned as "+0000", so
we change that here was well.

This will be relevant for later patches when we begin parsing rfc822
part headers, where gmime returns a parsed date string.

If we do want to test date parsing, we should do that in a separate
test.

test: some small fixes to multipart test

There were two "--format=text --part=0" tests.  One of them was
supposed to be a test for "--format=text --part=1".

There were also two errant "test_expect_equal_file OUTPUT EXPECTED"
lines, that are removed here.

build system: Check that python bindings have consistent version when releasing

Thanks to Sebastian Spaeth breaking out version.py, this can be done
without loading notmuch.py, or using sed. version.py is not (yet)
autogenerated because it seems more important to minimize the
differences between the tagged version and the tarball.

lib/gen-version-script.h: add getline and getdelim to notmuch.sym if needed

If the configure script detects missing getline and/or getdelim
symbols, then notmuch will use it's own versions. This patch, based on
id:"87k49v12i5.fsf@pc44es141.cs.uni-magdeburg.de" by Matthias
Guedemann, adds the symbols to notmuch.sym as well so they are
properly exported from the library.

lib/gen-version-script.sh: replace --defined argument to nm with awk

OpenBSD nm apparently doesn't support --defined.

The awk condition is based on the assumption that all defined symbols
have some hex number in the first column.

Thanks to Matthias Guedemann reporting the problem, and an earlier
version of this patch.

fix checking whether header is member of message-hidden-headers

Emacs lisp function 'member' takes element and list as an
argument. I.e. the second argument is list, not symbol
referencing the list.
On emacs 23.x the member call always returned nil (thus buggy),
on emacs 22.x the call failed, making it unusable.

python: Have setup.py read the version number without importing

Importing the notmuch module in setup.py is a no-no, and we want
to auto-generate the version number in the release process.

Outsource __VERSION__ to the new version.py which contains nothing else
and which can therefor easily be autogenerated. Have setup.py read in
the file via execfile and test if importing the version number actually
worked.

This should make all happy.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

python: Updated development status and wording in setup.py

We are beyond pre-alpha, and the Requirements wording could take some
tweaking. Done.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

Revert "python: Simplify setup.py"

This reverts commit 8826fc2d7b4e59afdd8cea06891a0c43245340c5.

It seems that importing the module in setup.py is controversial at best,
as it will fail for users that don't have all dependencies
installed. This was the case in e.g. the Ubuntu autobuilder, so building
notmuch failed. The plan is to create an autogenerated setup.py that can
be used for version information.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

Merge branch 'master' of ssh://notmuchmail.org/git/notmuch

python: Simplify setup.py

We were using a template setup.py which parsed __init__.py in complex
ways just to find out the version number. Simply import notmuch and use
__VERSION__ directly. Also adapt some wording and setup.py values while
going through.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

re-enable notmuch.sym generation using POSIX sed

Unfortunately Robin Green's patch 52e4dedf9aa was lost when I created
gen-version-script.sh. This merges his changes manually into that
script. It turns out tabs seem not needed in version script
files, so I simplified a bit and removed the printf.

Thanks to Alexander Botero-Lowry for help and testing.

python: Fix unsafe utf-8 decodings

This prevents unsafe calls to decode for return value None in
get_authors/get_subject which would current throw an Exception. Original
patch modified by Sebastian Spaeth.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

decode headers from utf-8 to unicode

as mail headers are stored as utf-8 in the index,
it is safe to return them as unicode strings directly

python: remove Tags().__len__() implementation

len() exhausts the tag iterator and e.g. list() or "".join(tags)
implicitly call len() if existing and then failing. So, we remove
Tags.__len__().

If you need to know the number of tags a message has, do use
len(list(tags)). It would be nicer to be able to support len() directly...

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

python: Do explicitly check if the next tag exists

If we try to pull a non-existing tag, Tags._get will return None and the
appended .decode() command will fail. So make sure that there is a tag to
be fetched before fetching it.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

python: pep8 compliance for __init__.py