Adds prototype docsite with existing tutorials.

.gitignore

@@ -27,3 +27,10 @@ instantclient*
 # We use a ci compose file that keeps some extra bits locally to cache
 # They are ignored below to avoid them being included in various operations, locally and in ci
 .stack-root
+
+# Ignore Hakyll build directories
+orville-docsite/site-builder/_cache
+orville-docsite/site-builder/_site
+
+# Ignore directories created by samples
+orville-docsite/samples/getting-started/orville-getting-started

orville-docsite/Dockerfile

@@ -0,0 +1,4 @@
+FROM ghcr.io/flipstone/haskell-tools:debian-stable-ghc-9.4.7-2023-10-31-3286ef4
+
+ADD samples/install-packages.sh /install-packages.sh
+RUN sh /install-packages.sh

orville-docsite/compose.yml

@@ -0,0 +1,20 @@
+version: "3"
+services:
+  dev:
+    build: .
+    environment:
+      STACK_ROOT: /stack-root
+    volumes:
+      - .:/orville-docsite
+      - stack-root:/stack-root
+      - ./stack-config.yaml:/stack-root/config.yaml
+    working_dir: /orville-docsite
+    # A TTY is required for the test-loop script to use
+    # stack test. stdin_open would be sufficient, but
+    # allocating a tty provides colorful test output :)
+    tty: true
+    ports:
+      - 8000:8000
+
+volumes:
+  stack-root:

orville-docsite/samples/getting-started/Main.hs

@@ -0,0 +1,26 @@
+module Main
+  ( main
+  ) where
+
+import qualified Orville.PostgreSQL as O
+import qualified Orville.PostgreSQL.Execution as Execution
+import qualified Orville.PostgreSQL.Raw.Connection as Connection
+import qualified Orville.PostgreSQL.Raw.RawSql as RawSql
+import qualified Orville.PostgreSQL.Raw.SqlValue as SqlValue
+
+main :: IO ()
+main = do
+  pool <-
+    O.createConnectionPool
+        O.ConnectionOptions
+          { O.connectionString = "host=localhost user=postgres password=postgres"
+          , O.connectionNoticeReporting = O.DisableNoticeReporting
+          , O.connectionPoolStripes = O.OneStripePerCapability
+          , O.connectionPoolLingerTime = 10
+          , O.connectionPoolMaxConnections = O.MaxConnectionsPerStripe 1
+          }
+
+  Connection.withPoolConnection pool $ \connection -> do
+    result <- RawSql.execute connection (RawSql.fromString "SELECT 1+1")
+    [[(_, sqlValue)]] <- Execution.readRows result
+    print (SqlValue.toInt sqlValue)

orville-docsite/samples/getting-started/add-orville-extra-dep-to-stack-yaml.patch

@@ -0,0 +1,5 @@
+42c42,43
+< # extra-deps: []
+---
+> extra-deps:
+>  - orville-postgresql-1.0.0.0

orville-docsite/samples/getting-started/add-orville-to-cabal-file.patch

@@ -0,0 +1,4 @@
+22c22
+<   build-depends:       base >= 4.7 && < 5
+---
+>   build-depends:       base >= 4.7 && < 5, orville-postgresql ^>= 1.0.0.0

orville-docsite/samples/getting-started/expected-output.txt

@@ -0,0 +1 @@
+Right 2

orville-docsite/samples/getting-started/run.sh

@@ -0,0 +1,31 @@
+# SNIPPET: hidden
+set -e
+rm -rf orville-getting-started
+service postgresql start
+# SNIPPET: initProject
+mkdir orville-getting-started
+cd orville-getting-started
+stack new orville-getting-started --bare simple --resolver lts-21.19
+# SNIPPET: hidden
+echo "system-ghc: true" >> stack.yaml
+echo "install-ghc: false" >> stack.yaml
+# SNIPPET: hidden
+patch stack.yaml ../add-orville-extra-dep-to-stack-yaml.patch
+# SNIPPET: hidden
+patch orville-getting-started.cabal ../add-orville-to-cabal-file.patch
+# SNIPPET: hidden
+cp ../Main.hs src/Main.hs
+# SNIPPET: buildAndExecute
+stack build
+stack exec orville-getting-started
+# SNIPPET: hidden
+expected=$(cat ../expected-output.txt)
+actual=$(stack exec orville-getting-started)
+
+if [ "$expected" = "$actual" ]; then
+  echo "Output matches expected"
+else
+  echo "Expected output to be: $expected"
+  echo "But it was actually  : $actual"
+  exit 1
+fi;

orville-docsite/samples/hero/expected-output.txt

@@ -0,0 +1 @@
+Spot found!

orville-docsite/samples/hero/hero.cabal

@@ -0,0 +1,32 @@
+cabal-version:       2.2
+
+name:                hero
+version:             0.1.0.0
+-- synopsis:
+-- description:
+homepage:            https://github.com/flipstone/hero#readme
+license:             BSD-3-Clause
+author:              Flipstone Technology Partners, Inc
+maintainer:          [email protected]
+copyright:           
+category:            sample
+build-type:          Simple
+
+executable hero
+  hs-source-dirs:      src
+  main-is:             Main.hs
+  default-language:    Haskell2010
+
+  build-depends:       base >= 4.7 && < 5,
+                       orville-postgresql,
+                       text
+
+  ghc-options:         -Wall
+                       -Wcompat
+                       -Widentities
+                       -Wincomplete-record-updates
+                       -Wincomplete-uni-patterns
+                       -Wmissing-export-lists
+                       -Wmissing-home-modules
+                       -Wpartial-fields
+                       -Wredundant-constraints

orville-docsite/samples/hero/run.sh

@@ -0,0 +1,13 @@
+set -e
+service postgresql start
+stack build
+expected=$(cat expected-output.txt)
+actual=$(stack exec hero)
+
+if [ "$expected" = "$actual" ]; then
+  echo "Output matches expected"
+else
+  echo "Expected output to be: $expected"
+  echo "But it was actually  : $actual"
+  exit 1
+fi;

orville-docsite/samples/hero/src/Main.hs

@@ -0,0 +1,106 @@
+module Main (main) where
+
+import Data.Int (Int32)
+import qualified Data.Text as T
+import qualified Orville.PostgreSQL as O
+import qualified Orville.PostgreSQL.AutoMigration as AutoMigration
+
+{- |
+  Pet is a plain old Haskell record that will be marshalled to and from the
+  @pet@ table.
+-}
+data Pet =
+  Pet
+    { petId :: PetId
+    , petName :: T.Text
+    }
+
+{- |
+  It's good practice to create newtype specific to each entity to hold its
+  primary key value
+-}
+newtype PetId = PetId Int32
+
+{- |
+  A marshaller must be defined to convert Pet to and from SQL.
+-}
+petMarshaller :: O.SqlMarshaller Pet Pet
+petMarshaller =
+  Pet
+    <$> O.marshallField petId petIdField
+    <*> O.marshallField petName nameField
+
+{- |
+  Defines the @id@ field for the marshaller to marshall the 'petId' record
+  field to and from.
+-}
+petIdField :: O.FieldDefinition O.NotNull PetId
+petIdField =
+  O.coerceField (O.integerField "id")
+
+{- |
+  Defines the @name@ field for the marshaller to marshall the 'petName' record
+  field to and from.
+-}
+nameField :: O.FieldDefinition O.NotNull T.Text
+nameField =
+  O.unboundedTextField "name"
+
+{- |
+  Marshaller above is associated with the @pet@ table. The marshallers fields
+  will define the column of the table.
+-}
+petTable :: O.TableDefinition (O.HasKey PetId) Pet Pet
+petTable =
+  O.mkTableDefinition
+    "pet"
+    (O.primaryKey petIdField)
+    petMarshaller
+
+{- |
+  A simple demo that connects to a database, inserts 2 pets and then finds the
+  pet named "Spot"
+-}
+main :: IO ()
+main = do
+  pool <-
+    O.createConnectionPool
+      O.ConnectionOptions
+        { O.connectionString = "host=localhost user=postgres password=postgres"
+        , O.connectionNoticeReporting = O.DisableNoticeReporting
+        , O.connectionPoolStripes = O.OneStripePerCapability
+        , O.connectionPoolMaxConnections = O.MaxConnectionsPerStripe 1
+        , O.connectionPoolLingerTime = 10
+        }
+
+  mbSpot <- O.runOrville pool insertAndFindSpot
+
+  case mbSpot of
+    Nothing -> putStrLn "No Spot Found!"
+    Just _spot -> putStrLn "Spot found!"
+
+{- |
+  The Orville monad provides a starter pack for running Orville operations
+  against a connection pool.
+-}
+insertAndFindSpot :: O.Orville (Maybe Pet)
+insertAndFindSpot = do
+  AutoMigration.autoMigrateSchema
+    AutoMigration.defaultOptions
+    [AutoMigration.SchemaTable petTable]
+
+  O.insertEntity petTable $
+    Pet
+      { petId = PetId 1
+      , petName = T.pack "FuFu"
+      }
+
+  O.insertEntity petTable $
+    Pet
+      { petId = PetId 2
+      , petName = T.pack "Spot"
+      }
+
+  O.findFirstEntityBy
+    petTable
+    (O.where_ (O.fieldEquals nameField (T.pack "Spot")))

orville-docsite/samples/hero/stack.yaml

@@ -0,0 +1,69 @@
+# This file was automatically generated by 'stack init'
+#
+# Some commonly used options have been documented as comments in this file.
+# For advanced use and comprehensive documentation of the format, please see:
+# https://docs.haskellstack.org/en/stable/yaml_configuration/
+
+# Resolver to choose a 'specific' stackage snapshot or a compiler version.
+# A snapshot resolver dictates the compiler version and the set of packages
+# to be used for project dependencies. For example:
+#
+# resolver: lts-21.13
+# resolver: nightly-2023-09-24
+# resolver: ghc-9.6.2
+#
+# The location of a snapshot can be provided as a file or url. Stack assumes
+# a snapshot provided as a file might change, whereas a url resource does not.
+#
+# resolver: ./custom-snapshot.yaml
+# resolver: https://example.com/snapshots/2023-01-01.yaml
+resolver: lts-21.19
+system-ghc: true
+install-ghc: false
+
+# User packages to be built.
+# Various formats can be used as shown in the example below.
+#
+# packages:
+# - some-directory
+# - https://example.com/foo/bar/baz-0.0.2.tar.gz
+#   subdirs:
+#   - auto-update
+#   - wai
+packages:
+- .
+# Dependency packages to be pulled from upstream that are not in the resolver.
+# These entries can reference officially published versions as well as
+# forks / in-progress versions pinned to a git hash. For example:
+#
+# extra-deps:
+# - acme-missiles-0.3
+# - git: https://github.com/commercialhaskell/stack.git
+#   commit: e7b331f14bcffb8367cd58fbfc8b40ec7642100a
+#
+extra-deps:
+  - orville-postgresql-1.0.0.0
+
+# Override default flag values for local packages and extra-deps
+# flags: {}
+
+# Extra package databases containing global packages
+# extra-package-dbs: []
+
+# Control whether we use the GHC we find on the path
+# system-ghc: true
+#
+# Require a specific version of Stack, using version ranges
+# require-stack-version: -any # Default
+# require-stack-version: ">=2.13"
+#
+# Override the architecture used by Stack, especially useful on Windows
+# arch: i386
+# arch: x86_64
+#
+# Extra directories used by Stack for building
+# extra-include-dirs: [/path/to/dir]
+# extra-lib-dirs: [/path/to/dir]
+#
+# Allow a newer minor version of GHC than the snapshot specifies
+# compiler-check: newer-minor

orville-docsite/samples/hero/stack.yaml.lock

@@ -0,0 +1,19 @@
+# This file was autogenerated by Stack.
+# You should not edit this file by hand.
+# For more information, please see the documentation at:
+#   https://docs.haskellstack.org/en/stable/lock_files
+
+packages:
+- completed:
+    hackage: orville-postgresql-1.0.0.0@sha256:35e9b9f8bc0bc1ee1847bcb5340fa39bed320f1573099ec16ca394726a50593a,9018
+    pantry-tree:
+      sha256: b8d324f2ad94f12ac419996cc2947ee0c69c5178b2caf13dc92135118602bbd8
+      size: 12020
+  original:
+    hackage: orville-postgresql-1.0.0.0
+snapshots:
+- completed:
+    sha256: fb482b8e2d5d061cdda4ba1da2957c012740c893a5ee1c1b99001adae7b1fbe7
+    size: 640046
+    url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/21/19.yaml
+  original: lts-21.19

orville-docsite/samples/install-packages.sh

@@ -0,0 +1,13 @@
+# SNIPPET: hidden
+set -e
+# SNIPPET: installLibPqClient
+apt update
+apt install -y libpq-dev
+# SNIPPET: hidden
+apt install -y postgresql
+sed \
+  -i \
+  "s/#listen_addresses = 'localhost'/listen_addresses = 'localhost' /" \
+  /etc/postgresql/15/main/postgresql.conf
+service postgresql start
+echo "ALTER USER postgres PASSWORD 'postgres'" | su postgres -c psql

orville-docsite/samples/using-json/expected-output.txt

@@ -0,0 +1,2 @@
+Just (Foo {fooId = 0, fooTags = Array [Number 1.0,Number 2.0,Number 3.0]})
+[(0,Number 1.0),(0,Number 2.0),(0,Number 3.0)]

orville-docsite/samples/using-json/run.sh

@@ -0,0 +1,17 @@
+# SNIPPET: hidden
+set -e
+service postgresql start
+# SNIPPET: buildAndExecute
+stack build
+stack exec using-json
+# SNIPPET: hidden
+expected=$(cat expected-output.txt)
+actual=$(stack exec using-json)
+
+if [ "$expected" = "$actual" ]; then
+  echo "Output matches expected"
+else
+  echo "Expected output to be: $expected"
+  echo "But it was actually  : $actual"
+  exit 1
+fi;