add tip about metadata driven views (and more flexible view filtering)

While writing this documentation, I realized that there needed to be a way
to stay in a view like tag=* while adding a filter like tag=work that
applies to the same field.

So, there are really two ways a view can be refined. It can have a new
"field=explicitvalue" filter added to it, which does not change the
"shape" of the view, but narrows the files it shows.
Or, it can have a new view added, which adds another level of
subdirectories.

So, added a vfilter command, which takes explicit values to add to the
filter, and rejects changes that would change the shape of the view.

And, made vadd only accept changes that change the shape of the view.

And, changed the View data type slightly; now components that can match
multiple metadata values can be visible, or not visible.

This commit was sponsored by Stelian Iancu.

Command/VAdd.hs

@@ -10,12 +10,11 @@ module Command.VAdd where
 import Common.Annex
 import Command
 import Annex.View
-import Logs.View
 import Command.View (paramView, parseViewParam, checkoutViewBranch)
 
 def :: [Command]
 def = [notBareRepo $ notDirect $
-	command "vadd" paramView seek SectionMetaData "refine current view"]
+	command "vadd" paramView seek SectionMetaData "add subdirs to current view"]
 
 seek :: CommandSeek
 seek = withWords start
@@ -23,20 +22,15 @@ seek = withWords start
 start :: [String] -> CommandStart
 start params = do
 	showStart "vadd" ""
-	go =<< currentView
-  where
-	go Nothing = error "Not in a view."
-	go (Just view) = do
-		let (view', change) = calc view Unchanged (reverse params)
+	withCurrentView $ \view -> do
+		let (view', change) = refineView view $
+			map parseViewParam $ reverse params
 		case change of
 			Unchanged -> do
 				showNote "unchanged"
 				next $ next $ return True
-			Narrowing -> next $ next $
-				checkoutViewBranch view' narrowView
+			Narrowing -> next $ next $ do
+				if visibleViewSize view' == visibleViewSize view
+					then error "That would not add an additional level of directory structure to the view. To filter the view, use vfilter instead of vadd."
+					else checkoutViewBranch view' narrowView
 			Widening -> error "Widening view to match more files is not currently supported."
-
-	calc v c [] = (v, c)
-	calc v c (p:ps) =
-		let (v', c') = uncurry (refineView v) (parseViewParam p)
-		in calc v' (max c c') ps

Command/View.hs

@@ -53,12 +53,9 @@ parseViewParam s = case separate (== '=') s of
 mkView :: [String] -> Annex View
 mkView params = do
 	v <- View <$> viewbranch <*> pure []
-	return $ calc v $ reverse params
+	return $ fst $ refineView v $
+		map parseViewParam $ reverse params
   where
-	calc v [] = v
-	calc v (p:ps) =
-		let (v', _) = uncurry (refineView v) (parseViewParam p)
-		in calc v' ps
 	viewbranch = fromMaybe (error "not on any branch!")
 		<$> inRepo Git.Branch.current