Extend daml new to accept template as an option (#6877)

* Extend `daml new` to accept template as an option

The two positional arguments keep confusing users so this PR changes
things to allow the template to be passed via `--template`. Using a
positional argument still works so this is not breaking.

I’ve updated all docs to use the less confusing syntax.

changelog_begin

- [DAML Assistant] You can now use ``daml new project-name
  --template=template-name`` instead of ``daml new project-name
  template-name``. The old CLI syntax continues to be supported.

changelog_end

* Update docs/source/getting-started/index.rst

Co-authored-by: Martin Huschenbett <martin.huschenbett@posteo.me>

Co-authored-by: Martin Huschenbett <martin.huschenbett@posteo.me>

daml-assistant/daml-helper/src/DA/Daml/Helper/Main.hs

@@ -129,11 +129,19 @@ commandParser = subparser $ fold
         <*> strOption (long "logback-config")
         <*> stdinCloseOpt
 
-    newCmd = asum
+    newCmd =
+        let tplOpts :: HasMetavar a => Mod a String
+            tplOpts =
+                metavar "TEMPLATE" <>
+                help ("Name of the template used to create the project (default: " <> defaultProjectTemplate <> ")")
+        in asum
         [ ListTemplates <$ flag' () (long "list" <> help "List the available project templates.")
         , New
             <$> argument str (metavar "TARGET_PATH" <> help "Path where the new project should be located")
-            <*> optional (argument str (metavar "TEMPLATE" <> help ("Name of the template used to create the project (default: " <> defaultProjectTemplate <> ")")))
+            <*> optional
+                  (strOption (long "template" <> tplOpts) <|>
+                   argument str tplOpts
+                  )
         ]
 
     createDamlAppCmd =

daml-assistant/integration-tests/src/DA/Daml/Assistant/CreateDamlAppTests.hs

@@ -59,7 +59,7 @@ tests =
       withTempDir $ \tmpDir -> do
         step "Create app from template"
         withCurrentDirectory tmpDir $ do
-          callCommandSilent $ "daml new " <> projectName <> " create-daml-app"
+          callCommandSilent $ "daml new " <> projectName <> " --template create-daml-app"
         let cdaDir = tmpDir </> projectName
         -- First test the base application (without the user-added feature).
         withCurrentDirectory cdaDir $ do

daml-assistant/integration-tests/src/DA/Daml/Assistant/IntegrationTests.hs

@@ -82,13 +82,13 @@ packagingTests :: TestTree
 packagingTests = testGroup "packaging"
      [ testCase "Build copy trigger" $ withTempDir $ \tmpDir -> do
         let projDir = tmpDir </> "copy-trigger"
-        callCommandSilent $ unwords ["daml", "new", projDir, "copy-trigger"]
+        callCommandSilent $ unwords ["daml", "new", projDir, "--template=copy-trigger"]
         withCurrentDirectory projDir $ callCommandSilent "daml build"
         let dar = projDir </> ".daml" </> "dist" </> "copy-trigger-0.0.1.dar"
         assertFileExists dar
      , testCase "Build copy trigger with LF version 1.dev" $ withTempDir $ \tmpDir -> do
         let projDir = tmpDir </> "copy-trigger"
-        callCommandSilent $ unwords ["daml", "new", projDir, "copy-trigger"]
+        callCommandSilent $ unwords ["daml", "new", projDir, "--template=copy-trigger"]
         withCurrentDirectory projDir $ callCommandSilent "daml build --target 1.dev"
         let dar = projDir </> ".daml" </> "dist" </> "copy-trigger-0.0.1.dar"
         assertFileExists dar
@@ -133,13 +133,13 @@ packagingTests = testGroup "packaging"
         assertFileExists dar
      , testCase "Build DAML script example" $ withTempDir $ \tmpDir -> do
         let projDir = tmpDir </> "script-example"
-        callCommandSilent $ unwords ["daml", "new", projDir, "script-example"]
+        callCommandSilent $ unwords ["daml", "new", projDir, "--template=script-example"]
         withCurrentDirectory projDir $ callCommandSilent "daml build"
         let dar = projDir </> ".daml/dist/script-example-0.0.1.dar"
         assertFileExists dar
      , testCase "Build DAML script example with LF version 1.dev" $ withTempDir $ \tmpDir -> do
         let projDir = tmpDir </> "script-example"
-        callCommandSilent $ unwords ["daml", "new", projDir, "script-example"]
+        callCommandSilent $ unwords ["daml", "new", projDir, "--template=script-example"]
         withCurrentDirectory projDir $ callCommandSilent "daml build --target 1.dev"
         let dar = projDir </> ".daml/dist/script-example-0.0.1.dar"
         assertFileExists dar
@@ -366,7 +366,7 @@ packagingTests = testGroup "packaging"
 quickstartTests :: FilePath -> FilePath -> TestTree
 quickstartTests quickstartDir mvnDir = testGroup "quickstart"
     [ testCase "daml new" $
-          callCommandSilent $ unwords ["daml", "new", quickstartDir, "quickstart-java"]
+          callCommandSilent $ unwords ["daml", "new", quickstartDir, "--template=quickstart-java"]
     , testCase "daml build" $ withCurrentDirectory quickstartDir $
           callCommandSilent "daml build"
     , testCase "daml test" $ withCurrentDirectory quickstartDir $
@@ -536,7 +536,7 @@ cleanTests baseDir = testGroup "daml clean"
                 createDirectoryIfMissing True baseDir
                 withCurrentDirectory baseDir $ do
                     let projectDir = baseDir </> ("proj-" <> templateName)
-                    callCommandSilent $ unwords ["daml", "new", projectDir, templateName]
+                    callCommandSilent $ unwords ["daml", "new", projectDir, "--template", templateName]
                     withCurrentDirectory projectDir $ do
                         filesAtStart <- sort <$> listFilesRecursive "."
                         callCommandSilent "daml build"
@@ -553,15 +553,23 @@ cleanTests baseDir = testGroup "daml clean"
                                 ]
 
 templateTests :: TestTree
-templateTests = testGroup "templates"
+templateTests = testGroup "templates" $
     [ testCase name $ do
           withTempDir $ \dir -> withCurrentDirectory dir $ do
-              callCommandSilent $ unwords ["daml", "new", "foobar", name]
+              callCommandSilent $ unwords ["daml", "new", "foobar", "--template", name]
               withCurrentDirectory (dir </> "foobar") $ callCommandSilent "daml build"
     | name <- templateNames
+    ] <>
+    [ testCase "quickstart-java, positional template" $ do
+          -- Verify that the old syntax for `daml new` still works.
+          withTempDir $ \dir -> withCurrentDirectory dir $ do
+              callCommandSilent "daml new foobar quickstart-java"
+              contents <- readFileUTF8 "foobar/daml.yaml"
+              assertInfixOf "name: quickstart" contents
     ]
 
 
+
   -- NOTE (MK) We might want to autogenerate this list at some point but for now
   -- this should be good enough.
   where templateNames =
@@ -593,7 +601,7 @@ codegenTests codegenDir = testGroup "daml codegen" (
                 createDirectoryIfMissing True codegenDir
                 withCurrentDirectory codegenDir $ do
                     let projectDir = codegenDir </> ("proj-" ++ lang)
-                    callCommandSilent $ unwords ["daml new", projectDir, "skeleton"]
+                    callCommandSilent $ unwords ["daml new", projectDir, "--template=skeleton"]
                     withCurrentDirectory projectDir $ do
                         callCommandSilent "daml build"
                         let darFile = projectDir </> ".daml/dist/proj-" ++ lang ++ "-0.0.1.dar"

docs/source/app-dev/bindings-java/quickstart.rst

@@ -27,7 +27,7 @@ Download the quickstart application
 
 You can get the quickstart application using the DAML assistant (``daml``):
 
-#. Run ``daml new quickstart quickstart-java``
+#. Run ``daml new quickstart --template quickstart-java``
 
    This creates the ``quickstart-java`` application into a new folder called ``quickstart``.
 #. Run ``cd quickstart`` to change into the new directory.

docs/source/app-dev/bindings-ts/daml2js.rst

@@ -20,7 +20,7 @@ Here's a complete example on a project built from the standard "skeleton" templa
 .. code-block:: bash
    :linenos:
 
-   daml new my-proj skeleton # Create a new project based off the skeleton template
+   daml new my-proj --template skeleton # Create a new project based off the skeleton template
    cd my-proj # Enter the newly created project directory
    daml build  # Compile the project's DAML files into a DAR
    daml codegen js -o daml.js .daml/dist/my-proj-0.0.1.dar # Generate JavaScript packages in the daml.js directory

docs/source/daml-repl/index.rst

@@ -17,7 +17,7 @@ template. Take a look at the documentation for
 
 .. code-block:: sh
 
-   daml new script-example script-example # create a project called script-example based on the template
+   daml new script-example --template 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

docs/source/daml/intro/0_Intro.rst

@@ -8,7 +8,7 @@ DAML is a smart contract language designed to build composable applications on a
 
 In this introduction, you will learn about the structure of a DAML Ledger, and how to write DAML applications that run on any DAML Ledger implementation, by building an asset-holding and -trading application. You will gain an overview over most important language features, how they relate to the :ref:`da-ledgers` and how to use the DAML SDK Tools to write, test, compile, package and ship your application.
 
-This introduction is structured such that each section presents a new self-contained application with more functionality than that from the previous section. You can find the DAML code for each section `here <https://github.com/digital-asset/daml/tree/master/docs/source/daml/intro/daml>`_ or download them using the DAML assistant. For example, to download the sources for section 1 into a folder called ``1_Token``, run ``daml new 1_Token daml-intro-1``.
+This introduction is structured such that each section presents a new self-contained application with more functionality than that from the previous section. You can find the DAML code for each section `here <https://github.com/digital-asset/daml/tree/master/docs/source/daml/intro/daml>`_ or download them using the DAML assistant. For example, to download the sources for section 1 into a folder called ``1_Token``, run ``daml new 1_Token --template daml-intro-1``.
 
 Prerequisites:
 

docs/source/daml/patterns.rst

@@ -6,7 +6,7 @@ Good design patterns
 
 Patterns have been useful in the programming world, as both a source of design inspiration, and a document of good design practices. This document is a catalog of DAML patterns intended to provide the same facility in the DA/DAML application world.
 
-You can checkout the examples locally via ``daml new daml-patterns daml-patterns``.
+You can checkout the examples locally via ``daml new daml-patterns --template daml-patterns``.
 
 :doc:`patterns/initaccept`
     The Initiate and Accept pattern demonstrates how to start a bilateral workflow. One party initiates by creating a proposal or an invite contract. This gives another party the chance to accept, reject or renegotiate.

docs/source/getting-started/index.rst

@@ -46,9 +46,11 @@ We'll start by getting the app up and running, and then explain the different co
 First off, open a terminal and instantiate the template project.
 ::
 
-    daml new create-daml-app create-daml-app
+    daml new create-daml-app --template create-daml-app
+
+This creates a new folder with contents from our template. To see
+a list of all available templates run ``daml new --list``.
 
-This creates a new folder with contents from our template.
 Change to the new folder::
 
     cd create-daml-app

docs/source/json-api/index.rst

@@ -138,7 +138,7 @@ Example session
 
 .. code-block:: shell
 
-    $ daml new iou-quickstart-java quickstart-java
+    $ daml new iou-quickstart-java --template quickstart-java
     $ cd iou-quickstart-java/
     $ daml build
     $ daml sandbox --wall-clock-time --ledgerid MyLedger ./.daml/dist/quickstart-0.0.1.dar

docs/source/triggers/index.rst

@@ -231,8 +231,8 @@ which only sends the commands if it is not already in flight.
 Running a DAML Trigger
 ----------------------
 
-To try this example out, you can replicate it using ``daml new
-copy-trigger copy-trigger``. You first have to build the trigger like
+To try this example out, you can replicate it using
+``daml new copy-trigger --template copy-trigger``. You first have to build the trigger like
 you would build a regular DAML project using ``daml build``.
 Then start the sandbox and navigator using ``daml start``.
 

language-support/scala/examples/iou-no-codegen/README.md

@@ -10,7 +10,7 @@ This examples requires a running sandbox.
 ## To start a sandbox running IOU example
 - create a new DAML Assistant `quickstart-scala` project
 ```
-$ daml new quickstart-scala quickstart-scala
+$ daml new quickstart-scala --template quickstart-scala
 ```
 - change directory to this project
 ```

language-support/scala/examples/quickstart-scala/README.md

@@ -10,7 +10,7 @@ All instructions below assume that you have DAML SDK installed. If you have not
 
 ## Create a quickstart-scala project
 ```
-daml new ./quickstart-scala quickstart-scala
+daml new ./quickstart-scala --template quickstart-scala
 ```
 This should output:
 ```

release/RELEASE.md

@@ -147,7 +147,7 @@ patches we backport to the 1.0 release branch).
        Otherwise, check out the commit that you are referencing in the `LATEST` file
        and build documentation locally via `./docs/scripts/preview.sh`.
 
-    1. Create a new project using `daml new create-daml-app create-daml-app`
+    1. Create a new project using `daml new create-daml-app --template create-daml-app`
        and switch to the project directory using `cd create-daml-app`.
 
     1. Build the project using `daml build`.
@@ -236,7 +236,7 @@ patches we backport to the 1.0 release branch).
    for now since it covers things not covered by the new GSG
    (Navigator, scenarios, Maven artifacts, …)
 
-    1. Create a new project with `daml new quickstart quickstart-java`
+    1. Create a new project with `daml new quickstart --template quickstart-java`
        and switch to it using `cd quickstart`.
 
     1. Verify the new version is specified in `daml.yaml` as the `sdk-version`.