Add documentation for DAML repl and advertise it (digital-asset#4678)

* Add documentation for DAML repl and advertise it This PR adds some simple docs for ``daml repl`` and adds it to the release notes. changelog_begin - [DAML Repl - Experimental] A new ``daml repl`` command that allows you to use the ``DAML Script`` API interactively. Take a look at the `documentation <https://docs.daml.com/daml-repl/>`_ for more information. changelog_end * Update docs/source/daml-repl/index.rst Co-Authored-By: Andreas Herrmann <42969706+aherrmann-da@users.noreply.github.com> * s/Repl/REPL/ Co-authored-by: Andreas Herrmann <42969706+aherrmann-da@users.noreply.github.com>
axman6 · Feb 25, 2020 · 38b7e65 · 38b7e65
1 parent 731b2c5
commit 38b7e65
Show file tree

Hide file tree

Showing 6 changed files with 133 additions and 4 deletions.
diff --git a/compiler/damlc/lib/DA/Cli/Damlc.hs b/compiler/damlc/lib/DA/Cli/Damlc.hs
@@ -252,16 +252,17 @@ cmdBuild numProcessors =
 
 cmdRepl :: Int -> Mod CommandFields Command
 cmdRepl numProcessors =
-    command "repl" $
-    info (helper <*> cmd) fullDesc
+    command "repl" $ info (helper <*> cmd) $
+    progDesc "Launch the DAML REPL." <>
+    fullDesc
   where
     cmd =
         execRepl
             <$> projectOpts "daml build"
             <*> optionsParser numProcessors (EnableScenarioService False) (pure Nothing)
             <*> strOption (long "script-lib" <> value "daml-script" <> internal)
             -- ^ This is useful for tests and `bazel run`.
-            <*> strArgument (help "DAR to load in the repl")
+            <*> strArgument (help "DAR to load in the repl" <> metavar "DAR")
             <*> strOption (long "ledger-host" <> help "Host of the ledger API")
             <*> strOption (long "ledger-port" <> help "Port of the ledger API")
 
@@ -598,6 +599,8 @@ execBuild projectOpts opts mbOutFile incrementalBuild initPkgDb =
 execRepl :: ProjectOpts -> Options -> FilePath -> FilePath -> String -> String -> Command
 execRepl projectOpts opts scriptDar mainDar ledgerHost ledgerPort = Command Repl (Just projectOpts) effect
   where effect = do
+            -- We change directory so make this absolute
+            mainDar <- makeAbsolute mainDar
             opts <- pure opts
                 { optDlintUsage = DlintDisabled
                 , optScenarioService = EnableScenarioService False
@@ -1000,6 +1003,7 @@ options numProcessors =
       <> cmdInspectDar
       <> cmdDocTest numProcessors
       <> cmdLint numProcessors
+      <> cmdRepl numProcessors
       )
     <|> subparser
       (internal -- internal commands
@@ -1013,7 +1017,6 @@ options numProcessors =
         <> cmdClean
         <> cmdGenerateSrc numProcessors
         <> cmdGenerateGenSrc
-        <> cmdRepl numProcessors
         -- once the repl is a bit more mature, make it non-internal
         -- and modify sdk-config.yaml to add a description.
       )

diff --git a/docs/configs/pdf/index.rst b/docs/configs/pdf/index.rst
@@ -95,6 +95,7 @@ Experimental features
    json-api/index
    triggers/index
    daml-script/index
+   daml-repl/index
    tools/visual
    daml2ts/index
    getting-started/index

diff --git a/docs/source/daml-repl/index.rst b/docs/source/daml-repl/index.rst
@@ -0,0 +1,121 @@
+.. Copyright (c) 2020 The DAML Authors. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+
+DAML REPL
+###########
+
+**WARNING:** DAML REPL is an experimental feature that is actively
+being designed and is *subject to breaking changes*.
+We welcome feedback about the DAML REPL on
+`our issue tracker <https://github.com/digital-asset/daml/issues/new>`_
+or `on Slack <https://hub.daml.com/slack/>`_.
+
+The DAML REPL allows you to use the :doc:`/daml-script/index` API
+interactively. This is useful for debugging and for interactively
+inspecting and manipulating a ledger.
+
+Usage
+=====
+
+First create a new project based on the ``script-example``
+template. Take a look at the documentation for
+:doc:`/daml-script/index` for details on this template.
+
+.. code-block:: sh
+
+   daml new script-example script-example # create a project called script-example based on the template
+   cd script-example # switch to the new project
+
+Now, build the project and start :doc:`/tools/sandbox`, the in-memory
+ledger included in the DAML SDK. Note that we are starting Sandbox in
+wallclock mode. Static time is not supported in ``daml repl``.
+
+.. code-block:: sh
+
+   daml build
+   daml sandbox --wall-clock-time --port=6865 .daml/dist/script-example-0.0.1.dar
+
+Now that the ledger has been started, you can launch the REPL in a
+separate terminal using the following command.
+
+.. code-block:: sh
+
+   daml repl --ledger-host=localhost --ledger-port=6865 .daml/dist/script-example-0.0.1.dar
+
+The ``--ledger-host`` and ``--ledger-port`` parameters point to the
+host and port your ledger is running on. In addition to that, you also
+need to pass in the name of a DAR containing the templates and other
+definitions that will be accessible in the REPL.
+
+You should now see a prompt looking like
+
+.. code-block:: none
+
+   daml>
+
+You can think of this prompt like a line in a ``do``-block of the
+``Script`` action. Each line of input has to have one of the following
+two forms:
+
+1. An expression ``expr`` of type ``Script a`` for some type ``a``. This
+   will execute the script ignoring the result.
+
+2. A binding of the form ``x <- expr`` where ``x`` is a variable name
+   and ``expr`` is an expression of type ``Script a``. This will
+   execute the script and bind the result to the variable ``x``. You
+   can then use ``x`` on subsequent lines.
+
+First create two parties: A party with the display name ``"Alice"``
+and the party id ``"alice"`` and a party with the display name
+``"Bob"`` and the party id ``"bob"``.
+
+.. code-block:: none
+
+   daml> alice <- allocatePartyWithHint "Alice" (PartyIdHint "alice")
+   daml> bob <- allocatePartyWithHint "Bob" (PartyIdHint "bob")
+
+Next, create a ``CoinProposal`` from ``Alice`` to ``Bob``
+
+.. code-block:: none
+
+   daml> submit alice (createCmd (CoinProposal (Coin alice bob)))
+
+As Bob, you can now get the list of active ``CoinProposal`` contracts
+using the ``query`` function. The ``debug : Show a => a -> Script ()``
+function can be used to print values.
+
+.. code-block:: none
+
+   daml> proposals <- query @CoinProposal bob
+   daml> debug proposals
+   [Daml.Script:39]: [(<contract-id>,CoinProposal {coin = Coin {issuer = 'alice', owner = 'bob'}})]
+
+Finally, accept all proposals using the ``forA`` function to iterate
+over them.
+
+.. code-block:: none
+
+   daml> forA proposals $ \(contractId, _) -> submit bob (exerciseCmd contractId Accept)
+
+Using the ``query`` function we can now verify that there is one
+``Coin`` and no ``CoinProposal``:
+
+.. code-block:: none
+
+   daml> coins <- query @Coin bob
+   daml> debug coins
+   [Daml.Script:39]: [(<contract-id>,Coin {issuer = 'alice', owner = 'bob'})]
+   daml> proposals <- query @CoinProposal bob
+   [Daml.Script:39]: []
+
+To exit ``daml repl`` press ``Control-D``.
+
+
+What is in scope at the prompt?
+===============================
+
+In the prompt, all modules from the main dalf of the DAR passed to
+``daml repl`` are imported. In addition to that the ``Daml.Script``
+module is imported and gives you access to the DAML Script API.
+
+At this point, it is not possible to import more modules.
diff --git a/docs/source/daml-script/index.rst b/docs/source/daml-script/index.rst
@@ -28,6 +28,8 @@ actual ledger. This means that you can use it to test automation
 logic, your UI but also for ledger initialization where scenarios
 cannot be used (with the exception of :doc:`/tools/sandbox`).
 
+You can also use DAML Script interactively using :doc:`/daml-repl/index`.
+
 Usage
 =====
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -100,6 +100,7 @@ DAML SDK documentation
    json-api/index
    DAML Triggers <triggers/index>
    DAML Script <daml-script/index>
+   DAML Repl <daml-repl/index>
    tools/visual
    daml2ts/index
    getting-started/index

diff --git a/release/sdk-config.yaml.tmpl b/release/sdk-config.yaml.tmpl
@@ -92,3 +92,4 @@ commands:
 - name: repl
   path: damlc/damlc
   args: ["repl"]
+  desc: "Launch the DAML REPL (experimental)"
-Original file line number
+Diff line change
@@ Expand Up @@
     logic, your UI but also for ledger initialization where scenarios
     cannot be used (with the exception of :doc:`/tools/sandbox`).
+    You can also use DAML Script interactively using :doc:`/daml-repl/index`.
     Usage
     =====
@@ Expand Down @@