notmuch

package module
v0.0.0-...-0c91863 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 18, 2022 License: GPL-2.0, GPL-3.0 Imports: 8 Imported by: 5

README

Build Status

Go binding for notmuch mail.

Licensed under the GPLv3 or later (like notmuch itself).

Development

Running tests

The project uses make to setup and download additional assets for the tests.

Run make test to run the tests.

Pre PR checks

Next to the tests, you should also run gofmt on the sourcecode. Running make fmtcheck checks for formatting issues.

To run both tests and format checks, use make ci.

Documentation

Overview

Package notmuch provides a Go language binding to the notmuch mail library.

The design is similar enough to the underlying C library that familiarity with one will inform the other. There are some differences, however:

  • The Go binding arranges for the garbage collector to deal with objects allocated by notmuch correctly. You should close the database manually, but everything else will be garbage collected when it becomes unreachable, and not before. Objects hold references to their parent objects to make this go smoothly.
  • If notmuch returns NULL because of an out of memory error, Go will panic, as it does with other out of memory errors.
  • Some of the names have been shortened or made more idiomatic. The documentation indends to make it obvious when this is the case.
  • Functions which create a child object from a parent object are methods on the parent object, rather than stand-alone functions.
  • Functions which in C return a status code and pass back a value via a pointer argument now return a (value, error) pair.

Index

Constants

View Source 
const (
	// DBReadOnly is the mode for opening the database in read only.
	DBReadOnly = C.NOTMUCH_DATABASE_MODE_READ_ONLY

	// DBReadWrite is the mode for opening the database in read write.
	DBReadWrite = C.NOTMUCH_DATABASE_MODE_READ_WRITE

	// TagMax is the maximum number of allowed tags.
	TagMax = C.NOTMUCH_TAG_MAX
)

Variables

View Source 
var (
	// ErrOutOfMemory is returned when an Out of memory occured.
	ErrOutOfMemory = statusErr(C.NOTMUCH_STATUS_OUT_OF_MEMORY)

	// ErrReadOnlyDB is returned when an attempt was made to write to a
	// database opened in read-only mode.
	ErrReadOnlyDB = statusErr(C.NOTMUCH_STATUS_READ_ONLY_DATABASE)

	// ErrXapianException is returned when a xapian exception occured.
	ErrXapianException = statusErr(C.NOTMUCH_STATUS_XAPIAN_EXCEPTION)

	// ErrFileError is returned when an error occurred trying to read or write to
	// a file (this could be file not found, permission denied, etc.)
	ErrFileError = statusErr(C.NOTMUCH_STATUS_FILE_ERROR)

	// ErrFileNotEmail is returned when a file was presented that doesn't appear
	// to be an email message.
	ErrFileNotEmail = statusErr(C.NOTMUCH_STATUS_FILE_NOT_EMAIL)

	// ErrDuplicateMessageID is returned when a file contains a message ID that
	// is identical to a message already in the database.
	ErrDuplicateMessageID = statusErr(C.NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID)

	// ErrNullPointer is returned when the user erroneously passed a NULL pointer
	// to a notmuch function.
	ErrNullPointer = statusErr(C.NOTMUCH_STATUS_NULL_POINTER)

	// ErrTagTooLong is returned when a tag value is too long (exceeds TagMax)
	ErrTagTooLong = statusErr(C.NOTMUCH_STATUS_TAG_TOO_LONG)

	// ErrUnbalancedFreezeThaw is returned when Message.Thaw() was called more
	// times than Message.Freeze().
	ErrUnbalancedFreezeThaw = statusErr(C.NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW)

	// ErrUnbalancedAtomic DB.EndAtomic() has been called more times than DB.BeginAtomic()
	ErrUnbalancedAtomic = statusErr(C.NOTMUCH_STATUS_UNBALANCED_ATOMIC)

	// ErrUnsupportedOperation is returned when the operation is not supported.
	ErrUnsupportedOperation = statusErr(C.NOTMUCH_STATUS_UNSUPPORTED_OPERATION)

	// ErrUpgradeRequired is returned when the database requires an upgrade.
	ErrUpgradeRequired = statusErr(C.NOTMUCH_STATUS_UPGRADE_REQUIRED)

	// ErrIgnored is returned if the operation was ignored
	ErrIgnored = statusErr(C.NOTMUCH_STATUS_IGNORED)

	// ErrNotFound is returned when Find* did not find the thread/message by id or filename.
	ErrNotFound = errors.New("not found")

	// ErrUnknownError is returned when notmuch returns NULL indicating an error.
	ErrUnknownError = errors.New("unknown error occured")

	// ErrNoRepliesOrPointerNotFromThread is returned if a message has no replies or if the message's C
	// pointer did not come from a thread.
	ErrNoRepliesOrPointerNotFromThread = errors.New("message has no replies or message's pointer not from a thread")
)

Functions

func Compact 

func Compact(path, backup string) error

Compact compacts a notmuch database, backing up the original database to the given path. The database will be opened with DBReadWrite to ensure no writes are made.

Types

type ConfigList 

type ConfigList cStruct

Messages represents a notmuch config list

func (*ConfigList) Close 

func (cl *ConfigList) Close() error

func (*ConfigList) Next 

func (cl *ConfigList) Next(key, value *string) bool

Next retrieves the nex config pair from the ConfigList. Neither key, nor value may be nil, or this function will panic. Next returns true if a pair was successfully retrieved.

type DB 

type DB cStruct

DB represents a notmuch database.

func Create 

func Create(path string) (*DB, error)

Create creates a new, empty notmuch database located at 'path'.

func Open 

func Open(path string, mode DBMode) (*DB, error)

Open opens the database at the location path using mode. Caller is responsible for closing the database when done.

func OpenWithConfig 

func OpenWithConfig(path, config, profile *string, mode DBMode) (*DB, error)

OpenWithConfig opens the database at the location 'path' using 'mode' and the configuration in 'config'.

If 'path' is nil, use the location specified:

  • in the environment variable $NOTMUCH_DATABASE, if non-empty
  • in a configuration file, located as described in 'config'
  • by $XDG_DATA_HOME/notmuch/<profile>, if profile argument is set

If 'path' is non-nil, but does not appear to be a Xapian database, check for a directory '.notmuch/xapian' below 'path'.

If 'config' is nil, it will look:

  • the environment variable $NOTMUCH_CONFIG, if non-empty
  • $XDG_CONFIG_HOME/notmuch
  • $HOME/.notmuch-config

If 'config' is an empty string (""), then it will not open any configuration file.

If 'profile' is nil, it will use:

  • the environment variable $NOTMUCH_PROFILE if defined
  • otherwise 'default' for directories, and ” for paths

If 'profile' is non-nil, append to the directory / file path determined for 'config' and 'path'.

Caller is responsible for closing the database when done.

func (*DB) AddMessage 

func (db *DB) AddMessage(filename string) (*Message, error)

AddMessage adds a new message to the current database or associate an additional filename with an existing message.

func (*DB) Atomic 

func (db *DB) Atomic(callback func(*DB)) error

Atomic opens an atomic transaction in the database and calls the callback.

func (*DB) Close 

func (db *DB) Close() error

Close closes the database.

func (*DB) FindMessage 

func (db *DB) FindMessage(id string) (*Message, error)

FindMessage finds a message with the given message_id.

func (*DB) FindMessageByFilename 

func (db *DB) FindMessageByFilename(filename string) (*Message, error)

FindMessageByFilename finds a message with the given filename.

func (*DB) GetConfig 

func (db *DB) GetConfig(key string) (string, error)

GetConfig gets config value of key

func (*DB) GetConfigList 

func (db *DB) GetConfigList(prefix string) (*ConfigList, error)

GetConfigList returns the config list, which can be used to iterate over all set options starting with prefix.

func (*DB) LastStatus 

func (db *DB) LastStatus() string

LastStatus retrieves last status string for the notmuch database.

func (*DB) NeedsUpgrade 

func (db *DB) NeedsUpgrade() bool

NeedsUpgrade returns true if the database can be upgraded. This will always return false if the database was opened with DBReadOnly.

If this function returns true then the caller may call Upgrade() to upgrade the database.

func (*DB) NewQuery 

func (db *DB) NewQuery(queryString string) *Query

NewQuery creates a new query from a string following xapian format.

func (*DB) Path 

func (db *DB) Path() string

Path returns the database path of the database.

func (*DB) RemoveMessage 

func (db *DB) RemoveMessage(filename string) error

RemoveMessage remove a message filename from the current database. If the message has no more filenames, remove the message.

func (*DB) SetConfig 

func (db *DB) SetConfig(key, value string) error

SetConfig sets config key to value.

func (*DB) Tags 

func (db *DB) Tags() (*Tags, error)

Tags returns the list of all tags in the database.

func (*DB) Upgrade 

func (db *DB) Upgrade() error

Upgrade upgrades the current database to the latest supported version. The database must be opened with DBReadWrite.

func (*DB) Version 

func (db *DB) Version() int

Version returns the database version.

type DBMode 

type DBMode C.notmuch_database_mode_t

DBMode is the mode of the database opening, DBReadOnly or DBReadWrite

type ExcludeMode 

type ExcludeMode C.notmuch_exclude_t

ExcludeMode represents the exclude behaviour of a query. One of EXCLUDE_{ALL,FLAG,TRUE,FALSE}. 

var (
	// Query.Messages and Query.Threads will return all matching
	// messages/threads regardless of exclude status.
	// The exclude flag will be set for any excluded message that is
	// returned by Query.SearchMessages, and the thread counts
	// for threads returned by Query.Threads will be the
	// number of non-excluded messages/matches.
	EXCLUDE_FLAG ExcludeMode = C.NOTMUCH_EXCLUDE_FLAG
	// Query.Messages and Query.Threads will return all matching
	// messages/threads regardless of exclude status.
	// The exclude status is completely ignored.
	EXCLUDE_FALSE ExcludeMode = C.NOTMUCH_EXCLUDE_FALSE
	// Query.Messages will omit excluded messages from the results,
	// and Query.Threads will omit threads that match only in excluded messages.
	// Query.Threads will include all messages in threads that
	// match in at least one non-excluded message.
	EXCLUDE_TRUE ExcludeMode = C.NOTMUCH_EXCLUDE_TRUE
	// Query.Messages will omit excluded messages from the results,
	// and Query.Threads will omit threads that match only in excluded messages.
	// Query.Threads will omit excluded messages from all threads.
	EXCLUDE_ALL ExcludeMode = C.NOTMUCH_EXCLUDE_ALL
)

type Filenames 

type Filenames struct {
	// contains filtered or unexported fields
}

Filenames is an iterator to get the message's filenames.

func (*Filenames) Next 

func (fs *Filenames) Next(f *string) bool

Next retrieves the next filename from the iterator. Next returns true if a filename was successfully retrieved.

type Message 

type Message cStruct

Message represents a notmuch message.

func (*Message) AddProperty 

func (m *Message) AddProperty(key string, value string) error

AddProperty adds a property to the message.

func (*Message) AddTag 

func (m *Message) AddTag(tag string) error

AddTag adds a tag to the message.

func (*Message) Atomic 

func (m *Message) Atomic(callback func(*Message)) error

Atomic allows a transactional change of tags to the message.

func (*Message) Close 

func (m *Message) Close() error

func (*Message) Date 

func (m *Message) Date() time.Time

Date returns the date of the message.

func (*Message) Filename 

func (m *Message) Filename() string

Filename returns the absolute path of the email message.

Note: If this message corresponds to multiple files in the mail store, (that is, multiple files contain identical message IDs), this function will arbitrarily return a single one of those filenames. See Filenames for returning the complete list of filenames.

func (*Message) Filenames 

func (m *Message) Filenames() *Filenames

Filenames returns *Filenames an iterator to get the message's filenames. Each filename in the iterator is an absolute filename.

func (*Message) Header 

func (m *Message) Header(name string) string

Header returns the value of the header.

func (*Message) ID 

func (m *Message) ID() string

ID returns the message ID.

func (*Message) MaildirFlagsToTags 

func (m *Message) MaildirFlagsToTags() error

MaildirFlagsToTags adds/removes tags according to maildir flags in the message filename(s). This function examines the filenames of 'message' for maildir flags, and adds or removes tags on 'message' as follows when these flags are present: 

Flag    Action if present
----    -----------------
'D'     Adds the "draft" tag to the message
'F'     Adds the "flagged" tag to the message
'P'     Adds the "passed" tag to the message
'R'     Adds the "replied" tag to the message
'S'     Removes the "unread" tag from the message

For each flag that is not present, the opposite action (add/remove) is performed for the corresponding tags.

Flags are identified as trailing components of the filename after a sequence of ":2,".

If there are multiple filenames associated with this message, the flag is considered present if it appears in one or more filenames. (That is, the flags from the multiple filenames are combined with the logical OR operator.)

A client can ensure that notmuch database tags remain synchronized with maildir flags by calling this function after each call to DB.AddMessage. See also Message.TagsToMaildirFlags for synchronizing tag changes back to maildir flags.

func (*Message) Properties 

func (m *Message) Properties(key string, exact bool) *MessageProperties

Properties returns the properties for the current message, returning a *MessageProperties which can be used to iterate over all properties using `MessageProperties.Next(MessageProperty)`

func (*Message) RemoveAllProperties 

func (m *Message) RemoveAllProperties(key string) error

RemoveAllProperties removes all properties with key from the message.

func (*Message) RemoveAllTags 

func (m *Message) RemoveAllTags() error

RemoveAllTags removes all tags from the message.

func (*Message) RemoveProperty 

func (m *Message) RemoveProperty(key string, value string) error

RemoveProperty removes a key/value pair from the message properties.

func (*Message) RemoveTag 

func (m *Message) RemoveTag(tag string) error

RemoveTag removes a tag from the message.

func (*Message) Replies 

func (m *Message) Replies() (*Messages, error)

Replies returns the replies of a message.

func (*Message) Tags 

func (m *Message) Tags() *Tags

Tags returns the tags for the current message, returning a *Tags which can be used to iterate over all tags using `Tags.Next(Tag)`

func (*Message) TagsToMaildirFlags 

func (m *Message) TagsToMaildirFlags() error

TagsToMaildirFlags renames message filename(s) to encode tags as maildir flags. Specifically, for each filename corresponding to this message:

If the filename is not in a maildir directory, do nothing. (A maildir directory is determined as a directory named "new" or "cur".) Similarly, if the filename has invalid maildir info, (repeated or outof-ASCII-order flag characters after ":2,"), then do nothing.

If the filename is in a maildir directory, rename the file so that its filename ends with the sequence ":2," followed by zero or more of the following single-character flags (in ASCII order):

  • flag 'D' if the message has the "draft" tag
  • flag 'F' if the message has the "flagged" tag
  • flag 'P' if the message has the "passed" tag
  • flag 'R' if the message has the "replied" tag
  • flag 'S' if the message does not have the "unread" tag

Any existing flags unmentioned in the list above will be preserved in the renaming.

Also, if this filename is in a directory named "new", rename it to be within the neighboring directory named "cur".

A client can ensure that maildir filename flags remain synchronized with notmuch database tags by calling this function after changing tags. See also Message.MaildirFlagsToTags for synchronizing maildir flag changes back to tags.

func (*Message) ThreadID 

func (m *Message) ThreadID() string

ThreadID returns the ID of the thread to which this message belongs to.

type MessageProperties 

type MessageProperties cStruct

MessageProperties represent a notmuch properties type.

func (*MessageProperties) Close 

func (props *MessageProperties) Close() error

func (*MessageProperties) Next 

func (props *MessageProperties) Next(p **MessageProperty) bool

Next retrieves the next prop from the result set. Next returns true if a prop was successfully retrieved.

type MessageProperty 

type MessageProperty struct {
	Key   string
	Value string
	// contains filtered or unexported fields
}

MessageProperty represents a property in the database.

func (*MessageProperty) String 

func (p *MessageProperty) String() string

type Messages 

type Messages cStruct

Messages represents notmuch messages.

func (*Messages) Close 

func (ms *Messages) Close() error

func (*Messages) Next 

func (ms *Messages) Next(m **Message) bool

Next retrieves the next message from the result set. Next returns true if a message was successfully retrieved.

func (*Messages) Tags 

func (ms *Messages) Tags() *Tags

Tags return a list of tags from all messages.

WARNING: You can no longer iterate over messages after calling this function, because the iterator will point at the end of the list. We do not have a function to reset the iterator yet and the only way how you can iterate over the list again is to recreate the message list.

type Query 

type Query cStruct

Query represents a notmuch query.

func (*Query) AddTagExclude 

func (q *Query) AddTagExclude(tag string) error

AddTagExclude adds a tag that will be excluded from the query results by default. Note that this function returns ErrIgnored if the provided tag appears in the query

func (*Query) Close 

func (q *Query) Close() error

func (*Query) CountMessages 

func (q *Query) CountMessages() int

CountMessages returns the number of messages for the current query.

func (*Query) CountThreads 

func (q *Query) CountThreads() int

CountThreads returns the number of messages for the current query.

func (*Query) Messages 

func (q *Query) Messages() (*Messages, error)

Messages returns the messages matching the query.

func (*Query) SetExcludeScheme 

func (q *Query) SetExcludeScheme(mode ExcludeMode)

SetExcludeScheme is used to set the exclude scheme on a query.

func (*Query) SetSortScheme 

func (q *Query) SetSortScheme(mode SortMode)

SetSortScheme is used to set the sort scheme on a query.

func (*Query) String 

func (q *Query) String() string

String returns the query as a string, implements fmt.Stringer.

func (*Query) Threads 

func (q *Query) Threads() (*Threads, error)

Threads returns the threads matching the query.

type SortMode 

type SortMode C.notmuch_sort_t

SortMode represents the sort behaviour of a query. One of SORT_{OLDEST_FIRST,NEWEST_FIRST,MESSAGE_ID,UNSORTED} 

var (
	SORT_OLDEST_FIRST SortMode = C.NOTMUCH_SORT_OLDEST_FIRST
	SORT_NEWEST_FIRST SortMode = C.NOTMUCH_SORT_NEWEST_FIRST
	SORT_MESSAGE_ID   SortMode = C.NOTMUCH_SORT_MESSAGE_ID
	SORT_UNSORTED     SortMode = C.NOTMUCH_SORT_UNSORTED
)

type Tag 

type Tag struct {
	Value string
	// contains filtered or unexported fields
}

Tag represents a tag in the database.

func (*Tag) String 

func (t *Tag) String() string

type Tags 

type Tags cStruct

Tags represent a notmuch tags type.

func (*Tags) Close 

func (ts *Tags) Close() error

func (*Tags) Next 

func (ts *Tags) Next(t **Tag) bool

Next retrieves the next tag from the result set. Next returns true if a tag was successfully retrieved.

type Thread 

type Thread cStruct

Thread represents a notmuch thread.

func (*Thread) Authors 

func (t *Thread) Authors() ([]string, []string)

Authors returns the list of authors, the first are the authors that matched the query whilst the second return are the rest of the authors. All authors are ordered by date.

func (*Thread) Close 

func (t *Thread) Close() error

func (*Thread) Count 

func (t *Thread) Count() int

Count returns the total number of messages in the current thread.

func (*Thread) CountMatched 

func (t *Thread) CountMatched() int

CountMatched returns the total number of messages in the current thread that matched the search.

func (*Thread) ID 

func (t *Thread) ID() string

ID returns the ID of the thread.

func (*Thread) Messages 

func (t *Thread) Messages() *Messages

Messages returns an iterator for all messages in the current thread in oldest-first order.

func (*Thread) NewestDate 

func (t *Thread) NewestDate() time.Time

NewestDate returns the date of the oldest message in the thread.

func (*Thread) OldestDate 

func (t *Thread) OldestDate() time.Time

OldestDate returns the date of the oldest message in the thread.

func (*Thread) Subject 

func (t *Thread) Subject() string

Subject returns the subject of a thread.

func (*Thread) Tags 

func (t *Thread) Tags() *Tags

Tags returns the tags for the current thread, returning a *Tags which can be used to iterate over all tags using `Tags.Next(Tag)`

Note: In the Notmuch database, tags are stored on individual messages, not on threads. So the tags returned here will be all tags of the messages which matched the search and which belong to this thread.

func (*Thread) TopLevelMessages 

func (t *Thread) TopLevelMessages() *Messages

TopLevelMessages returns an iterator for the top-level messages in the current thread in oldest-first order.

type Threads 

type Threads cStruct

Threads represents notmuch threads.

func (*Threads) Close 

func (ts *Threads) Close() error

func (*Threads) Next 

func (ts *Threads) Next(t **Thread) bool

Next retrieves the next thread from the result set. Next returns true if a thread was successfully retrieved.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.