Skip to content

Commit

Permalink
Generate API docs for DAML script and include them in the SDK docs (d…
Browse files Browse the repository at this point in the history
…igital-asset#3568)

* Generate API docs for DAML script and include them in the SDK docs

* Update daml-script/daml/Daml/Script.daml

Co-Authored-By: Martin Huschenbett <martin.huschenbett@posteo.me>
cocreature and hurryabit authored Nov 21, 2019
1 parent 55dfe96 commit ec5d832
Showing 5 changed files with 67 additions and 2 deletions.
16 changes: 16 additions & 0 deletions daml-script/daml/BUILD.bazel
Original file line number Diff line number Diff line change
@@ -28,3 +28,19 @@ EOF
tools = ["//compiler/damlc"],
visibility = ["//visibility:public"],
)

genrule(
name = "daml-script-rst-docs",
srcs = glob(["**/*.daml"]) + [":daml-script-rst-template.rst"],
outs = ["daml-script.rst"],
cmd = """
$(location //compiler/damlc) -- docs \
--combine \
--output=$(location :daml-script.rst) \
--format=Rst \
--template=$(location :daml-script-rst-template.rst) \
$(location Daml/Script.daml)
""",
tools = ["//compiler/damlc"],
visibility = ["//visibility:public"],
)
33 changes: 31 additions & 2 deletions daml-script/daml/Daml/Script.daml
Original file line number Diff line number Diff line change
@@ -2,8 +2,18 @@
-- SPDX-License-Identifier: Apache-2.0

daml 1.2
module Daml.Script where

module Daml.Script
( Script
, submit
, submitMustFail
, query
, allocateParty
, Commands
, createCmd
, exerciseCmd
) where

import Prelude hiding (submit, submitMustFail)
import DA.Optional

-- | A free monad
@@ -45,6 +55,11 @@ data CommandsF a
| Exercise { tplId : TemplateTypeRep, cId : ContractId (), argE : AnyChoice, continueE : LedgerValue -> a }
deriving Functor

-- | This is used to build up the commands send as part of `submit`.
-- If you enable the `ApplicativeDo` extension by adding
-- `{-# LANGUAGE ApplicativeDo #-}` at the top of your file, you can
-- use `do`-notation but the individual commands must not depend
-- on each other.
newtype Commands a = Commands (Ap CommandsF a)
deriving (Functor, Applicative)

@@ -60,6 +75,8 @@ data QueryACS a = QueryACS
, continue : [(ContractId (), AnyTemplate)] -> a
} deriving Functor

-- | Query the set of active contracts of the template
-- that are visible to the given party.
query : forall t. Template t => Party -> Script [(ContractId t, t)]
query p = Script $ Free $ Query (QueryACS p (templateTypeRep @t) (pure . map (\(cid, tpl) -> (coerceContractId cid, fromSome $ fromAnyTemplate tpl))))

@@ -68,6 +85,8 @@ data AllocateParty a = AllocateParty
, continue : Party -> a
} deriving Functor

-- | Allocate a party with the given display name
-- using the party management service.
allocateParty : Text -> Script Party
allocateParty displayName = Script $ Free (AllocParty $ AllocateParty displayName pure)

@@ -79,14 +98,22 @@ data SubmitFailure = SubmitFailure
data SubmitCmd a = SubmitCmd { party : Party, commands : Commands a, handleFailure : SubmitFailure -> a }
deriving Functor

-- | Submit the commands as a single transaction.

-- This will error if the submission fails.
submit : Party -> Commands a -> Script a
submit p cmds = Script $ Free (fmap pure $ Submit $ SubmitCmd p cmds fail)
where fail (SubmitFailure status msg) = error $ "Submit failed with code " <> show status <> ": " <> msg

-- | Submit the commands as a single transaction
-- but error if it succeeds. This is only
-- useful for testing.
submitMustFail : Party -> Commands a -> Script ()
submitMustFail p cmds = Script $ Free (fmap pure $ Submit $ SubmitCmd p (fail <$> cmds) (const ()))
where fail _ = error "Expected submit to fail but it succeeded"

-- | This is the type of A DAML script. `Script` is an instance of `Action`,
-- so you can use `do` notation.
newtype Script a = Script (Free ScriptF a)
deriving (Functor, Applicative, Action)

@@ -98,8 +125,10 @@ data LedgerValue = LedgerValue {}
fromLedgerValue : LedgerValue -> a
fromLedgerValue = error "foobar"

-- | Create a contract of the given template.
createCmd : Template t => t -> Commands (ContractId t)
createCmd arg = Commands $ Ap (\f -> f (Create (toAnyTemplate arg) identity) (pure coerceContractId))

-- | Exercise a choice on the given contract.
exerciseCmd : forall t c r. Choice t c r => ContractId t -> c -> Commands r
exerciseCmd cId arg = Commands $ Ap (\f -> f (Exercise (templateTypeRep @t) (coerceContractId cId) (toAnyChoice @t arg) identity) (pure fromLedgerValue))
11 changes: 11 additions & 0 deletions daml-script/daml/daml-script-rst-template.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
.. Copyright (c) 2019 The DAML Authors. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
.. _daml-script-api-docs:

DAML Script Library
====================

The DAML Script library defines the API used to implement DAML scripts. See :doc:`index`:: for more information on DAML script.

{{{body}}}
4 changes: 4 additions & 0 deletions docs/BUILD.bazel
Original file line number Diff line number Diff line change
@@ -80,6 +80,7 @@ genrule(
srcs = glob(["source/**"]) + [
"//compiler/damlc:daml-base-rst-docs",
"//triggers/daml:daml-trigger-rst-docs",
"//daml-script/daml:daml-script-rst-docs",
"//ledger-api/grpc-definitions:docs",
"//:LICENSE",
"//:NOTICES",
@@ -94,6 +95,9 @@ genrule(
# Copy in daml-trigger documentation
cp -rL $(location //triggers/daml:daml-trigger-rst-docs) source/triggers/trigger-docs.rst
# Copy in daml-script documentation
cp -rL $(location //daml-script/daml:daml-script-rst-docs) source/daml-script/daml-script-docs.rst
# Copy in Protobufs
cp -rL $(location //ledger-api/grpc-definitions:docs) source/app-dev/grpc/proto-docs.rst
5 changes: 5 additions & 0 deletions docs/source/daml-script/index.rst
Original file line number Diff line number Diff line change
@@ -4,6 +4,11 @@
DAML Script
###########

.. toctree::
:hidden:

daml-script-docs

**WARNING:** DAML Script is an experimental feature that is actively
being designed and is *subject to breaking changes*.
We welcome feedback about DAML script on

0 comments on commit ec5d832

Please sign in to comment.