-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Open the user's $EDITOR for text input.
--   
--   You know when you run <tt>git commit</tt>, and an editor pops open so
--   you can enter a commit message? This is a Haskell library that does
--   that.
--   
--   This library isn't very portable. It relies on the <tt>$EDITOR</tt>
--   environment variable. The concept only exists on *nix systems.
@package editor-open
@version 0.2.0.0


-- | You know when you run <tt>git commit</tt>, and a little editor pops
--   up? This is a Haskell library that does that.
module Text.Editor

-- | If you don't want to use ByteString, use this function.
--   
--   <pre>
--   &gt;&gt;&gt; :t runUserEditorDWIM plainTemplate mempty
--   ByteString
--   
--   &gt;&gt;&gt; :t wrapStr &lt;$&gt; runUserEditorDWIM plainTemplate mempty
--   String
--   </pre>
wrapStr :: ByteString -> String

-- | This is most likely the function you want to use. It takes a file type
--   template as an argument, along with what you want displayed when the
--   user opens the editor. It then runs the editor, and returns the
--   version of the text that the user modified.
--   
--   <pre>
--   runUserEditorDWIM templ initialContents = userEditorDefault _default_editor &gt;&gt;= theEditor -&gt;
--                                               runSpecificEditor theEditor templ initialContents
--   </pre>
--   
--   Examples:
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; runUserEditorDWIM jsonTemplate "{\n\n}\n"
--   </pre>
--   
--   This will open up the user's <tt>$EDITOR</tt> configured to edit JSON,
--   and with the initial text:
--   
--   <pre>
--   {
--   }
--   </pre>
--   
--   There are a bunch of templates. See the "File-type extensions"
--   section. It's also trivially easy to make your own templates. Say you
--   want one for, I dunno, Python:
--   
--   <pre>
--   pythonTemplate = mkTemplate "py"
--   </pre>
--   
--   The argument to <a>mkTemplate</a> should be the file extension you
--   want. In that case, I used <tt>"py"</tt>, because Python's file
--   extension is <tt>.py</tt>.
runUserEditorDWIM :: Template -> ByteString -> IO ByteString

-- | This is the same as above, it just takes a file as an argument instead
--   of the ByteString
--   
--   <pre>
--   runUserEditorDWIMFile templ fp = B.readFile fp &gt;&gt;=  runUserEditorDWIM templ
--   </pre>
runUserEditorDWIMFile :: Template -> FilePath -> IO ByteString

-- | This is likely the simplest function here. It opens up the user's
--   editor, and fetches a ByteString from it
--   
--   <pre>
--   runUserEditor = userEditorDefault _default_editor &gt;&gt;= theEditor -&gt;
--                     runSpecificEditor theEditor plainTemplate mempty
--   </pre>
runUserEditor :: IO ByteString

-- | This is probably the second-simplest function.
runUserEditorWithTemplate :: Template -> IO ByteString
type Template = String

-- | Make a template
--   
--   <pre>
--   mkTemplate ext = _ftempl &lt;&gt; "." &lt;&gt; ext
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; mkTemplate "blah"
--   tmp.blah
--   </pre>
mkTemplate :: String -> Template

-- | File-type template for HTML
--   
--   <pre>
--   htmlTemplate = mkTemplate "html"
--   </pre>
htmlTemplate :: Template

-- | File-type template for JSON
--   
--   <pre>
--   jsonTemplate = mkTemplate "json"
--   </pre>
jsonTemplate :: Template

-- | File-type template for Markdown
--   
--   <pre>
--   markdownTemplate = mkTemplate "md"
--   </pre>
markdownTemplate :: Template

-- | Older file-type template for Markdown
--   
--   <pre>
--   markdownTemplate = mkTemplate "markdown"
--   </pre>
oldMarkdownTemplate :: Template

-- | File-type template for plain text
--   
--   <pre>
--   plainTemplate = mkTemplate "txt"
--   </pre>
plainTemplate :: Template

-- | File-type template for XML
--   
--   <pre>
--   xmlTemplate = mkTemplate "xml"
--   </pre>
xmlTemplate :: Template

-- | Same as <a>plainTemplate</a>
txtTemplate :: Template

-- | File-type template for YAML
--   
--   <pre>
--   yamlTemplate = mkTemplate "yaml"
--   </pre>
yamlTemplate :: Template

-- | Open an editor. You probably don't want to use this function.
--   
--   <pre>
--   runSpecific editorName templ initialContents =
--     withSystemTempFile templ $ filePath hdl -&gt; do
--       hSetBinaryMode hdl True
--       hSetBuffering hdl NoBuffering
--       B.hPut hdl initialContents
--       callProcess editorName [filePath]
--       B.hGetContents hdl
--   </pre>
runSpecificEditor :: String -> Template -> ByteString -> IO ByteString

-- | This uses <a>getEnv</a> from <a>System.Posix</a> to attempt to get the
--   user's <tt>$EDITOR</tt> variable.
--   
--   <pre>
--   userEditor = getEnv _editor
--   </pre>
userEditor :: IO (Maybe String)

-- | Wrapper around <a>userEditor</a> that includes a fallback option if
--   the <tt>$EDITOR</tt> variable doesn't exist. <tt> userEditorDefault
--   def = userEditor &gt;&gt;= case Just e -&gt; pure e Nothing -&gt; pure
--   def </tt>
userEditorDefault :: String -> IO String

-- | The default editor if no other editor is found
--   
--   <pre>
--   _default_editor = "nano"
--   </pre>
_default_editor :: String

-- | The variable we should search when finding the user's editor.
--   
--   <pre>
--   _editor = <a>EDITOR</a>
--   </pre>
_editor :: String

-- | The standard filename template
--   
--   <pre>
--   _ftempl = "tmp"
--   </pre>
_ftempl :: String