add MAP.updateAll hook to booster and docs

Author: jberthold

booster/library/Booster/Builtin.hs

@@ -1,3 +1,4 @@
+{-# LANGUAGE MultiWayIf #-}
 {- |
 Copyright   : (c) Runtime Verification, 2023
 License     : BSD-3-Clause
@@ -24,12 +25,14 @@ import Data.Map (Map)
 import Data.Map qualified as Map
 import Data.Set qualified as Set
 import Data.Text (Text)
+import Data.Text qualified as Text
 import Prettyprinter (pretty, vsep)
 import Text.Read (readMaybe)
 
 import Booster.Definition.Attributes.Base (
     KCollectionSymbolNames (..),
     KListDefinition (..),
+    KMapDefinition (..),
  )
 import Booster.Pattern.Base
 import Booster.Pattern.Bool
@@ -206,6 +209,7 @@ builtinsMAP =
     Map.mapKeys ("MAP." <>) $
         Map.fromList
             [ "update" ~~> mapUpdateHook
+            , "updateAll" ~~> mapUpdateAllHook
             , "remove" ~~> mapRemoveHook
             , -- removeAll: requires a Set argument
               "size" ~~> mapSizeHook
@@ -238,6 +242,45 @@ mapUpdateHook args
     | otherwise =
         throwE . renderText $ "MAP.update: wrong arity " <> pretty (length args)
 
+mapUpdateAllHook :: BuiltinFunction
+mapUpdateAllHook [KMap def1 _ _, KMap def2 _ _]
+    | def1 /= def2 =
+        throwE $
+            "MAP.updateAll: incompatible maps " <>
+                Text.pack (show (def1.mapSortName, def2.mapSortName))
+mapUpdateAllHook [original, KMap _ [] Nothing] =
+    -- updates map is empty, result is original map
+    pure $ Just original
+mapUpdateAllHook [KMap _ [] Nothing, updates] =
+    -- original map is empty, result is updates map
+    pure $ Just updates
+mapUpdateAllHook [KMap _ _ (Just _), _updates] =
+    -- indeterminate part in original map, leave unevaluated
+    pure Nothing
+mapUpdateAllHook [KMap def pairs1 Nothing, KMap _ pairs2 mbRest2]
+    -- performing the update requires all keys to be fully evaluated
+    -- (constructor-like) or syntactically equal.
+    | Set.null origKeys = -- all keys in the original map were updated (syntactically)
+        pure $ Just $ KMap def updated mbRest2
+    | Set.null updateKeys
+    , Nothing <- mbRest2 = -- all update keys were (syntactically) present
+        pure $ Just $ KMap def updated Nothing
+    | all isConstructorLike_ (updateKeys <> origKeys)
+    , Nothing <- mbRest2 = -- all untouched or added keys are fully evaluated
+        pure $ Just $ KMap def updated Nothing
+    | otherwise = -- uncertain whether all keys updated, leave unevaluated
+        pure Nothing
+  where
+    orig = Map.fromList pairs1
+    update = Map.fromList pairs2
+    updated = Map.assocs $ Map.unionWith (\_ u -> u) orig update
+    origKeys = Set.difference (Map.keysSet orig) (Map.keysSet update)
+    updateKeys = Set.difference (Map.keysSet update) (Map.keysSet orig)
+mapUpdateAllHook [_, _] =
+        pure Nothing -- at least one argument not an internalised map, leave unevaluated
+mapUpdateAllHook args =
+        throwE . renderText $ "MAP.update: wrong arity " <> pretty (length args)
+
 mapRemoveHook :: BuiltinFunction
 mapRemoveHook args
     | [m@(KMap def pairs mbRest), key] <- args = do

docs/hooks.md

@@ -536,6 +536,16 @@ present, replace the associated value with the new value provided.
         [hook{}("MAP.update")]
 ~~~
 
+### MAP.updateAll
+
+Insert all associations from the second map into the first map. If any key 
+is already present in the first map, the associated value is replaced with 
+the new value from the second map.
+
+~~~
+    hooked-symbol updateMap{}(Map{}, Map{}) : Map{}
+        [hook{}("MAP.updateAll")]
+~~~
 ### MAP.remove
 
 Remove the key and the value associated with it from the map. If the key