From 4f768a8bdf376af1034075f7a194b8866dd3377d Mon Sep 17 00:00:00 2001 From: Kazu Yamamoto Date: Wed, 19 Nov 2014 09:07:34 +0900 Subject: [PATCH] adding docs in the piki format. --- doc/Makefile | 10 ++ doc/bug.piki | 41 +++++++++ doc/copyright.piki | 5 + doc/emacs.piki | 215 +++++++++++++++++++++++++++++++++++++++++++ doc/ghc-mod.piki | 38 ++++++++ doc/ghc-modi.piki | 48 ++++++++++ doc/history.piki | 3 + doc/index.piki | 26 ++++++ doc/install.piki | 28 ++++++ doc/preparation.piki | 67 ++++++++++++++ 10 files changed, 481 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/bug.piki create mode 100644 doc/copyright.piki create mode 100644 doc/emacs.piki create mode 100644 doc/ghc-mod.piki create mode 100644 doc/ghc-modi.piki create mode 100644 doc/history.piki create mode 100644 doc/index.piki create mode 100644 doc/install.piki create mode 100644 doc/preparation.piki diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..2f5303a --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,10 @@ +all: + piki template.html index.piki > index.html + piki template.html install.piki > install.html + piki template.html ghc-mod.piki > ghc-mod.html + piki template.html ghc-modi.piki > ghc-modi.html + piki template.html emacs.piki > emacs.html + piki template.html preparation.piki > preparation.html + piki template.html copyright.piki > copyright.html + piki template.html history.piki > history.html + piki template.html bug.piki > bug.html diff --git a/doc/bug.piki b/doc/bug.piki new file mode 100644 index 0000000..ce4e2d0 --- /dev/null +++ b/doc/bug.piki @@ -0,0 +1,41 @@ +*Bugs + +If you found a bug relating the ghc-mod/ghc-modi commands or the ghc-mod library or the haskell-mode sub module, please record a ["issue on github" https://github.com/kazu-yamamoto/ghc-mod/issues]. + +**ghc-mod + +***ghc-mod cannot work if a ".hsc" file exist + +Please convert it to ".hs" by "cabal build" or by hand with "hsc2hs". + +***ghc-mod cannot work if "Paths_.hs" is missing + +Please create "Paths_.hs" by "cabal build". If you want to create it by hand, please install the [cab http://www.mew.org/~kazu/proj/cab/en/] command. +Typing "cab genpaths" in your package directory would help you. + + +**ghc-modi + +***Ctr-c does not terminate ghc-modi + +ghc-modi uses multiple threads of Ghc monad. +Ghc monad installs its own signal handlers +and multiple threads of Ghc monad make the world messy. +I cannot find a workaround. +Just type RET to terminate ghc-modi. + + + + +**Emacs front end + +***C-xC-s modifies the timestamp of the file even if there is no modification. + +In order to reload the file and check the syntax with GHC API (ghc-modi), +it is necessary to update the timestamp of the file. +A temporary file cannot maintain consistency of module dependency graph. +If you know a workaround, please let me know. + +***M-C-d on a function or type cannot display it but the top of the page is displayed + +For instance, "open" on Mac removes "#anchor" from the "file:///" URL. So, the top of the file is displayed. Please use C-uM-C-d as workaround. diff --git a/doc/copyright.piki b/doc/copyright.piki new file mode 100644 index 0000000..1844b40 --- /dev/null +++ b/doc/copyright.piki @@ -0,0 +1,5 @@ +*Copyright and license + +Copyright of this package belongs to ["IIJ Innovation Institute Inc" http://www.iij-ii.co.jp/en/]. +This package is available under BSD3 license. + diff --git a/doc/emacs.piki b/doc/emacs.piki new file mode 100644 index 0000000..31171d5 --- /dev/null +++ b/doc/emacs.piki @@ -0,0 +1,215 @@ +* Usage of Emacs front-end + +** Key bindings + +?M-C-i +!Completes a name of keyword, module, class, function, types, language extensions, GHC flags, etc. +?M-/ +!Completes a name of local symbol. +?M-t +!Inserts template. In the beginning of a buffer, "module Foo where" is inserted. On the function without signature, inferred type is inserted. On a symbol "foo" without definition, "foo = undefined" is inserted or a proper module is imported. C-uM-t inserts a hole in this case. On a variable, the case is split. When checking with hlint, original code is replaced with hlint's suggestion if possible. +?M-C-d +!Browses the local document with your browser. On a module import line, the document of the module is browsed. On a function or type, its document is browsed. +?C-uM-C-d +!Browses the Hackage document of the module with your browser. +?M-C-m +!Loads information of symbols for modules in the current buffer. If you add a new line to import a module, type this. The idle timer executes this command anyway. +?C-cC-h +!Query somthing at the cursor for hoogle. +?C-xC-s +!Saves the buffer if necessary and runs syntax check. +?C-cC-c +!Toggle GHC and Hlint for syntax check. GHC is used for initial time. +?M-n +!Goes to the next warning or error. +?M-p +!Goes to the previous warning or error. +?M-? +!Displays the warning/error message in the current line. +?C-cC-i +!Displays the info of this expression in another window. +?C-cC-t +!Displays the type of this expression in the minibuffer. Type C-cC-t multiple time to enlarge the expression. +?C-cC-a +!Selects one of possible cases. +?C-cC-f +!Replaces a hole with user-typed functions followed by holes. +?C-cC-e +!Displays the expanded Template Haskell. +?C-cC-m +!Insert "import Module" for the function at the cursor. +?M-s +!Sort and merge import statements in the region. +?C-cC-j +!In the beginning of the buffer, errors of other files are displayed. Typing C-cC-j on the errors jumps to the fist file of the error sources. +?C-cC-k +!Kill the ghc-modi subprocess for this project. If you install dependency packages, this command should be executed to reflect that change. +?C-c< +!Make the indentation of the region shallower. +?C-c> +!Make the indentation of the region deeper. + +** Resolving import hell + +Here is an example story not to type "import Foo" when +you write a Haskell program. + +Type the following signature. +Note that "ByteString" can be completed with M-C-i. + +>| +foo :: [ByteString] -> [ByteString] -> [ByteString] +|< + +C-xC-s highlights the signature. +Typing M-t on the line results in: + +>| +import Data.ByteString (ByteString) + +foo :: [ByteString] -> [ByteString] -> [ByteString] +foo = undefined +|< + +Type M-C-m to load symbols of Data.ByteString. +Then edit the body of "foo". +Note that "append" can be completed with M-C-i. + +>| +import Data.ByteString (ByteString) + +foo :: [ByteString] -> [ByteString] -> [ByteString] +foo bs1 bs2 = B.append <$> bs1 <*> bs2 +|< + +C-xC-s highlights the body. +Type M-t to get: + +>| +import Data.ByteString (ByteString) +import Control.Applicative ((<*>)) +import Control.Applicative ((<$>)) +import qualified Data.ByteString as B + +foo :: [ByteString] -> [ByteString] -> [ByteString] +foo bs1 bs2 = B.append <$> bs1 <*> bs2 +|< + +Now select a region for import statements (for instance, +move the cursor, type C-SPC, and move the cursor) then +type M-s. + +>| +import Control.Applicative ((<$>), (<*>)) +import Data.ByteString (ByteString) +import qualified Data.ByteString as B + +foo :: [ByteString] -> [ByteString] -> [ByteString] +foo bs1 bs2 = B.append <$> bs1 <*> bs2 +|< + +**Type holes + +Consider the following broken example: + +>| +foo :: [a -> a] -> a -> a +foo xs = foldr bar id xs + where + bar = (:) +|< + +C-xC-s highlights the 2nd line. C-c? displays the following: + +>| +Couldn't match type `[a -> a]' with `a -> a' +Expected type: (a -> a) -> (a -> a) -> a -> a + Actual type: (a -> a) -> [a -> a] -> [a -> a] +... +|< + +Even in this situation, C-cC-t on 'id' displays 'a -> a' in the minibuffer. GHC's -fdefer-type-errors enables this magic. + +Also, you can make use of GHC's hole. Inserting "_" before "bar" and typing C-xC-s results in highlighting the second line again: + +>| +foo :: [a -> a] -> a -> a +foo xs = foldr _bar id xs + where + bar = (:) +|< + +C-c? displays: + +>| +Found hole `_bar' with type: (a -> a) -> (a -> a) -> a -> a +Where: `a' is a rigid type variable bound by + the type signature for foo :: [a -> a] -> a -> a + at /Users/kazu/c.hs:3:8 +Relevant bindings include + bar :: forall a. a -> [a] -> [a] (bound at /Users/kazu/c.hs:6:5) + xs :: [a -> a] (bound at /Users/kazu/c.hs:4:5) + foo :: [a -> a] -> a -> a (bound at /Users/kazu/c.hs:4:1) +... +|< + +**More type holes + +Suppose you have: + +>| +filterNothing :: [Maybe a] -> [a] +|< + +Typing M-t gets: + +>| +filterNothing :: [Maybe a] -> [a] +filterNothing = undefined +|< + +On the other hand, typing C-uM-t gets: + +>| +filterNothing :: [Maybe a] -> [a] +filterNothing xs = _body +|< + +Then, C-xC-s refreshes highlightings. When you type C-cC-f on "_body" and +type "filter" in the minibuffer, you get: + +>| +filterNothing :: [Maybe a] -> [a] +filterNothing xs = filter _body_1 _body_2 +|< + +** Case handling + +Suppose you have: + +>| +f :: [a] -> a +f x = _f_body +|< + +Typing M-t on "x" splits cases as follows: + +>| +f :: [a] -> a +f [] = _f_body +f (x:xs) = _f_body +|< + +Suppose you have: + +>| +f :: a -> Maybe a +f x = _f_body +|< + +Typing C-cC-a on "_f_body" and selecting one of possible cases in another window results in: + +>| +f :: a -> Maybe a +f x = Nothing +|< diff --git a/doc/ghc-mod.piki b/doc/ghc-mod.piki new file mode 100644 index 0000000..a96a99f --- /dev/null +++ b/doc/ghc-mod.piki @@ -0,0 +1,38 @@ +*The ghc-mod command + +?ghc-mod list +!Displays a list of modules +?ghc-mod lang +!Displays a list of language extensions +?ghc-mod flag +!Displays a list of GHC flags +?ghc-mod browse \[:\] +!Displays symbols of +?ghc-mod check +!Checks syntax with GHC +?ghc-mod expand +!Expands Template Haskell +?ghc-mod debug +!Displays debug information +?ghc-mod info +!Displays information about the expression +?ghc-mod type +!Displays the types of all expressions including the expression +?ghc-mod find +!Finds all module names exporting +?ghc-mod lint +!Checks synstax with Hlint +?ghc-mod root +!Finds the root directory for the Haskell file +?ghc-mod doc +!Finds the html document for the module +?ghc-mod boot +!Displays boot information for Emacs front-end +?ghc-mod version +!Displays the version of ghc-mod +?ghc-mod help +!Displays help messages + + for "info" and "type" is not used, anything is OK. +It is necessary to maintain backward compatibility. + diff --git a/doc/ghc-modi.piki b/doc/ghc-modi.piki new file mode 100644 index 0000000..3d45827 --- /dev/null +++ b/doc/ghc-modi.piki @@ -0,0 +1,48 @@ +*The ghc-modi command + +** Example + +>| +% ghc-modi +check Foo.hs +Foo.hs:7:15:Not in scope: `B.append' +OK +bye +NG quit +% +|< + +** Commands + +? check +! Checks syntax with GHC +? find +! Finds all module names exporting +? info +! Displays information about the expression +? type +! Displays the types of all expressions including the expression +? lint \[hlint options\] +! Checks synstax with Hlint +? boot +! Displays boot information for Emacs front-end +? browse \[:\] +! Displays symbols of +? quit (or empty string) +! Terminate ghc-modi + +** Options + +Option should be the form of Haskell's list of String (\[String\]). +Here is an example: + +>| +lint ["--ignore=Use camelCase", "--ignore=Eta reduce"] Foo.hs +|< + +** Session separators + +?OK +! The session succeeded. +?NG +! The session fails. ghc-modi gets finished. diff --git a/doc/history.piki b/doc/history.piki new file mode 100644 index 0000000..01f0e26 --- /dev/null +++ b/doc/history.piki @@ -0,0 +1,3 @@ +*History + +Please see [ChangeLog https://github.com/kazu-yamamoto/ghc-mod/blob/master/ChangeLog]. diff --git a/doc/index.piki b/doc/index.piki new file mode 100644 index 0000000..7766117 --- /dev/null +++ b/doc/index.piki @@ -0,0 +1,26 @@ +*Happy Haskell Programming + +The ["ghc-mod command" ghc-mod.html] and ["ghc-modi command" ghc-modi.html] are backend commands to enrich Haskell programming on editors +including Emacs, Vim, and Sublime. +ghc-mod and ghc-modi are based on the ["ghc-mod library" http://hackage.haskell.org/packages/archive/ghc-mod/latest/doc/html/Language-Haskell-GhcMod.html] +which is a wrapper of ["GHC API" http://www.haskell.org/ghc/docs/latest/html/libraries/ghc/] and [Cabal http://hackage.haskell.org/package/Cabal]. + +The ["ghc-mod package" http://hackage.haskell.org/package/ghc-mod] on Hackage +includes +the ghc-mod command, the ghc-modi command, the ghc-mod library, and +["Emacs front-end" emacs.html] (for historical reasons). +The ["source repository of ghc-mod" https://github.com/kazu-yamamoto/ghc-mod] is on github. + +**Emacs + +["Emacs front-end" emacs.html] is an extension of ["Haskell mode" https://github.com/haskell/haskell-mode]. They enable to complete Haskell symbols and to browse documents of modules. Syntax error highlighting with GHC/Hlint is also integrated. Moreover, you are free from "import hell". + +**Vim + +-[ghcmod-vim https://github.com/eagletmt/ghcmod-vim] +-[syntastic https://github.com/scrooloose/syntastic] + +**Sublime + +-[SublimeHaskell https://github.com/SublimeHaskell/SublimeHaskell] + diff --git a/doc/install.piki b/doc/install.piki new file mode 100644 index 0000000..43ba53d --- /dev/null +++ b/doc/install.piki @@ -0,0 +1,28 @@ +*Installing "ghc-mod" + +This page assumes that you are a Haskell programmer and you know the "cabal" command well. + +**Installing the ghc-mod package + +First of all, update Cabal's database: + +>| +% cabal update +|< + +Now install "ghc-mod": + +>| +% cabal install ghc-mod +|< + +This command installs the followings: + +?~/.cabal/bin/ghc-mod +!The ghc-mod commnad +?~/.cabal/bin/ghc-modi +!The ghc-modi commnad +?~/.cabal/lib/ghc-mod-x.y.z/* +!The ghc-mod library +?~/.cabal/share/ghc-mod-x.y.z/ghc*.el +!Elisp files to extend Haskell mode diff --git a/doc/preparation.piki b/doc/preparation.piki new file mode 100644 index 0000000..cbad20a --- /dev/null +++ b/doc/preparation.piki @@ -0,0 +1,67 @@ +* Preparing Emacs front-end + +**Downloading + +Please use *stable* [MELPA http://melpa-stable.milkbox.net/] to download Emacs front-end. So, your "~/.emacs" should be: + +>| +(require 'package) +(add-to-list 'package-archives + '("melpa" . "http://melpa-stable.milkbox.net/packages/")) +(package-initialize) +|< + +The package name is "ghc". +Please don't forget ["install the latest cabal command" install.html]. + +**Configuring "~/.emacs.el" + +Then, put the followings to your "~/.emacs.el" or "~/.emacs.d/init.el": + +>| +(autoload 'ghc-init "ghc" nil t) +(autoload 'ghc-debug "ghc" nil t) +(add-hook 'haskell-mode-hook (lambda () (ghc-init))) +|< + +IMPORTANT: if your haskell-mode-hook includes (flymake-mode), please remove it. + +**Testing + +Executes Emacs and opens a Haskell file by C-xC-f. And try to complete any keywords by M-C-i. + +**Debugging + +ghc-mod/ghc-modi must be compiled by GHC which you are actually using from Emacs. The version of Emacs front-end and ghc-mod/ghc-modi must be the same. To confirm this, type M-x ghc-debug. + +>| +Path: check if you are using intended programs. + ghc.el path: /Users/kazu/work/ghc-mod/elisp/ghc.el + ghc-mod path: /Users/kazu/Library/Haskell/bin/ghc-mod + ghc-modi path: /Users/kazu/Library/Haskell/bin/ghc-modi + ghc path: /usr/local/ghc-7.8/bin/ghc + +Version: all versions must be the same. + ghc.el version 4.1.0 + ghc-mod version 4.1.0 compiled by GHC 7.8.2 + ghc-modi version 4.1.0 compiled by GHC 7.8.2 + The Glorious Glasgow Haskell Compilation System, version 7.8.2 +|< + +If you put (setq ghc-debug t) to your ".emacs", you can watch the communication between Emacs front-end and ghc-modi in the "*GHC Debug*" buffer. + +**Customizing + +If you want to specify GHC options from Emacs, set "ghc-ghc-options". +The following is an example to specify the "-i" options to GHC. + +>| +(setq ghc-ghc-options '("-idir1" "-idir2")) +|< + +An example to specify HLint options: + +>| +(setq ghc-hlint-options '("--ignore=Use camelCase")) +|< +