command line: specify properties per source and config

The new format of the property name in --sync-property is:
  <name>[@<context>|@<peer>@<context>]

--source-property also allows a source name:
  [<source>/]<name>[@<context>|@<peer>@<context>]

This allows to set source properties differently for different
sources in the same command line invocation. The @<context> or
@<peer>@<context> will be used to set properties differently for
main and target context in a local sync (not used yet).

The advantage of this grammar is that a string can be split purely based
on the syntax in PropertySpecifier::StringToPropSpec().

The patch itself is based on the idea of first collecting all of these
config property filters in a new case-insensitive hash structure,
FullProps in ConfigFilter.cpp/h, as part of parsing command line
parameters.

Then once specific filters for sync or sources are needed, they are
generated from FullProps by collecting all that apply, starting with
the ones with lowest priority and overwriting them with more important
(= more specific) ones. This also covers additional filters, like the
shared properties of the target context when printing a template.

Currently FullProps may contain arbitrary source and config
names. Typos are not detected, which is both hard to implement (which
names and configs are valid in the current invocation?) and also
forces users to be very specific (can't apply one set of filters to
different configs) - this is the same conflict of interest as in
"configure", which allows unknown --enable/disable parameters because
they might be relevant in a sub-configure script.

SyncConfig itself still only stores the filters which apply to it, not
the full set of overrides that the Cmdline has in its m_props. The
advantage is that the API remains the same (no change needed or done
in the syncevo-dbus-server). The disadvantage is that in a local
sync, no information is available about the properties applying to the
target context - probably needs to change.

1 files changed, 47 insertions, 3 deletions

diff --git a/README.rst b/README.rst
index 49d62e2e..b3248f12 100644
--- a/README.rst
+++ b/README.rst
@@ -385,6 +385,26 @@ a list of valid values.
   to update the configuration. Can be used multiple times.  Specifying
   an unused property will trigger an error message.
 
+  The <property> has the following format: ``<name>[@<context>|@<peer>@<context>]``
+
+  The optional <context> or <peer>@<context> suffix limits the scope
+  of the value to that particular configuration. This is currently
+  only useful for a local sync, which involves a source and a target
+  configuration.
+
+  A string without a second @ sign inside is always interpreted as a
+  context name, so in contrast to the <server> string, "foo" cannot be
+  used to reference the "foo@default" configuration. Use the full name
+  including the context for that.
+
+  When no config or context is specified explicitly, a value is
+  changed in all active configs, typically the one given with
+  ``<server>``.  The priority of multiple values for the same config
+  is `more specific definition wins`, so ``<peer>@<context>``
+  overrides ``@<context>``, which overrides `no suffix given`.
+  Specifying some suffix which does not apply to the current operation
+  does not trigger an error, so beware of typos.
+
   When using the configuration layout introduced with 1.0, some of the
   sync properties are shared between peers, for example the directory
   where sessions are logged. Permanently changing such a shared
@@ -396,15 +416,39 @@ a list of valid values.
 --source-property|-z <property>=<value>|<property>=?|?
   Same as --sync-property, but applies to the configuration of all active
   sources. `--sync <mode>` is a shortcut for `--source-property sync=<mode>`.
-  
+
+  The <property> has the following format: ``[<source>/]<name>[@<context>|@<peer>@<context>]``
+
+  In it's simplest form without <source>, <context> or <config>,
+  the name specifies one of the know properties.
   When combined with `--configure`, the configuration of all sources
   is modified. The value is applied to all sources unless sources are
   listed explicitly on the command line. So if you want to change a
   source property of just one specific sync source, then use
   `--configure --source-property ... <server> <source>`.
-  
+
+  Adding the <source>/ prefix makes it possible to set the same
+  property differently for different sources in one command::
+
+    --configure --source-property addressbook/sync=two-way \
+                --source-property calendar/sync=one-way-from-server \
+                <server>
+
+  If the same property is set both with and without a <source>/ prefix,
+  then the more specific value with that prefix is used for that source,
+  regardless of the order on the command line. The following command
+  disables all sources except for the addressbook::
+
+    --configure --source-property addressbook/sync=none \
+                --source-property sync=two-way \
+                <server>
+
   As with sync properties, some properties are shared between peers,
-  in particular the selection of which local data to synchronize.
+  in particular the selection of which local data to synchronize.  The
+  optional configuration suffix in ``<property>`` also has the same
+  meaning as for sync properties. That suffix is checked first, so
+  "sync@foo@default" overrides "addressbook/sync", even though
+  "addressbook/sync" normally overrides "sync".
 
 --template|-l <peer name>|default|?<device>
   Can be used to select from one of the built-in default configurations