Support loading files from GitHub repositories (#218)

Author: thomashoneyman

README.md

@@ -12,9 +12,40 @@
 - Run and print output or show resulting JavaScript
 - Multiple view modes: code, output or both
 - Persistent session
-- Load PureScript code from Github Gists
+- Load PureScript code from GitHub Gists or repository files
 
-### Which Libraries are Available?
+### Control Features via the Query String
+
+Most of these features can be controlled not only from the toolbar, but also using the [query parameters](https://en.wikipedia.org/wiki/Query_string):
+
+- **Load From GitHub Repo**: Load a PureScript file from a GitHub repository using the `github` parameter
+    - Format: `github=/<owner>/<repo>/<branch or tag>/<file>.purs`
+    - Example: `github=/purescript/trypurescript/master/client/examples/Main.purs`.
+    - Notes: the file should be a single PureScript module with the module name `Main`.
+
+- **Load From Gist**: Load PureScript code from a gist using the `gist` parameter
+    - Format: `gist=<gist id>`
+    - Example: `gist=37c3c97f47a43f20c548`
+    - Notes: the file should be named `Main.purs` with the module name `Main`.
+
+- **View Mode**: Control the view mode using the `view` parameter
+    - Options are: `code`, `output`, `both` (default)
+    - Example: `view=output` will only display the output
+
+- **Auto Compile**: Automatic compilation can be turned off using the `compile` parameter
+    - Options are: `true` (default), `false`
+    - Example: `compile=false` will turn auto compilation off
+
+- **JavaScript Code Generation**: Print the resulting JavaScript code in the output window instead of the output of the program using the `js` parameter
+    - Options are: `true`, `false` (default)
+    - Example: `js=true` will print JavaScript code instead of the program's output
+
+- **Session**: Load code from a session which is stored with [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) using the `session` parameter
+    - Usually managed by Try PureScript
+    - Example: `session=9162f098-070f-4053-60ea-eba47021450d` (Note: will probably not work for you)
+    - When used with the `gist` or `github` query parameters the code will be loaded from the source file and not the session
+
+### Which Libraries Are Available?
 
 Try PureScript aims to provide a complete, recent package set from <https://github.com/purescript/package-sets>. The available libraries are those listed in `staging/spago.dhall`, at the versions in the package set mentioned in `staging/packages.dhall`.
 
@@ -41,30 +72,6 @@ $ spago ls packages | cut -f 1 -d ' ' | xargs spago install
 
 Before deploying an updated package set, someone (your reviewer) should check that the memory required to hold the package set's externs files does not exceed that of the try.purescript.org server.
 
-### Control Features via the Query String
-
-Most of these features can be controlled not only from the toolbar, but also using the [query parameters](https://en.wikipedia.org/wiki/Query_string):
-
-- **Load From Gist**: Load PureScript code from Gist id using the `gist` parameter
-    - Example: `gist=37c3c97f47a43f20c548` will load the code from this Gist if the file was named `Main.purs`
-
-- **View Mode**: Control the view mode using the `view` parameter
-    - Options are: `code`, `output`, `both` (default)
-    - Example: `view=output` will only display the output
-
-- **Auto Compile**: Automatic compilation can be turned off using the `compile` parameter
-    - Options are: `true` (default), `false`
-    - Example: `compile=false` will turn auto compilation off
-
-- **JavaScript Code Generation**: Print the resulting JavaScript code in the output window instead of the output of the program using the `js` parameter
-    - Options are: `true`, `false` (default)
-    - Example: `js=true` will print JavaScript code instead of the program's output
-
-- **Session**: Load code from a session which is stored with [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) using the `session` parameter
-    - Usually managed by Try PureScript
-    - Example: `session=9162f098-070f-4053-60ea-eba47021450d` (Note: will probably not work for you)
-    - When used with the `gist` query parameter the code will be loaded from the Gist and not the session
-
 ## Development
 
 ### 1. Client setup
@@ -98,6 +105,16 @@ stack exec trypurescript 8081 $(spago sources)
 # then: Setting phasers to stun... (port 8081) (ctrl-c to quit)
 ```
 
+### 3. Choosing a Tag
+
+The built-in examples for Try PureScript are loaded from this GitHub repository. To change the tag that the examples are loaded from, you'll need to touch three files:
+
+* `client/config/dev/Try.Config.purs`
+* `client/config/prod/Try.Config.purs`
+* `client/examples/Main.purs`, in the `fromExample` function.
+
+If you are preparing a release or if you need to adjust examples in development, you should change the tag in these three places (and ensure you're using the same tag in each place!).
+
 ## Server API
 
 The server is a very basic web service which wraps the PureScript compiler, allowing clients to send PureScript code to be compiled and receiving either compiled JS or error messages in response.

client/config/dev/Try.Config.purs

@@ -1,10 +1,15 @@
 module Try.Config where
 
+import Prelude
+
 loaderUrl :: String
 loaderUrl = "js/output"
 
 compileUrl :: String
 compileUrl = "http://localhost:8081"
 
-mainGist :: String
-mainGist = "7ad2b2eef11ac7dcfd14aa1585dd8f69"
+tag :: String
+tag = "load-from-github"
+
+mainGitHubExample :: String
+mainGitHubExample = "/purescript/trypurescript/" <> tag <> "/client/examples/Main.purs"

client/config/prod/Try.Config.purs

@@ -1,10 +1,15 @@
 module Try.Config where
 
+import Prelude
+
 loaderUrl :: String
 loaderUrl = "https://compile.purescript.org/output"
 
 compileUrl :: String
 compileUrl = "https://compile.purescript.org"
 
-mainGist :: String
-mainGist = "7ad2b2eef11ac7dcfd14aa1585dd8f69"
+tag :: String
+tag = "load-from-github"
+
+mainGitHubExample :: String
+mainGitHubExample = "/purescript/trypurescript/" <> tag <> "/client/examples/Main.purs"

client/examples/ADTs.purs

@@ -0,0 +1,23 @@
+module Main where
+
+import Prelude
+
+import Effect.Console (logShow)
+import Data.Map (Map, lookup, singleton)
+import TryPureScript (render, withConsole)
+
+-- | A Name consists of a first name and a last name
+data Name = Name String String
+
+-- | With compiler versions >= 0.8.2, we can derive
+-- | instances for Eq and Ord, making names comparable.
+derive instance eqName :: Eq Name
+derive instance ordName :: Ord Name
+
+-- | The Ord instance allows us to use Names as the
+-- | keys in a Map.
+phoneBook :: Map Name String
+phoneBook = singleton (Name "John" "Smith") "555-555-1234"
+
+main = render =<< withConsole do
+  logShow (lookup (Name "John" "Smith") phoneBook)

client/examples/DoNotation.purs

@@ -0,0 +1,20 @@
+module Main where
+
+import Prelude
+import Control.MonadPlus (guard)
+import Effect.Console (logShow)
+import Data.Array ((..))
+import Data.Foldable (for_)
+import TryPureScript
+
+-- Find Pythagorean triples using an array comprehension.
+triples :: Int -> Array (Array Int)
+triples n = do
+  z <- 1 .. n
+  y <- 1 .. z
+  x <- 1 .. y
+  guard $ x * x + y * y == z * z
+  pure [x, y, z]
+
+main = render =<< withConsole do
+  for_ (triples 20) logShow

client/examples/Generic.purs

@@ -0,0 +1,56 @@
+module Main where
+
+import Prelude
+import Effect.Console (logShow)
+import Data.Generic.Rep (class Generic)
+import Data.Eq.Generic (genericEq)
+import Data.Ord.Generic (genericCompare)
+import Data.Show.Generic (genericShow)
+import TryPureScript (render, withConsole)
+
+data Address = Address
+  { city  :: String
+  , state :: String
+  }
+
+data Person = Person
+  { first   :: String
+  , last    :: String
+  , address :: Address
+  }
+
+-- Generic instances can be derived by the compiler,
+-- using the derive keyword:
+derive instance genericAddress :: Generic Address _
+
+derive instance genericPerson :: Generic Person _
+
+-- Now we can write instances for standard type classes
+-- (Show, Eq, Ord) by using standard definitions
+instance showAddress :: Show Address where
+  show = genericShow
+
+instance eqAddress :: Eq Address where
+  eq = genericEq
+
+instance ordAddress :: Ord Address where
+  compare = genericCompare
+
+instance showPerson :: Show Person where
+  show = genericShow
+
+instance eqPerson :: Eq Person where
+  eq = genericEq
+
+instance ordPerson :: Ord Person where
+  compare = genericCompare
+
+main = render =<< withConsole do
+  logShow $ Person
+    { first: "John"
+    , last: "Smith"
+    , address: Address
+        { city: "Faketown"
+        , state: "CA"
+        }
+    }

client/examples/Loops.purs

@@ -0,0 +1,12 @@
+module Main where
+
+import Prelude
+
+import Effect.Console (log)
+import Data.Array ((..))
+import Data.Foldable (for_)
+import TryPureScript (render, withConsole)
+
+main = render =<< withConsole do
+  for_ (10 .. 1) \n -> log (show n <> "...")
+  log "Lift off!"

client/examples/Main.purs

@@ -0,0 +1,66 @@
+module Main where
+
+import Prelude
+
+import Data.Foldable (fold)
+import Effect (Effect)
+import TryPureScript (h1, h2, p, text, list, indent, link, render, code)
+
+main :: Effect Unit
+main =
+  render $ fold
+    [ h1 (text "Try PureScript!")
+    , p (text "Try out the examples below, or create your own!")
+    , h2 (text "Examples")
+    , list (map fromExample examples)
+    , h2 (text "Share Your Code")
+    , p (text "A PureScript file can be loaded from GitHub from a gist or a repository. To share code using a gist, simply include the gist ID in the URL as follows:")
+    , indent (p (code (text "  try.purescript.org?gist=<gist id>")))
+    , p (fold
+        [ text "The gist should contain PureScript module named "
+        , code (text "Main")
+        , text " in a file named "
+        , code (text "Main.purs")
+        , text " containing your PureScript code."
+        ])
+    , p (text "To share code from a repository, include the path to the source file as follows:")
+    , indent (p (code (text "  try.purescript.org?github=/<owner>/<repo>/<branch or tag>/<file>.purs")))
+    , p (fold
+        [ text "The file should be a PureScript module named "
+        , code (text "Main")
+        , text " containing your PureScript code."
+        ])
+    ]
+  where
+  fromExample { title, source } =
+    link ("https://github.com/purescript/trypurescript/load-from-github/client/examples/" <> source) (text title)
+
+  examples =
+    [ { title: "Algebraic Data Types"
+      , source: "ADTs.purs"
+      }
+    , { title: "Loops"
+      , source: "Loops.purs"
+      }
+    , { title: "Operators"
+      , source: "Operators.purs"
+      }
+    , { title: "Records"
+      , source: "Records.purs"
+      }
+    , { title: "Recursion"
+      , source: "Recursion.purs"
+      }
+    , { title: "Do Notation"
+      , source: "DoNotation.purs"
+      }
+    , { title: "Type Classes"
+      , source: "TypeClasses.purs"
+      }
+    , { title: "Generic Programming"
+      , source: "Generic.purs"
+      }
+    , { title: "QuickCheck"
+      , source: "QuickCheck.purs"
+      }
+    ]

client/examples/Operators.purs

@@ -0,0 +1,20 @@
+module Main where
+
+import Prelude
+import Effect.Console (log)
+import TryPureScript (render, withConsole)
+
+type FilePath = String
+
+subdirectory :: FilePath -> FilePath -> FilePath
+subdirectory p1 p2 = p1 <> "/" <> p2
+
+-- Functions can be given an infix alias
+-- The generated code will still use the original function name
+infixl 5 subdirectory as </>
+
+filepath :: FilePath
+filepath = "usr" </> "local" </> "bin"
+
+main = render =<< withConsole do
+  log filepath

client/examples/QuickCheck.purs

@@ -0,0 +1,21 @@
+module Main where
+
+import Prelude
+import Data.Array (sort)
+import Test.QuickCheck (quickCheck, (===))
+import TryPureScript (render, withConsole, h1, h2, p, text)
+
+main = do
+  render $ h1 $ text "QuickCheck"
+  render $ p $ text """QuickCheck is a Haskell library which allows us to assert properties
+hold for our functions. QuickCheck uses type classes to generate
+random test cases to verify those properties.
+purescript-quickcheck is a port of parts of the QuickCheck library to
+PureScript."""
+  render $ h2 $ text "Sort function is idempotent"
+  render =<< withConsole do
+    quickCheck \(xs :: Array Int) -> sort (sort xs) === sort xs
+  render $ h2 $ text "Every array is sorted"
+  render $ p $ text "This test should fail on some array which is not sorted"
+  render =<< withConsole do
+    quickCheck \(xs :: Array Int) -> sort xs === xs