Remote imports

[mmhat]

This PR adds the basic support for remote imports. That means:

• The language is extended with a builtin URL literal:

  let Some/function = http://domain.tld/Some/function.ffg
  in Some/function "hello"
  

• A type for resolvers newtype Resolver = Resolver { runResolver :: Text.URI.URI -> IO (Maybe Text) }.
  A resolver receives the URL as an argument and shall return Just code if can process the URL (e.g. an HTTP resolver can resolve http:// URLs but not file:// URLs.) and Nothing it not.
• Several functions - like interpretWith or mainWith - take a value of type Grace.Interpret.InterpretSettings. Part of those settings is a list of resolvers which are tried one after another.
• grace-core includes two simple resolvers:
  • A resolver for environment variables matching env:// URLs.
  • A resolver matching file:// URLs that is basically equivalent to the filepath-based imports.
  • A catchall resolver matching any url called External Resolver. This resolver tries to invoke a program grace-resolver-<scheme> ${URL}. If such an executable is not found in $PATH the resolver fails, i.e. does not match the URL passed to it.

[mmhat]

@Gabriel439 I think I am almost done with this - A little smoke testing, one more review of tests, code, documentation and so on; That's all what is left to do. Given that this topic involved a fair amount of design decisions I'd highly appreciate your comments on this PR 🙂

[mmhat]

@Gabriel439 The last commits implement the ideas from #16 (comment). Please let me know if that is closer to the API you envision.

[mmhat]

Yet another approach for the configuration topic is here: https://github.com/mmhat/grace/tree/remote-imports-backpack
IMHO it is quite elegant but it has the downside that Stack users cannot use this project due to commercialhaskell/stack#2540.

The idea is as follows:

• Keep the non-configurable part in grace-core.
• The configurable interpreter lives in grace-interpreter. It requires the signature of Grace.Configuration to be instantiated when used.
• grace-configuration-default provides the Grace.Configuration module for the default grace interpreter.
• The grace package uses the former two to build the default interpreter.

TBH the main reason for this experiment is that I always wanted to play around with Backpack 😄

[Gabriella439]

Regarding the backpack solution, I still think it's a non-goal of this project to support package-level or API-level configurability, because I don't plan on publishing this project to Hackage. The intended user experience is that people will fork this project and edit it to implement features

The first reason why is to keep the implementation clearer for teaching purposes. The second reason why is because many desirable language features cannot (easily) be implemented by exposing a customizable interface.

As an example of the latter reason: in #17 you mentioned the introduction of a Map-like type (which I'm still thinking about), but suppose hypothetically that grace did not support such a built-in Map type and a downstream author wanted to add that type. It would be very difficult create an API that was sufficiently extensible to support such a type. For example, how would we make the Syntax tree or parser sufficiently customizable to store or parse such a type? It's possible to do, but very difficult.

The way I think about this project is that the source code is the API, not the actual Haskell API.

[mmhat]

@Gabriel439 Aaaah, okay! Thank you very much for clarification! 👍
I could have figured that from your comment above but I guess I was mentally stuck in the classic library development scenario... I apologize for the attention this PR draw from you.

Anyway, I will prepare this PR such that it does not have a configurable API and mark the respective parts as entrypoints for customization.

[mmhat]

@Gabriel439 Ok, this is now more in the spirit of this project: The interpreter does not take a callback function for URI resolving anymore and the grace-resolver-builtin package is gone.

[Gabriella439]

This is looking great! Just a few last suggestions

[Gabriella439]

I think you will want to store the exception and not the rendered form of the exception, like this:

Suggested change

	Left e -> throwError (ImportError uri (displayException e))
	Left e -> throwError (ImportError uri e)

The main reason I suggest this is to preserve as much structure as possible from the original exception. Instead, render the underlying exception at the last moment (i.e. have the displayException method of ImportError call displayException for the wrapped exception).

The second reason that I suggest this is that you probably want the Show instance for ImportError to Show (and not display…) the underlying exception

[mmhat]

I totally agree with you; The reason I render the message already there is the Eq instance of ImportError. Sadly we have to choose between one of the two. What is your preference?

[Gabriella439]

I think this is still doable if you use ExistentialQuantification, like this:

data InterpretError
    = forall e . (Exception e, Eq e) => ImportError URI e
    | …

[mmhat]

The problem here is that we use tryAny to catch the exception, hence e :: SomeException which does not have an Eq instance. We could however change InterpretError to

data InterpretError
    = ImportError URI SomeException

and define the Eq instance like

instance Eq InterpretError where
    ImportError uri1 e1 == InterpretError uri2 e2 = uri1 == uri2 && show e1 == show e2

It is not a pretty "solution" but since the Eq instance is only intended to be used in the test suite it could work.

As an alternative we can add another constructor to Grace.Import.ImportError:

data ImportError
    = forall e. (Eq e, Exception e) => SomeImportError e
    | UnsupportedURI

Then we leave it to the resolvers to wrap their errors (and the one of the libraries they are using) and catch only this error in interpretExprWith.

[Gabriella439]

I think this looks great! I think I can put up a PR of my own with the remaining proposed change for ImportError

[mmhat]

Thank you! 🚀

Regarding ImportError: Which path are you going to take?