packages feed

docstrings (empty) → 0.1.0.0

raw patch · 7 files changed

+164/−0 lines, 7 filesdep +basedep +containersdep +heredocsetup-changed

Dependencies added: base, containers, heredoc, template-haskell

Files

+ LICENSE view
@@ -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.
+ README.md view
@@ -0,0 +1,7 @@+# docstrings+  This package provides <https://en.wikipedia.org/wiki/Docstring docstring> 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.
+ Setup.hs view
@@ -0,0 +1,2 @@+import Distribution.Simple+main = defaultMain
+ docstrings.cabal view
@@ -0,0 +1,35 @@+name:                docstrings+version:             0.1.0.0+synopsis:            Docstrings for documentation in the repl+description:+  This package provides <https://en.wikipedia.org/wiki/Docstring docstring> 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
+ src/Help.hs view
@@ -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`|]
+ src/Help/Docstring.hs view
@@ -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 []
+ src/Help/Docstring/Internal.hs view
@@ -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