[PlutusLedgerApi] [Refactoring] Polish imports and exports (#6178)

This

- resolves #6098
- moves a bunch of stuff shared among `V1`/`V2`/`V3` into `Common` (see the PR review)
- makes all imports in the `Common`/`V1`/`V2`/`V3` modules qualified so that it's clear where definitions come from and whether they are inherited from `Common` or an earlier ledger language
- fixes some formatting, adds a definition for consistency etc

plutus-ledger-api/changelog.d/20240606_160839_effectfully_polish_imports_and_exports.md

@@ -0,0 +1,18 @@
+### Added
+
+- Exported the following from `PlutusLedgerApi.Common` in #6178:
+  + `ExCPU (..)`
+  + `ExMemory (..)`
+  + `SatInt (unSatInt)`
+  + `fromSatInt`
+  + `toOpaque,
+  + `fromOpaque`
+  + `BuiltinData (..)`
+  + `ToData (..)`
+  + `FromData (..)`
+  + `UnsafeFromData (..)`
+  + `toData`
+  + `fromData`
+  + `unsafeFromData`
+  + `dataToBuiltinData`
+  + `builtinDataToData`

plutus-ledger-api/exe/analyse-script-events/Main.hs

@@ -34,7 +34,6 @@ import Control.Monad.Writer.Strict
 import Data.Int (Int64)
 import Data.List (find, intercalate)
 import Data.Primitive.PrimArray qualified as P
-import Data.SatInt (fromSatInt)
 import System.Directory.Extra (listFiles)
 import System.Environment (getArgs, getProgName)
 import System.FilePath (isExtensionOf, takeFileName)
@@ -308,8 +307,8 @@ data EvaluationResult =  OK ExBudget | Failed | DeserialisationError
 -- Convert to a string for use in an R frame
 toRString :: EvaluationResult -> String
 toRString = \case
-  OK _ -> "T"
-  Failed -> "F"
+  OK _                 -> "T"
+  Failed               -> "F"
   DeserialisationError -> "NA"
 
 -- Print out the actual and claimed CPU and memory cost of every script.
@@ -471,6 +470,6 @@ main =
               eventFiles -> analysis eventFiles
 
     in getArgs >>= \case
-      [name] -> go name "."
+      [name]      -> go name "."
       [name, dir] -> go name dir
-      _ -> usage
+      _           -> usage

plutus-ledger-api/src/PlutusLedgerApi/Common.hs

@@ -1,73 +1,112 @@
+-- editorconfig-checker-disable-file
+
 -- | The types and functions that are common among all ledger Plutus versions.
-module PlutusLedgerApi.Common
-    ( -- * Script (de)serialization
-      SerialisedScript
-    , ScriptForEvaluation
-    , serialisedScript
-    , deserialisedScript
-    , serialiseCompiledCode
-    , serialiseUPLC
-    , deserialiseScript
-    , uncheckedDeserialiseUPLC
-    , ScriptDecodeError (..)
-    , ScriptNamedDeBruijn (..)
-
-      -- * Script evaluation
-    , evaluateScriptCounting
-    , evaluateScriptRestricting
-    , evaluateTerm
-    , VerboseMode (..)
-    , LogOutput
-    , EvaluationError (..)
-    -- reexport Data & ExBudget for convenience to upstream users
-    , PlutusCore.Data (..)
-    , PlutusCore.ExBudget (..)
-
-      -- * Network's versioning
-      {-| The network's behaviour (and plutus's by extension) can change via /hard forks/,
-      which directly correspond to major-number protocol version bumps.
-      -}
-    , MajorProtocolVersion (..)
-    , PlutusLedgerLanguage (..)
-    , Version (..)
-    , builtinsIntroducedIn
-    , builtinsAvailableIn
-    , ledgerLanguageIntroducedIn
-    , ledgerLanguagesAvailableIn
-
-      -- * Network's costing parameters
-      {-| A less drastic approach (that does not rely on a HF)
-      to affect the network's (and plutus's by extension) behaviour
-      is by tweaking the values of the cost model parameters.
-
-      The network does not associate names to cost model parameters;
-      Plutus attaches names to the network's cost model parameters (values)
-      either in a raw textual form or typed by a specific plutus version.
-
-      See Note [Cost model parameters]
-      -}
-    , CostModelParams
-    , toCostModelParams
-    , assertWellFormedCostModelParams
-    , IsParamName (showParamName, readParamName)
-    , GenericParamName
-    , CostModelApplyError (..)
-    , CostModelApplyWarn (..)
-
-      -- ** Evaluation context
-    , EvaluationContext (..)
-    , mkDynEvaluationContext
-    , toMachineParameters
-    -- While not strictly used by the ledger, this is useful for people trying to
-    -- reconstruct the term evaluated by the ledger from the arguments, e.g.
-    -- for profiling purposes.
-    , mkTermToEvaluate
-    ) where
-
-import PlutusCore.Data as PlutusCore (Data (..))
-import PlutusCore.Evaluation.Machine.CostModelInterface (CostModelParams)
-import PlutusCore.Evaluation.Machine.ExBudget as PlutusCore (ExBudget (..))
-import PlutusLedgerApi.Common.Eval
-import PlutusLedgerApi.Common.ParamName
-import PlutusLedgerApi.Common.SerialisedScript
-import PlutusLedgerApi.Common.Versions
+module PlutusLedgerApi.Common (
+  -- * Script (de)serialization
+  SerialisedScript.SerialisedScript,
+  SerialisedScript.ScriptForEvaluation,
+  SerialisedScript.serialisedScript,
+  SerialisedScript.deserialisedScript,
+  SerialisedScript.serialiseCompiledCode,
+  SerialisedScript.serialiseUPLC,
+  SerialisedScript.deserialiseScript,
+  SerialisedScript.uncheckedDeserialiseUPLC,
+  SerialisedScript.ScriptDecodeError (..),
+  SerialisedScript.ScriptNamedDeBruijn (..),
+
+  -- * Script evaluation
+  Eval.evaluateScriptCounting,
+  Eval.evaluateScriptRestricting,
+  Eval.evaluateTerm,
+  Eval.VerboseMode (..),
+  Eval.LogOutput,
+  Eval.EvaluationError (..),
+
+  -- * Network's versioning
+  {-| The network's behaviour (and plutus's by extension) can change via /hard forks/,
+  which directly correspond to major-number protocol version bumps.
+  -}
+  Versions.MajorProtocolVersion (..),
+  Versions.PlutusLedgerLanguage (..),
+  Versions.Version (..),
+  Versions.builtinsIntroducedIn,
+  Versions.builtinsAvailableIn,
+  Versions.ledgerLanguageIntroducedIn,
+  Versions.ledgerLanguagesAvailableIn,
+
+  -- * Costing-related types
+  PLC.ExBudget (..),
+  PLC.ExCPU (..),
+  PLC.ExMemory (..),
+  SatInt.SatInt (unSatInt),
+  SatInt.fromSatInt,
+
+  -- * Network's costing parameters
+  {-| A less drastic approach (that does not rely on a HF)
+  to affect the network's (and plutus's by extension) behaviour
+  is by tweaking the values of the cost model parameters.
+
+  The network does not associate names to cost model parameters;
+  Plutus attaches names to the network's cost model parameters (values)
+  either in a raw textual form or typed by a specific plutus version.
+
+  See Note [Cost model parameters]
+  -}
+  PLC.CostModelParams,
+  ParamName.toCostModelParams,
+  Eval.assertWellFormedCostModelParams,
+  ParamName.IsParamName (showParamName, readParamName),
+  ParamName.GenericParamName,
+  ParamName.CostModelApplyError (..),
+  ParamName.CostModelApplyWarn (..),
+
+  -- ** Evaluation context
+  Eval.EvaluationContext (..),
+  Eval.mkDynEvaluationContext,
+  Eval.toMachineParameters,
+  -- While not strictly used by the ledger, this is useful for people trying to
+  -- reconstruct the term evaluated by the ledger from the arguments, e.g.
+  -- for profiling purposes.
+  Eval.mkTermToEvaluate,
+
+  -- ** Supporting types used in the context types
+
+  -- *** Builtins
+  TxPrelude.BuiltinByteString,
+  TxPrelude.toBuiltin,
+  TxPrelude.fromBuiltin,
+  TxPrelude.toOpaque,
+  TxPrelude.fromOpaque,
+
+  -- * Data
+  PLC.Data (..),
+  Builtins.BuiltinData (..),
+  IsData.ToData (..),
+  IsData.FromData (..),
+  IsData.UnsafeFromData (..),
+  IsData.toData,
+  IsData.fromData,
+  IsData.unsafeFromData,
+  Builtins.dataToBuiltinData,
+  Builtins.builtinDataToData,
+
+  -- * Misc
+  MonadError,
+) where
+
+import PlutusLedgerApi.Common.Eval qualified as Eval
+import PlutusLedgerApi.Common.ParamName qualified as ParamName
+import PlutusLedgerApi.Common.SerialisedScript qualified as SerialisedScript
+import PlutusLedgerApi.Common.Versions qualified as Versions
+
+import PlutusTx.Builtins.Internal qualified as Builtins
+import PlutusTx.IsData.Class qualified as IsData
+import PlutusTx.Prelude qualified as TxPrelude
+
+import PlutusCore.Data qualified as PLC
+import PlutusCore.Evaluation.Machine.CostModelInterface qualified as PLC
+import PlutusCore.Evaluation.Machine.ExBudget qualified as PLC
+import PlutusCore.Evaluation.Machine.ExMemory qualified as PLC
+
+import Control.Monad.Except (MonadError)
+import Data.SatInt qualified as SatInt