On Fri 03 Jul 2020 at 10:43 -0300, David Bremner wrote:
> Several aspects of this are potentially controversial:
>
> 1) The use of environment variables as fallback. I understand the
> discomfort with having a library function check the environment, but
> this seems to be functionality people want, and it is better to
> implement it once.
>
> 2) The use of both NULL and "" to do different things for config_path.
>
> 3) The new API is pretty complex, compared to the previous one.
> ---
>
> There is not much code to back this so far. This is just me thinking
> out loud at this point. The location calculation is done (and also
> easy). The challenging part is probably updating
> notmuch_database_get_config to do what this comment promises.
>
> I suspect database_create will probably need to be updated to match.
>
> Another question is if we should have an opaque set of options to pass
> to open (in the style notmuch_indexopts_t). Currently this is just
> future proofing as far as I know.
>
> lib/notmuch.h | 138 --
> 1 file changed, 111 insertions(+), 27 deletions(-)
>
> diff --git a/lib/notmuch.h b/lib/notmuch.h
> index ceb5a018..6a46b80a 100644
> --- a/lib/notmuch.h
> +++ b/lib/notmuch.h
> @@ -301,52 +301,136 @@ typedef enum {
> } notmuch_database_mode_t;
>
> /**
> - * Open an existing notmuch database located at 'path'.
> + * Deprecated alias for notmuch_database_open_with_config with
> + * config_path=error_message=NULL
> + * @deprecated Deprecated as of libnotmuch 5.2 (notmuch 0.31)
> + */
> +NOTMUCH_DEPRECATED(5, 2)
> +notmuch_status_t
> +notmuch_database_open (const char *path,
> +notmuch_database_mode_t mode,
> +notmuch_database_t **database);
> +/**
> + * Deprecated alias for notmuch_database_open_with_config with
> + * config_path=NULL
> + *
> + * @deprecated Deprecated as of libnotmuch 5.2 (notmuch 0.31)
> + *
> + */
> +NOTMUCH_DEPRECATED(5, 2)
> +notmuch_status_t
> +notmuch_database_open_verbose (const char *path,
> +notmuch_database_mode_t mode,
> +notmuch_database_t **database,
> +char **error_message);
> +
> +/**
> + * Open an existing notmuch database located at 'database_path', using
> + * configuration in 'config_path'.
> + *
> + * @param[in]database_path
> + * @parblock
> + * Path to existing database.
> + *
> + * A notmuch database is a Xapian database containing appropriate
> + * metadata.
> *
> * The database should have been created at some time in the past,
> * (not necessarily by this process), by calling
> - * notmuch_database_create with 'path'. By default the database should be
> - * opened for reading only. In order to write to the database you need to
> - * pass the NOTMUCH_DATABASE_MODE_READ_WRITE mode.
> + * notmuch_database_create.
> + *
> + * If 'database_path' is NULL, use the location specified
> + *
> + * - in the environment variable NOTMUCH_DATABASE, if non-empty
> + *
> + * - by $XDG_DATA_HOME/notmuch/$NOTMUCH_PROFILE where XDG_DATA_HOME
> + * defaults to "$HOME/.local/share" and NOTMUCH_PROFILE defaults to
> + * "default"
I like the profile support, is the plan for
$XDG_DATA_HOME/notmuch/$NOTMUCH_PROFILE to be written when creating the
database?
> + *
> + * If 'database_path' is non-NULL, but does not appear to be a Xapian
> + * database, check for a directory '.notmuch/xapian' below
> + * 'database_path'.
> + *
> + * @endparblock
> + * @param[in]mode
> + * @parblock
> + * Mode to open database
> + *
> + * By default the database will be opened for reading only. In order
> + * to write to the database you need to pass the
> + * #NOTMUCH_DATABASE_MODE_READ_WRITE mode.
> + *
> + * @endparblock
> + * @param[in] config_path
> + * @parblock
> + * Path to config file.
> + *
> + * Config file is key-value, with mandatory sections. See
> + * notmuch-config(5) for more information. The key-value pair
> + * overrides the corresponding configuration data stored in the
> + * database (see notmuch_database_get_config)
> *
> - * An existing notmuch database can be identified by the presence of a
> - * directory named ".notmuch" below 'path'.
> + * If config_path is NULL use the path specified
> + *
> + * - in environment variable NOTMUCH_CONFIG, if non-empty
> + *
> + * - by XDG_CONFIG_HOME/notmuch/ where
> + * XDG_CONFIG_HOME defaults to "$HOME/.config".
> + *
> + * - by $HOME/.notmuch-config
> + *
> + * If config_path is "" (empty string) then do not
> + * open any configuration file.
> + * @endparblock
> + * @param[in] profile:
> + * @parblock
> + * Name of profile (configuration/database variant).
> + *
> + * If non-NULL, append to the directory / file path determined by
> + * config_path.
> + *
> + * If NULL then use
> + * - environment variable NOTMUCH_PROFILE if defined,
> + * - otherwise "default" for directories and "" (empty string) for paths.
> + *
> + * @endpa
