From 344958d8f15f4bbb3ff04c7ef0c9a1d57dd66a4c Mon Sep 17 00:00:00 2001
From: instinctive <177694+instinctive@users.noreply.github.com>
Date: Wed, 16 Nov 2022 05:31:50 -0800
Subject: [PATCH] add documentation for single-file Haskell scripts (#8559)
* add documentation for single-file Haskell scripts
This is a useful feature which I think would benefit newcomers by being a top-level, early entry in the docs. See: https://stackoverflow.com/a/65541020
* Add project metadata and cabal run doc link
* Fix cabal run link
* Add custom anchor for 'cabal run'
* Qualify use of executable shell script to unix-likes
---
doc/cabal-commands.rst | 2 ++
doc/getting-started.rst | 38 ++++++++++++++++++++++++++++++++++++++
2 files changed, 40 insertions(+)
diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst
index 7671e41cdf..2773eae821 100644
--- a/doc/cabal-commands.rst
+++ b/doc/cabal-commands.rst
@@ -845,6 +845,8 @@ The configuration information for the script is cached under the cabal directory
and can be pre-built with ``cabal build path/to/script``.
See ``cabal run`` for more information on scripts.
+.. _cabal run:
+
cabal run
^^^^^^^^^
diff --git a/doc/getting-started.rst b/doc/getting-started.rst
index f1a64d6b0c..416a5dd77a 100644
--- a/doc/getting-started.rst
+++ b/doc/getting-started.rst
@@ -166,6 +166,44 @@ Now you can build and re-run your code to see the new output:
/ / / / \ \
/____/ /____/ \____\
+Run a single-file Haskell script
+--------------------------------
+
+Cabal also enables us to run single-file Haskell scripts
+without creating a project directory or ``.cabal`` file.
+The cabal directives are placed in the file within a comment.
+
+.. code-block:: haskell
+
+ #!/usr/bin/env cabal
+ {- cabal:
+ build-depends: base, split
+ -}
+
+ import Data.List.Split (chunksOf)
+
+ main :: IO ()
+ main = getLine >>= print . chunksOf 3
+
+This can be run using ``cabal run myscript``.
+On Unix-like systems this can be run directly with execute permission.
+
+.. code-block:: console
+
+ $ cabal run myscript
+
+ $ chmod +x myscript
+ $ ./myscript
+
+Project metadata can also be included:
+
+.. code-block:: haskell
+
+ {- project:
+ with-compiler: ghc-8.10.7
+ -}
+
+See more in the documentation for :ref:`cabal run`.
What Next?
----------
--
GitLab