command line: listing databases

[Patrick Ohly]

Hello!

The current approach of invoking the command line without arguments to
list databases has various shortcomings:
      * unusual "syntax"
      * cannot limit the output to specific databases
      * does not work for CalDAV/CardDAV, which needs credentials and/or
        syncURL

Here's a proposal, written as patch for README.rst:

===================================================================
 SYNOPSIS
 ========
 
-Show available sources:
-  syncevolution
+List databases:
+  syncevolution --print-databases [<properties>] [<config> <source>]
 
 Show information about configuration(s):
   syncevolution --print-servers|--print-configs|--print-peers
 
@@ -114,15 +114,29 @@ Sometimes it is also useful to change configuration options of a
 context, without modifying a specific peer. This can be done by using
 `@default` (or some other context name) without anything before the
 `at` sign. The empty string "" is the same as `@default`. ::
 
-   syncevolution
-
-If no arguments are given, then SyncEvolution will list all available
-data sources regardless whether there is a configuration file for them
-or not. The output includes the identifiers which can then be used to
-select those sources in a configuration file. For each source one can
-set a different synchronization mode in its configuration file. ::
+   syncevolution --print-databases [<properties>] [<config> <source>]
+
+If no additional arguments are given, then SyncEvolution will list all
+available backends and the databases that can be accessed through each
+backend. This works without existing configurations. However, some
+backends need additional information (like credentials or URL of a
+remote server) and/or cannot list databases (file backend). This
+additional information can be provided on the command line with
+property assignments (`username=...`) or in an existing configuration.
+The output in these cases explains the required information further.
+
+Otherwise the output starts with a heading that lists the values for
+the `backend` property which select the backend, followed by the databases.
+Each database has a name and a unique ID (in brackets). Typically
+both can be used as value of the 'database' property. One database
+might be marked as `default`. It will be used when `database` is not
+set explicitly.
+
+When selecting an existing source configuration or specifying the `backend`
+property on the command line, only the databases for that backend
+are listed, using the same output format.

=============================================================

Does this make sense?

I have partly implemented that because I wanted to test auto-discovery
of databases in CalDAV at the CalConnect interoperability test event. I
have used it like this to show all address books on a specific server:
     syncevolution --print-databases \
                   syncURL=http://... \
                   username=... \
                   password=... \
                   backend=carddav

I'm undecided whether listing all databases of all sources in a config
should also be supported. Right now, if a config is specified, then a
source also must be given ([<config> <source>]). Would it be useful to
support the [<config> [<source>]] syntax also (= config without source)?

This is for the command line. In the D-Bus API, GetDatabases() already
is defined per source and can be used on a session where temporary
config changes were made, so it should already work without API changes.

Long term the returned information should be made a bit richer and also
include additional information:
      * read-only databases => can be mirrored locally, but not be
        written to
      * large databases (for example, CardDAV gateways) => only access
        them in queries, never sync them

Related to this change is the removal of <config> and <source> as
mandatory. Item operations can work without them, if backend and
possibly database are specified as properties on the command line. Not
written up yet, but I'll make the change soon.


-- 
Best Regards, Patrick Ohly

The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.