MFC revisions 274068, 274119, 279624:

r274068: Add key+=append syntax to sysrc(8)
r279624: Add key-=remove syntax
r274119: Add EXAMPLES-section entries for new syntax

Reviewed by:	shurd (r274068)
Thanks to:	seanc
Relnotes:	sysrc(8) now supports key+=append and key-=remove

1 files changed, 131 insertions, 3 deletions

diff --git a/usr.sbin/sysrc/sysrc.8 b/usr.sbin/sysrc/sysrc.8
index ebe5651..31254d4 100644
--- a/usr.sbin/sysrc/sysrc.8
+++ b/usr.sbin/sysrc/sysrc.8
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2011-2014 Devin Teske
+.\" Copyright (c) 2011-2015 Devin Teske
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd Jul 18, 2014
+.Dd March 4, 2015
 .Dt SYSRC 8
 .Os
 .Sh NAME
@@ -35,7 +35,7 @@
 .Op Fl cdDeFhinNqvx
 .Op Fl f Ar file
 .Op Fl j Ar jail | Fl R Ar dir
-.Ar name Ns Op = Ns Ar value
+.Ar name Ns Op Ns Oo +|- Oc Ns = Ns Ar value
 .Ar ...
 .Nm
 .Op Fl cdDeFhinNqvx
@@ -135,6 +135,15 @@ It shares the `-e' and `-n' options
 and also has the same
 .Ql name[=value]
 syntax for making queries/assignments.
+In addition
+.Pq but unlike Xr sysctl 8 ,
+.Ql name+=value
+is supported for adding items to values
+.Pq see APPENDING VALUES
+and
+.Ql name-=value
+is supported for removing items from values
+.Pq see SUBTRACTING VALUES .
 .Pp
 However, while
 .Xr sysctl 8
@@ -183,6 +192,115 @@ modifying these integral files (yet taking care not to allow the file to
 grow unwieldy should
 .Nm
 be called repeatedly).
+.Sh APPENDING VALUES
+When using the
+.Ql key+=value
+syntax to add items to existing values,
+the first character of the value is taken as the delimiter separating items
+.Pq usually Qo \  Qc or Qo , Qc .
+For example, in the following statement:
+.Bl -tag -width indent+
+.It \ 
+.Nm
+cloned_interfaces+=" gif0"
+.El
+.Pp
+the first character is a space, informing
+.Nm
+that existing values are to be considered separated by whitespace.
+If
+.Ql gif0
+is not found in the existing value for
+.Va cloned_interfaces ,
+it is added
+.Pq with delimiter only if existing value is non-NULL .
+.Pp
+For convenience, if the first character is alpha-numeric
+.Pq letters A-Z, a-z, or numbers 0-9 ,
+.Nm
+uses the default setting of whitespace as separator.
+For example, the above and below statements are equivalent since
+.Dq gif0
+starts with an alpha-numeric character
+.Pq the letter Li g :
+.Pp
+.Bl -tag -width indent+
+.It \ 
+.Nm
+cloned_interfaces+=gif0
+.El
+.Pp
+Take the following sequence for example:
+.Bl -tag -width indent+
+.It \ 
+.Nm
+cloned_interfaces= # start with NULL
+.It \ 
+.Nm
+cloned_interfaces+=gif0
+.Dl # NULL -> `gif0' Pq NB: no preceding delimiter
+.It \ 
+.Nm
+cloned_interfaces+=gif0 # no change
+.It \ 
+.Nm
+cloned_interfaces+="tun0 gif0"
+.Dl # `gif0' -> `gif0 tun0' Pq NB: no duplication
+.El
+.Pp
+.Nm
+prevents the same value from being added if already there.
+.Sh SUBTRACTING VALUES
+When using the
+.Ql key-=value
+syntax to remove items from existing values,
+the first character of the value is taken as the delimiter separating items
+.Pq usually Qo \  Qc or Qo , Qc .
+For example, in the following statement:
+.Pp
+.Dl Nm cloned_interfaces-=" gif0"
+.Pp
+the first character is a space, informing
+.Nm
+that existing values are to be considered separated by whitespace.
+If
+.Ql gif0
+is found in the existing value for
+.Va cloned_interfaces ,
+it is removed
+.Pq extra delimiters removed .
+.Pp
+For convenience, if the first character is alpha-numeric
+.Pq letters A-Z, a-z, or numbers 0-9 ,
+.Nm
+uses the default setting of whitespace as separator.
+For example, the above and below statements are equivalent since
+.Dq gif0
+starts with an alpha-numeric character
+.Pq the letter Li g :
+.Pp
+.Bl -tag -width indent+
+.It \ 
+.Nm
+cloned_interfaces-=gif0
+.El
+.Pp
+Take the following sequence for example:
+.Bl -tag -width indent+
+.It \ 
+.Nm
+foo="bar baz" # start
+.It \ 
+.Nm
+foo-=bar # `bar baz' -> `baz'
+.It \ 
+.Nm
+foo-=baz # `baz' -> NULL
+.El
+.Pp
+.Nm
+removes all occurrences of all items provided
+and collapses extra delimiters between items.
 .Sh ENVIRONMENT
 The following environment variables are referenced by
 .Nm :
@@ -243,6 +361,16 @@ Working on other files, such as
 -f /etc/crontab MAILTO
 .Dl returns the value of the MAILTO setting Pq if configured .
 .Pp
+Appending to existing values:
+.Pp
+.Nm
+\&cloned_interfaces+=gif0
+.Dl appends Qo gif0 Qc to $cloned_interfaces Pq see APPENDING VALUES .
+.Pp
+.Nm
+\&cloned_interfaces-=gif0
+.Dl removes Qo gif0 Qc from $cloned_interfaces Pq see SUBTRACTING VALUES .
+.Pp
 In addition to the above syntax,
 .Nm
 also supports inline