Improve "evaluating plinth" example: clarify application and lifting separately.

Author: Unisay

doc/docusaurus/docs/using-plinth/evaluating-plinth.md

@@ -20,7 +20,19 @@ Let's consider the following example Plinth program:
   start="-- BEGIN Plinth" 
   end="-- END Plinth" />
 
-In order to evaluate this code, we need to add the `plutus-tx:plutus-tx-testlib` 
+This code represents a function that expects an `Integer` argument
+and returns the `Integer` value. 
+
+To compile it, we can use the `compile` function as described earlier in the "[Compiling Plinth code](./compiling-plinth.md)" section:
+
+<LiteralInclude 
+  file="Example/Evaluation/Main.hs" 
+  language="haskell" 
+  title="Plinth code compiled" 
+  start="-- BEGIN CompiledCode" 
+  end="-- END CompiledCode" />
+
+In order to evaluate `compiledCode`, we need to add the `plutus-tx:plutus-tx-testlib` 
 dependency to our cabal file:
 ```cabal
   build-depends:
@@ -38,9 +50,6 @@ import PlutusTx.Test (
  )
 ```
 
-Our example code represents a function that expects an `Integer` argument
-and returns the `Integer` value. 
-
 It is possible to evaluate this compiled code without applying it to any arguments, 
 and evaluation will succeed, returning the value of type `Integer -> Integer`:
 
@@ -140,17 +149,42 @@ No traces were emitted
 This output reveals that the evaluation was successful, and the resultng UPLC 
 value is an (un-applied) lambda abstraction. 
 
-The [Lifting Values into CompiledCode](./lifting.md) section contains and example 
-of applying the `CompiledCode` to an argument.
+To apply the compiled lambda abstraction to an argument we need to have a compiled argument, 
+and there are several ways of obtaining it from a Haskell value known at compile time:
+1. "lift" it into `CompiledCode`. See the [Lifting Values into CompiledCode](./lifting.md) section for more details.
+    <LiteralInclude 
+      file="Example/Evaluation/Main.hs" 
+      language="haskell" 
+      title="Lift a constant value into CompiledCode" 
+      start="-- BEGIN LiftedArgument" 
+      end="-- END LiftedArgument" />
+
+2. `$(compile [|| ... ||])` it the same way we compiled the function itself.
+    <LiteralInclude 
+      file="Example/Evaluation/Main.hs" 
+      language="haskell" 
+      title="Compile a constant value into CompiledCode" 
+      start="-- BEGIN CompiledArgument" 
+      end="-- END CompiledArgument" />
+
+Once we have an argument of type `CompiledCode a`, we can apply it to the compiled function
+using either the [`applyCode`](https://plutus.cardano.intersectmbo.org/haddock/latest/plutus-tx/PlutusTx-Code.html#v:applyCode) function 
+
+<LiteralInclude 
+  file="Example/Evaluation/Main.hs" 
+  language="haskell" 
+  title="Applying compiled function to an argument (type-safe way)" 
+  start="-- BEGIN SafeApplicationResult" 
+  end="-- END SafeApplicationResult" />
 
-Alternatively, we can use the imported `applyLifted` function like this:
+or the [`unsafeApplyCode`](https://plutus.cardano.intersectmbo.org/haddock/latest/plutus-tx/PlutusTx-Code.html#v:unsafeApplyCode) function.
 
 <LiteralInclude 
   file="Example/Evaluation/Main.hs" 
   language="haskell" 
-  title="How to apply compiled function to a lifted argument" 
-  start="-- BEGIN AppliedResult" 
-  end="-- END AppliedResult" />
+  title="Applying compiled function to an argument (unsafe way)" 
+  start="-- BEGIN UnsafeApplicationResult" 
+  end="-- END UnsafeApplicationResult" />
 
 Lets print the result of the evaluation:
 

doc/docusaurus/static/code/Example/Evaluation/Main.hs

@@ -3,29 +3,35 @@
 {-# LANGUAGE NoImplicitPrelude   #-}
 {-# LANGUAGE OverloadedStrings   #-}
 {-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TemplateHaskell     #-}
 {-# LANGUAGE TypeApplications    #-}
 {-# OPTIONS_GHC -fplugin PlutusTx.Plugin #-}
 {-# OPTIONS_GHC -fplugin-opt PlutusTx.Plugin:target-version=1.1.0 #-}
 
 module Main where
 
-import Data.Proxy (Proxy (..))
-import Data.Text.IO qualified as Text
-import PlutusTx
-import PlutusTx.Plugin (plc)
 import PlutusTx.Prelude
-import Prelude (IO)
 
-import PlutusTx.Test (EvalResult, applyLifted, evaluateCompiledCode, prettyEvalResult)
+import Data.Text.IO qualified as Text
+import PlutusTx (CompiledCode, applyCode, compile, liftCodeDef, unsafeApplyCode)
+import Prelude (IO, String)
+
+import PlutusTx.Test (EvalResult, evaluateCompiledCode, prettyEvalResult)
 
 -- BEGIN Plinth
+
 plinthCode :: Integer -> Integer
 plinthCode x = trace "Evaluating x" x + trace "Evaluating constant" 2
 
-compiledCode :: CompiledCode (Integer -> Integer)
-compiledCode = plc (Proxy @"plinth") plinthCode
 -- END Plinth
 
+-- BEGIN CompiledCode
+
+compiledCode :: CompiledCode (Integer -> Integer)
+compiledCode = $$(compile [||plinthCode||])
+
+-- END CompiledCode
+
 {-
 EvalResult
     { evalResult = Right
@@ -45,12 +51,43 @@ EvalResult
     }
 -}
 
--- BEGIN AppliedResult
+-- BEGIN CompiledArgument
+
+argumentCompiled :: CompiledCode Integer
+argumentCompiled = $$(compile [||2||])
+
+-- END CompiledArgument
+
+-- BEGIN LiftedArgument
+
+argumentLifted :: CompiledCode Integer
+argumentLifted = liftCodeDef 2
+
+-- END LiftedArgument
+
+-- BEGIN SafeApplicationResult
+
+errorOrResult :: Either String EvalResult
+errorOrResult = fmap evaluateCompiledCode appliedSafely
+ where
+  appliedSafely :: Either String (CompiledCode Integer)
+  appliedSafely = compiledCode `applyCode` argumentLifted
+
+-- END SafeApplicationResult
+
+-- BEGIN UnsafeApplicationResult
+
 result :: EvalResult
-result = evaluateCompiledCode $ compiledCode `applyLifted` 2
--- END AppliedResult
+result = evaluateCompiledCode appliedUnsafely
+ where
+  appliedUnsafely :: CompiledCode Integer
+  appliedUnsafely = compiledCode `unsafeApplyCode` argumentCompiled
+
+-- END UnsafeApplicationResult
 
 -- BEGIN main
+
 main :: IO ()
 main = Text.putStrLn $ prettyEvalResult result
+
 -- END main