prettyBlackBox: Correctly escape [ and ]

The way that way that blackboxes of function arguments to higher order
blackboxes are handled is somewhat weird.

For historical reasons, they are parsed, pretty-printed, later re-parsed
again. However, the pretty-printer failed to correctly re-escape
previously escaped square brackets, resulting in the generation of
invalid HDL, as seen in #2809.

Fixes #2809.
Fixes #2988.

Author: bgamari

changelog/2025-08-18T20_57_06+02_00_fix_2988_2809

@@ -0,0 +1,2 @@
+FIXED: Verilog and System Verilog code gen bug for `map head` [#2809](https://github.com/clash-lang/clash-compiler/issues/2809)
+FIXED: Error parsing blackbox: `Clash.Sized.Vector.head` [#2988](https://github.com/clash-lang/clash-compiler/issues/2988)

clash-lib/src/Clash/Netlist/BlackBox/Parser.hs

@@ -150,8 +150,8 @@ pElemE = pTagE
 
 -- | Parse SigD
 pSigD :: Parser [Element]
-pSigD = some (pTagE <|> (Text (pack "[") <$ (pack <$> string "[\\"))
-                    <|> (Text (pack "]") <$ (pack <$> string "\\]"))
+pSigD = some (pTagE <|> (EscapedSymbol SquareBracketOpen <$ string "[\\")
+                    <|> (EscapedSymbol SquareBracketClose <$ string "\\]")
                     <|> (Text <$> (pack <$> some (satisfyRange '\000' '\90')))
                     <|> (Text <$> (pack <$> some (satisfyRange '\94' '\125'))))
 

clash-lib/src/Clash/Netlist/BlackBox/Types.hs

@@ -19,6 +19,7 @@ module Clash.Netlist.BlackBox.Types
  , BlackBoxTemplate
  , TemplateKind (..)
  , Element(..)
+ , EscapedSymbol(..)
  , Decl(..)
  , HdlSyn(..)
  , RenderVoid(..)
@@ -211,6 +212,12 @@ data Element
   | CtxName
   -- ^ The "context name", name set by `Clash.Magic.setName`, defaults to the
   -- name of the closest binder
+  | EscapedSymbol EscapedSymbol
+  -- ^ Used for "[\" and "\]", they'll be rendered as "[" and "]",
+  -- but pretty printed as "[\" and "\]".
+  deriving (Show, Generic, NFData, Binary, Eq, Hashable)
+
+data EscapedSymbol = SquareBracketOpen | SquareBracketClose
   deriving (Show, Generic, NFData, Binary, Eq, Hashable)
 
 -- | Component instantiation hole. First argument indicates which function argument

clash-lib/src/Clash/Netlist/BlackBox/Util.hs

@@ -140,6 +140,7 @@ inputHole = \case
   DevNull _        -> Nothing
   SigD _ nM        -> nM
   CtxName          -> Nothing
+  EscapedSymbol _  -> Nothing
 
 -- | Determine if the number of normal\/literal\/function inputs of a blackbox
 -- context at least matches the number of argument that is expected by the
@@ -923,6 +924,9 @@ renderTag b CtxName = case bbCtxName b of
     -> return (Id.toLazyText t)
   _ -> error "internal error"
 
+renderTag _ (EscapedSymbol sym) = case sym of
+  SquareBracketOpen  -> return "["
+  SquareBracketClose -> return "]"
 
 renderTag _ e = do e' <- getAp (prettyElem e)
                    error $ $(curLoc) ++ "Unable to evaluate: " ++ show e'
@@ -1127,6 +1131,9 @@ prettyElem (Template bbname source) = do
                                   <> brackets (string $ Text.concat bbname')
                                   <> brackets (string $ Text.concat source'))
 prettyElem CtxName = return "~CTXNAME"
+prettyElem (EscapedSymbol sym) = case sym of
+  SquareBracketOpen  -> return "[\\"
+  SquareBracketClose -> return "\\]"
 
 -- | Recursively walk @Element@, applying @f@ to each element in the tree.
 walkElement
@@ -1197,6 +1204,7 @@ walkElement f el = maybeToList (f el) ++ walked
         Repeat es1 es2 ->
           concatMap go es1 ++ concatMap go es2
         CtxName -> []
+        EscapedSymbol _ -> []
 
 -- | Determine variables used in an expression. Used for VHDL sensitivity list.
 -- Also see: https://github.com/clash-lang/clash-compiler/issues/365
@@ -1285,6 +1293,7 @@ getUsedArguments (N.BBTemplate t) = nub (concatMap (walkElement matchArg) t)
         TypM _ -> Nothing
         Vars _ -> Nothing
         CtxName -> Nothing
+        EscapedSymbol _ -> Nothing
 
 onBlackBox
   :: (BlackBoxTemplate -> r)

tests/Main.hs

@@ -668,6 +668,7 @@ runClashTest = defaultMain
         , runTest "T2845" def{hdlSim=[],hdlTargets=[Verilog]}
         , runTest "T2904" def
         , runTest "T2966" def{hdlSim=[],hdlTargets=[Verilog]}
+        , runTest "T2988" def{hdlSim=[]}
         ] <>
         if compiledWith == Cabal then
           -- This tests fails without environment files present, which are only

tests/shouldwork/Issues/T2988.hs

@@ -0,0 +1,15 @@
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE CPP #-}
+
+module T2988 where
+
+import Clash.Prelude
+import Prelude ()
+
+topEntity :: Signal System (Vec 4 (Vec 4 (Unsigned 32))) -> Signal System (Vec 4 (Unsigned 32))
+topEntity = f
+{-# CLASH_OPAQUE topEntity #-}
+
+f :: Signal System (Vec n (Vec 4 (Unsigned 32))) -> Signal System (Vec n (Unsigned 32))
+f x = fmap (fmap head) x
+{-# CLASH_OPAQUE f #-}