diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,30 @@ +Copyright Author name here (c) 2017 + +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + + * Neither the name of Author name here nor the names of other + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,7 @@ +# docstrings + This package provides funcionality similar to Python or Lisp. + Docstrings are simply strings bound to identifier names. + To get access to a name one must enable @-XTemplateHaskell@ and use + prime notation like @'myValIdentifier@ and @''MyTypeIdentifier@. + Access Docstrings in the repl via @help 'myIdentifier@, + and introduce Docstrings via @docstring 'myIdentifier "some documentation"@ in a module. diff --git a/Setup.hs b/Setup.hs new file mode 100644 --- /dev/null +++ b/Setup.hs @@ -0,0 +1,2 @@ +import Distribution.Simple +main = defaultMain diff --git a/docstrings.cabal b/docstrings.cabal new file mode 100644 --- /dev/null +++ b/docstrings.cabal @@ -0,0 +1,35 @@ +name: docstrings +version: 0.1.0.0 +synopsis: Docstrings for documentation in the repl +description: + This package provides funcionality similar to Python or Lisp. + Docstrings are simply strings bound to identifier names. + To get access to a name one must enable @-XTemplateHaskell@ and use + prime notation like @'myValIdentifier@ and @''MyTypeIdentifier@. + Access Docstrings in the repl via @help 'myIdentifier@, + and introduce Docstrings via @docstring 'myIdentifier "some documentation"@ in a module. +homepage: https://github.com/daig/docstrings#readme +license: MIT +license-file: LICENSE +author: Dai +maintainer: dailectic@gmail.com +copyright: 2017 Dai +category: Documentation +build-type: Simple +extra-source-files: README.md +cabal-version: >=1.10 + +library + hs-source-dirs: src + exposed-modules: Help, Help.Docstring + other-modules: Help.Docstring.Internal + build-depends: base >= 4.7 && < 5 + ,containers + ,template-haskell + ,heredoc + ghc-options: -Wall + default-language: Haskell2010 + +source-repository head + type: git + location: https://github.com/daig/docstrings diff --git a/src/Help.hs b/src/Help.hs new file mode 100644 --- /dev/null +++ b/src/Help.hs @@ -0,0 +1,45 @@ +{-# language TemplateHaskell #-} +{-# language QuasiQuotes #-} +{-| +Module : Help +Description : Access and define docstrings +Copyright : Dai 2017 +License : MIT +Maintainer : dailectic@gmail.com +Stability : experimental +Portability : POSIX + +Import this module in the repl to access docstrings. When defining docstrings it is best to import only @Help.Docstring@. +-} + +module Help (help, docstring) where +import Help.Docstring +import Help.Docstring.Internal +import Data.Map as M + +-- | Retrieve documentation for a value/function identifier `'myIdentifier` +-- or a type identifier `''MyIdentifier`. +-- +-- `help` will find documentation from any use of `docstring` in previously imported modules. +-- Documentation for a module `MyModule` is conventionally found in an associated `MyModule.Docs`|] +help :: Name -> IO () +help n = do + m <- readMVar docstrings + putStrLn $ case M.lookup n m of + Nothing -> "no documentation for " ++ show n + Just s -> "=== " ++ show n ++ " ===\n" ++ s ++ "\n======" + +docstring 'docstring + [str|Add documentation string for given `Name`, to be retrieved by `help`. + |You may want to use the `Text.Heredoc.str` quasiquoter for convinient multiline documentation. + |(See definition for `docstring`) + | + |`docstring` adds documentation to a magic global scope as a Template Haskell side effect + |and so documentation for `MyModule` should probably be added only in a seperate `MyModule.Doc` module + |to avoid polluting application code|] +docstring 'help + [str|Retrieve documentation for a value/function identifier `'myIdentifier` + |or a type identifier `''MyIdentifier`. + | + |`help` will find documentation from any use of `docstring` in previously imported modules. + |Documentation for a module `MyModule` is conventionally found in an associated `MyModule.Docs`|] diff --git a/src/Help/Docstring.hs b/src/Help/Docstring.hs new file mode 100644 --- /dev/null +++ b/src/Help/Docstring.hs @@ -0,0 +1,24 @@ +{-| +Module : Help.Docstring +Description : Define docstrings +Copyright : Dai 2017 +License : MIT +Maintainer : dailectic@gmail.com +Stability : experimental +Portability : POSIX +-} +module Help.Docstring (docstring, module X ) where +import Help.Docstring.Internal +import Data.Map as M +import Language.Haskell.TH.Syntax as X (Name,Q,Dec) +import Text.Heredoc as X (str) + +-- | Add documentation string for given `Name`, to be retrieved by `help`. +-- You may want to use the `Text.Heredoc.str` quasiquoter for convinient multiline documentation. +-- (See definition for `docstring`) +-- +-- `docstring` adds documentation to a magic global scope as a Template Haskell side effect +-- and so documentation for `MyModule` should probably be added only in a seperate `MyModule.Doc` module +-- to avoid polluting application code +docstring :: Name -> String -> Q [Dec] +docstring n s = unsafePerformIO (modifyMVar docstrings (\m -> return (M.insert n s m,()))) `seq` return [] diff --git a/src/Help/Docstring/Internal.hs b/src/Help/Docstring/Internal.hs new file mode 100644 --- /dev/null +++ b/src/Help/Docstring/Internal.hs @@ -0,0 +1,21 @@ +{-| +Module : Help.Docstring.Internal +Description : Define docstrings +Copyright : Dai 2017 +License : MIT +Maintainer : dailectic@gmail.com +Stability : experimental +Portability : POSIX +-} +module Help.Docstring.Internal (docstrings, module X) where +import GHC.IO as X (unsafePerformIO) +import GHC.Conc (pseq) +import Data.Map as M +import Control.Concurrent.MVar as X (MVar,newMVar,modifyMVar,readMVar) +import Language.Haskell.TH.Syntax as X (Name,Q,Dec) + + +-- | Global list of docstrings. Should not be accessed directly and only be manipulated by @docstring@ and @help@ +docstrings :: MVar (Map Name String) +{-# noinline docstrings #-} +docstrings = m `pseq` unsafePerformIO (newMVar m) where m = M.empty