tweak
[lambda.git] / juli8.mdwn
index e3fa29d..a5e6087 100644 (file)
 -->
 
 
-## Using the Juli8 Libraries ##
+## What are the Juli8 Libraries? ##
 
 In addition to the fine programming language Kapulet, which doesn't yet exist in a form you can actually execute --- though the full-featured interpreter we provided last week (LINK) is a good start --- I decided it would be useful to have a collection of basic libraries for our teaching (and other) purposes, that brought OCaml, Haskell, and the Scheme implementations we recommend, more onto even footing. Of course there are fundamental differences between these languages, such as the lack of types in Scheme (though both Racket and Chicken have some facility for working with types in extensions), or the default lazy evaluation strategy in Haskell. But there are also many simply accidental differences between the languages too, in that this one provides a library function doing so-and-so, but the other one doesn't, or calls it by a different name. The Juli8 collection of libraries is aimed to reduce these differences, to make it easier to move back and forth between the languages, and also to just make some of the languages generally easier to use (from my perspective). Juli8 will eventually have components that you can install into each of Haskell, OCaml, Racket, and Chicken. For the moment, OCaml is the most developed of these, and Haskell a bit, with the Scheme components deferred for another time.
 
 Juli8 tries to give OCaml more-or-less the same functionality that you have in Haskell's Maybe, List, and Monad libraries, as well as a few others. It doesn't try for an exact match, and it doesn't strictly use the same names as Haskell does. I've aimed to at least stay close to the existing OCaml naming patterns, and also the Scheme naming patterns when they are salient to me.
 
-First we'll give instructions on how to install Juli8 into your existing Haskell and/or OCaml setups. Then we'll give instructions on how to use the non-monadic parts of the Juli8 libraries for OCaml. We discuss how to use the monadic parts of the Juli8 libraries for OCaml here (LINK). At the end, we say a little bit about what Juli8 provides you if you're using Haskell.
+Below, we'll give instructions on how to install Juli8 into your existing OCaml and/or Haskell setups. We'll also discuss how to use the non-monadic parts of the Juli8 libraries for OCaml. We discuss how to use the monadic parts of the Juli8 libraries for OCaml elsewhere (LINK). We'll also say a little bit about the little bit that Juli8 provides for you if you're using Haskell.
 
 ## Setting up OCaml in general, and for use with Juli8 ##
 
@@ -88,7 +88,11 @@ First we'll give instructions on how to install Juli8 into your existing Haskell
     Now whenever you start up OCaml, the Juli8 OCaml libraries (including their monad components, which we'll be making extensive use of) will automatically be loaded. <!-- If later you want to load Oleg's Delimcc library, type `#load "delimcc.cma";;` then use the `Delimcc` module. -->
 
 
-If you're only going to use Juli8 for OCaml and not for Haskell, you can skip ahead to later in this document...
+## Using the Juli8 libraries with OCaml ##
+
+Will add here some guidance on using the non-monadic parts of the Juli8 library. For the monadic part, [[see here]] (LINK).
+
+
 
 ## Setting up Haskell for use with Juli8 ##
 
@@ -105,15 +109,15 @@ If you're only going to use Juli8 for OCaml and not for Haskell, you can skip ah
         cabal update
         cabal install --user ghc-paths semigroups hoogle
 
-4. If you haven't already downloaded and installed the Juli8 libraries as described in Step 4 under the previous OCaml section, do that now. Also type the following lines in a Terminal:
+4. If you haven't already downloaded and installed the Juli8 libraries as described in Step 4 under the earlier OCaml section, do that now. Also type the following lines in a Terminal:
 
         ln -s ~/.juli8/haskell ~/.ghc/juli8
 
 5. Check to see whether any of the following files exist on your system. `$HOME` will be some directory like `/Users/jim` or `/home/jim` or `C:/Documents\ and\ Settings/jim`:
 
-    * $HOME/.ghci
-    * $HOME/.ghc/ghci.conf
-    * $HOME/"Application Data"/ghc/ghci.conf
+    * `$HOME/.ghci`
+    * `$HOME/.ghc/ghci.conf`
+    * `$HOME/"Application Data"/ghc/ghci.conf`
 
     If you find such a file, you will add lines to it in the next step. If you don't find such a file, create one.
 
@@ -123,7 +127,15 @@ If you're only going to use Juli8 for OCaml and not for Haskell, you can skip ah
         :cmd (System.Environment.getEnvironment >>= maybe (return "") readFile . lookup "GHCIRC")
 
         -- special :commands from Juli8
-        :cmd do { dot_ghc <- System.Directory.getAppUserDataDirectory "ghc"; let { juli8 = dot_ghc ++ "/juli8"; cmds = juli8 ++ "/commands" }; juli8_exists <- System.Directory.doesDirectoryExist juli8; cmds_exists <- System.Directory.doesFileExist cmds; Control.Monad.when cmds_exists $ putStrLn "Loading juli8/commands ..."; return $ unlines $ if cmds_exists then [":set -i"++juli8, ":script "++cmds] else if juli8_exists then [":set -i"++juli8] else [] }
+        :{
+        :cmd do { dot_ghc <- System.Directory.getAppUserDataDirectory "ghc";
+                  let { juli8 = dot_ghc ++ "/juli8";
+                        cmds = juli8 ++ "/commands" };
+                  juli8_exists <- System.Directory.doesDirectoryExist juli8;
+                  cmds_exists <- System.Directory.doesFileExist cmds;
+                  Control.Monad.when cmds_exists $ putStrLn "Loading juli8/commands ...";
+                  return $ unlines $ if cmds_exists then [":set -i"++juli8, ":script "++cmds] else if juli8_exists then [":set -i"++juli8] else [] }
+        :}
 
         :def! url (\l->return $ ":!open "++l)
         -- :set editor vim
@@ -131,6 +143,7 @@ If you're only going to use Juli8 for OCaml and not for Haskell, you can skip ah
         -- :set +t -- to print types after each binding
 
         :load Juli8
+        :mod Juli8
 
     You may want to uncomment the `:set editor vim` line, but only if you know how to use the text editor `vim`. Other text editors you may be familiar with, and can use here are:
 
@@ -141,7 +154,7 @@ If you're only going to use Juli8 for OCaml and not for Haskell, you can skip ah
         :set editor mate -- Mac-only, see http://manual.macromates.com/en/using_textmate_from_terminal.html
         -- for Windows, use one of https://wiki.haskell.org/Windows#Editors
 
-    You may want to uncomment the `:set +m` line. What this does is let you type multi-line commands in the `ghci` sessions. There is a diffeent way to do that, where you type like this:
+    You may want to uncomment the `:set +m` line. What this does is let you type multi-line commands in the `ghci` sessions. There is a different way to do that, where you type like this:
 
         :{
         multiline
@@ -152,10 +165,20 @@ If you're only going to use Juli8 for OCaml and not for Haskell, you can skip ah
 
 If everything works, then when you start up GHCi, you should see a prompt like this:
 
-    *Juli8>
+    Prelude Juli8>
 
 
-## Using the Juli8 libraries with OCaml ##
+## What do I get from Juli8 for Haskell? ##
 
-Will add here some guidance on using the non-monadic parts of the Juli8 library. For the monadic part, [[see here]] (LINK).
+There are two or three benefits that Juli8 provides for Haskell, and they're not a big deal. If you're already a seasoned Haskell user, you may or may not find them helpful.
+
+First, Juli8 comes with a bunch of extra `:commands` to use at the GHCi prompt. You can see a list of what it installs by typing `:?`. Some of the commands listed in `:?` were already present before Juli8 arrived, and are just here collected and explained in a way I find more helpful. Others are provided by Juli8 itself. Many of these are based on commands already published elsewhere on Haskell wikis and so on, so you may have installed some versions of them already yourself. I'll leave it to you to pick and choose whether anything that comes with Juli8 suits your further needs.
+
+I developed these `:commands` on a Mac, and expect that some of the assumptions I made won't work on other systems. As the library matures, we'll try to make it work for a broader range of systems, or give specific instructions about how to customize it.
+
+The command `:help` will give you the old, official help text, that doesn't show the extra commands installed by Juli8.
+
+Second, Juli8 comes with a module/library that collects together a number of elements from scattered other locations in the Haskell libraries. These include the Semigroup libraries you installed in Step 3 of the above instructions, which you should use in place of Haskell's standard Data.Monoid libraries. Note that the Semigroup library provides `First a` and `Last a` types that differ from the types of the same name in Data.Monoid. Juli8 also provides `OptFirst a` and `OptLast a` types that behave more like the `First a` and `Last a` types from Data.Monoid. It also provides analogous types `OptMax a` and `OptMin a`. (If you don't know what any of this means, don't worry about it.)
+
+Third, Juli8 comes with a module/library `IOPlus` that isn't loaded by default, but which you can load manually by saying `:add IOPlus`. This provides instances to make `IO a` a Monoid when `a` is, and to make `IO` act like an instance of the Alternative and MonadPlus typeclass. This has some limitations, and can't be done perfectly, which is why it isn't done in the standard libraries. There's also an `IOFirst` and an `IOLast`. This is more experimental than the rest of the stuff in Juli8 and may well change or be removed. I'll explain it and refine it another time.