Remote imports

.github/workflows/haskell.yml

@@ -36,4 +36,4 @@ jobs:
     - name: Build
       run: cabal build --enable-tests --enable-benchmarks all
     - name: Run tests
-      run: cabal test tasty
+      run: cabal test grace-core:tasty

.hlint.yaml

@@ -0,0 +1,68 @@
+# HLint configuration file
+# https://github.com/ndmitchell/hlint
+##########################
+
+# This file contains a template configuration file, which is typically
+# placed as .hlint.yaml in the root of your project
+
+
+# Specify additional command line arguments
+#
+# - arguments: [--color, --cpp-simple, -XQuasiQuotes]
+
+
+# Control which extensions/flags/modules/functions can be used
+#
+# - extensions:
+#   - default: false # all extension are banned by default
+#   - name: [PatternGuards, ViewPatterns] # only these listed extensions can be used
+#   - {name: CPP, within: CrossPlatform} # CPP can only be used in a given module
+#
+# - flags:
+#   - {name: -w, within: []} # -w is allowed nowhere
+#
+# - modules:
+#   - {name: [Data.Set, Data.HashSet], as: Set} # if you import Data.Set qualified, it must be as 'Set'
+#   - {name: Control.Arrow, within: []} # Certain modules are banned entirely
+#
+# - functions:
+#   - {name: unsafePerformIO, within: []} # unsafePerformIO can only appear in no modules
+
+
+# Add custom hints for this project
+#
+# Will suggest replacing "wibbleMany [myvar]" with "wibbleOne myvar"
+# - error: {lhs: "wibbleMany [x]", rhs: wibbleOne x}
+
+# The hints are named by the string they display in warning messages.
+# For example, if you see a warning starting like
+#
+# Main.hs:116:51: Warning: Redundant ==
+#
+# You can refer to that hint with `{name: Redundant ==}` (see below).
+
+# Turn on hints that are off by default
+#
+# Ban "module X(module X) where", to require a real export list
+# - warn: {name: Use explicit module export list}
+#
+# Replace a $ b $ c with a . b $ c
+# - group: {name: dollar, enabled: true}
+#
+# Generalise map to fmap, ++ to <>
+# - group: {name: generalise, enabled: true}
+
+
+# Ignore some builtin hints
+# - ignore: {name: Use let}
+# - ignore: {name: Use const, within: SpecialModule} # Only within certain modules
+- ignore: {name: Use fmap, within: Grace.Parser}
+- ignore: {name: Use <$>, within: Grace.Parser}
+
+
+# Define some custom infix operators
+# - fixity: infixr 3 ~^#^~
+
+
+# To generate a suitable file for HLint do:
+# $ hlint --default > .hlint.yaml

README.md

@@ -884,6 +884,11 @@ annotation as a last resort.
 
 ### Imports
 
+Grace has two ways to import expressions from other sources: Filepath-based
+imports and imports using URIs.
+
+#### Imports from files
+
 You can import a Grace subexpression stored within a separate file by
 referencing the file's relative or absolute path.
 
@@ -974,6 +979,83 @@ $ grace interpret - <<< './greet.ffg "John"'
 
 Any subexpression can be imported in this way.
 
+#### Imports using URIs
+
+Imports with URIs work similar to the ones using a simple filepath.
+
+Suppose you do not have the `greet.ffg` stored locally but instead it resides
+on a web server: `http://example.com/grace/greet.ffg`
+You could either download it and reference it by its filepath like demonstrated
+in the example above or let the Grace interpreter do the job:
+
+```bash
+$ grace interpret - <<< 'http://example.com/grace/greet.ffg "John"'
+```
+```dhall
+"Hello, John!"
+```
+
+Note that if a particular URI can be handled by the Grace interpreter depends
+on its (compile-time) configuration: Internally it relies on a set of _resolvers_
+that take care of all the things related to networking like downloading, caching
+, verifying the integrity of retrieved file on so on.
+For instance, the motivating example will unfortunately not work out-of-the box
+since the grace executable has no builtin resolver for HTTP (yet).
+
+Grace comes with three builtin resolvers:
+
+1. One to resolve `env://` URIs,
+2. one to resolve `file://` URIs.
+3. and one that delegates the resolving to an external program.
+
+Lets have a look at the `env://` resolver first:
+```bash
+$ MY_VAR='"Hello !"' grace interpret - <<< 'env:///MY_VAR'
+```
+```dhall
+"Hello !"
+```
+
+The `file://` resolver is similar to the filepath-based imports we already know:
+```bash
+$ grace interpret - <<< 'file:///path/to/greet.ffg "John"'
+```
+```dhall
+"Hello, John!"
+```
+
+Last but not least we'll have at look at third resolver: The one using external
+programs to resolve URIs. This resolver is somewhat different compared to the
+other two: It is not bound to a particular URI scheme.
+Instead, it tries to find the right executable to process the URI: Suppose our
+`greet.ffg` is on a remote machine reachable at `example.com` and all we got is
+SSH access. Now a resolver capable of receiving that file might look something
+like this:
+
+```bash
+#!/usr/bin/bash
+
+# The URI to resolve is passed as $1
+
+set -e
+
+no_scheme="${1#ssh://}"
+host="${no_scheme%%/*}"
+path="${1#ssh://$host/}"
+
+ssh "$host" cat "$path"
+```
+
+We store that file under `/usr/local/bin/grace-resolver-ssh` (or in another
+directory in `$PATH` - but the name is important). Now the following will work:
+
+```bash
+$ grace interpret - <<< 'ssh://example.com/greet.ffg "John"'
+```
+```dhall
+"Hello, John!"
+```
+
 ## Name
 
 Like all of my programming language projects, Grace is named after a

grace-core/grace-core.cabal

@@ -18,19 +18,24 @@ library
                      , insert-ordered-containers
                      , lens
                      , megaparsec
+                     , modern-uri
                      , mtl
                      , parser-combinators
                      , prettyprinter
                      , prettyprinter-ansi-terminal
+                     , safe-exceptions
                      , scientific
                      , string-interpolate
                      , template-haskell
                      , terminal-size
                      , text
+                     , typed-process
                      , unordered-containers
   exposed-modules:     Grace.Context
                      , Grace.Domain
                      , Grace.Existential
+                     , Grace.Import
+                     , Grace.Import.Resolver
                      , Grace.Interpret
                      , Grace.Infer
                      , Grace.Lexer
@@ -59,6 +64,7 @@ test-suite tasty
                      , tasty-hunit
                      , tasty-silver
                      , text
+  other-modules:       Grace.Test.Resolver
   hs-source-dirs:      tasty
   default-language:    Haskell2010
   ghc-options:         -Wall

grace-core/src/Grace/Import.hs

@@ -0,0 +1,84 @@
+{-# LANGUAGE BlockArguments #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE DerivingStrategies #-}
+{-# LANGUAGE FlexibleContexts #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ViewPatterns #-}
+
+{- | This module contains the functions and types that power to URI-base imports
+-}
+
+module Grace.Import
+    ( Import(..)
+    , ImportCallback
+    , Resolver(..)
+    , resolverToCallback
+    , ImportError(..)
+    ) where
+
+import Control.Exception.Safe (Exception(..), throw)
+import Grace.Location (Location)
+import Grace.Pretty (Pretty(..))
+import Grace.Syntax (Syntax)
+import Text.URI (URI)
+
+{- | A reference to external source code that will be imported by the
+     interpreter.
+-}
+data Import
+    = File FilePath
+    | URI URI
+
+instance Pretty Import where
+    pretty (File file) = pretty file
+    pretty (URI uri) = pretty uri
+
+-- | Type of the callback function used to resolve URI imports
+type ImportCallback = URI -> IO (Syntax Location Import)
+
+{- | A resolver for an URI.
+
+     When the interpreter tries to resolve an URI pointing to some source code
+     it will try multiple resolvers sequentially and stops if one returns a
+     @Just code@ value where @code@ is the source code of an expression.
+     It will then try to parse and interpret that expression.
+
+     Here are some good practices for the development of resolvers:
+
+     * A resolver should handle exactly one URI scheme.
+
+     * If a resolver encounters an URI which it cannot process (e.g. a
+       @file://@ URI is passed to a HTTP resolver) it should return @Nothing@
+       as fast as possible.
+
+     * Exceptions thrown in resolvers will be caught and rethrown as an
+       `ImportError` by the interpreter.
+-}
+newtype Resolver = Resolver { runResolver :: URI -> IO (Maybe (Syntax Location Import)) }
+
+instance Semigroup Resolver where
+    x <> y = Resolver \uri -> do
+        maybeResult <- runResolver x uri
+        case maybeResult of
+            Nothing -> runResolver y uri
+            _ -> return maybeResult
+
+instance Monoid Resolver where
+    mempty = Resolver (const (return Nothing))
+
+-- | Convert a resolver to a callback function
+resolverToCallback :: Resolver -> ImportCallback
+resolverToCallback resolver uri = do
+    maybeResult <- runResolver resolver uri
+    case maybeResult of
+        Nothing -> throw UnsupportedURI
+        Just result -> return result
+
+-- | Errors that might be raised during import resolution.
+data ImportError
+    = UnsupportedURI
+    deriving stock Show
+
+instance Exception ImportError where
+    displayException UnsupportedURI = "Resolving this URI is not supported"