docs: Update news, man page, and online help for restore --accumulate

As a side effect, reformat the NEWs entry for notmuch dump for
consistency with the notmuch restore NEWS submitted by Thomas
Schwinge.

notmuch-restore: check for extra arguments.

We consider it an error to pass more than one file to restore, since
extra ones are ignored.

notmuch-restore: implement --accumulate option

Modify command line argument handling to take a --accumulate flag.
Test for extra arguments beyond the input file.

The --accumulate switch causes the union of the existing and new tags to be
applied, instead of replacing each message's tags as they are read in from the
dump file.

Based on a patch by Thomas Schwinge:

      id:"1317317857-29636-1-git-send-email-thomas@schwinge.name"

test/dump-restore: add tests for restore --accumulate

Flesh out what ``notmuch restore --accumulate'' is supposed to do.
Its tests are currently XFAILed; the functionality will be added in
future patch(es).

Based on a patch by Thomas Schwinge:

      id:"1317317811-29540-1-git-send-email-thomas@schwinge.name"

notmuch.1: typo fixes new wording for dump/restore

These changes were included in Thomas's restore --accumulate patch,
but are actually more generally applicable.

test/dump-restore: Fix quoting on grep

Thanks to Thomas Schwinge for noticing yet another place where quoting
matters. Since the shell translates \. to ., the regex passed to grep
is too generous without the quotes.

The use of [.] is the suggestion of Tomi Ollila.

test/dump-restore: expand test suite for dump-restore, make more robust

Several new tests are added, and existing use of test_begin_subtest is
replaced by test_expect_success to catch failing commands in cases where
we execute more than one command.

Based on changes in

      id:"1317317811-29540-1-git-send-email-thomas@schwinge.name"

test/test-lib.sh: update comments

- explain test_expect_equal_file
- remove mention of test_expect_failure, since that function was removed.

Based on id:"1317317811-29540-1-git-send-email-thomas@schwinge.name"

cli: change argument parsing convention for subcommands

previously we deleted the subcommand name from argv before passing to
the subcommand. In this version, the deletion is done in the actual
subcommands. Although this causes some duplication of code, it allows
us to be more flexible about how we parse command line arguments in
the subcommand, including possibly using off-the-shelf routines like
getopt_long that expect the name of the command in argv[0].

docs: Update man page, NEWS and online help for new dump arguments.

We mention in all three places that using the filename argument is
deprecated.

notmuch-dump: deprecate use of output file argument.

We print an intentionally non-specific message on stderr, since it
isn't clear if there will be some global output file argument to
replace.

We update the test suite atomically, since it relies on having the
same text in two files.

notmuch-dump: treat any remaining arguments after the filename as search terms

The main motivation here is allow the fast dumping of tag data for
messages having certain tags.  In practice it seems too slow to pipe
dump to grep.

All dump-restore tests should be working now, so we update test/dump-restore
accordingly

notmuch-dump: update handling of file name argument

We permit -- as an "option processing terminator".

Currently this does not do anything useful, but we plan to add
search terms after the --.

test: add tests for command line arguments to notmuch-dump

The plan is to add the possibility of search terms after the file name,
and the use of -- to stop looking for an output file name.

test: update dump-restore to use redirection instead of filename args

The idea here is that we want to deprecate the use of arguments to
dump and restore to specify paths, since in particular we want to use
the non-option arguments to dump to form a query.

debian: changelog stanza for 0.9

Admit that there have been no changes since the last release
candidate.

version: bump to 0.9

also bump python bindings version.

NEWS: document API changes to n_d_find_message{,_by_filename}

For details the user will have to refer to the source.  Reformat Ruby
news consistently with Python.

NEWS: document API changes to n_d_find_message{,_by_filename}

For details the user will have to refer to the source.

test: add two emacs tests for show mode refresh

The first test tests that the notmuch-show-refresh-view function
produces the exact same output for an unmodified show buffer.  This
test should pass since the relevant functionality has already been
applied.

The second test tests show refresh for a show buffer that has been
modified by navigation and message visibility toggling.  Ideally
refresh-view should preserve this state of the notmuch-show buffer.
Unfortunately it currently does not, so this test is know to be broken
and is marked as such.

NEWS: add notes about emacs improvements and reply formating cleanup

version: bump to 0.9~rc2

We continue to keep the python bindings version in sync manually

debian: update changelog for 0.9~rc2-1

Document upstream changes since 0.9~rc1-1

emacs: add notmuch-show-refresh-view function

This function, like the equivalent for notmuch-search, just refreshes
the current show view.  Like in notmuch-search, this new function is
bound to "=".  If a prefix is given then the redisplay happens with the
crypto-switch set, which displays the thread with the opposite logic
of whatever is set in the notmuch-crypto-process-mime customization
variable.

emacs: Add callback functions to crypto sigstatus button.

This adds two callback functions to the sigstatus button.  If the sig
status is "good", then clicking the button displays the output of "gpg
--list-keys" on the key fingerprint.  If the sigstatus is "bad", then
clicking the button will retrieve the key from the keyserver, and
redisplay the current buffer.

Thanks to David Bremner <bremner@unb.ca> for help with this.

Ignore "application/pgp-*" parts in reply.

The quoted text doesn't need to mention that the message being replied
to had these crufty parts.

test: test for absence of "Non-text part: application/pgp-*" lines in reply

In reply, the quoted text does not need to mention that the original
message had "application/pgp-signed" or "application/pgp-encrypted"
parts.

Fix notmuch-reply to not output "Non-text part:" lines for non-leafnode parts.

These lines are just cruft in this case, and can be removed.

test/multipart: test for absence of "Non-text part:" lines in reply for multipart/* and message/rfc822 parts

There's no reason to output "Non-text part:" lines for parts that are
not leaf nodes, eg. multipart/* and message/rfc822.  We fix the text
here to test for their absence.  The next patch will fix reply
accordingly.

python: Set status in the class definitions

Technically, this is a superfluous change, as the self.status variable
currently gets set in NotmuchErrors's __new__ function. However, in the
long run I would like to get rid of the weird __new__ implementation which
might be somewhat confusing for users (NotmuchError(status) returns a
different class, e.g. OutOfMemoryError)

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

python: help function Query._assert_query_is_initialized

Remove code duplication by using the new helper function. Also raise the
new fine grained exceptions in many cases, rather than the more generic
NotmuchErrors.

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

python: clean up docstrings and API documentation

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

python: whitespace fixed in docstrings

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

python: Add the new exception types in the API documentation

as they should be documented...

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

python: Catch up with find_message(by_filename) API changes

message is now an out parameter, and we get an additional status code as
a result. Hurray \o/.

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

python: also use libnotmuch.so.2

Catch up with the major version bump. I wonder if this could somehow be
automatically made the correct version number. Oh well, I hope it
doesn't change too often :-).

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

debian: update packaging for new soname

we need
   - a new changelog stanza, because the symbols files need a new version
   - s/libnotmuch1/libnotmuch2/ everywhere
   - update symbols file, s/.so.1/.so.2/, and bump minimum versions on changed
     symbols (although the latter is just documentation)

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