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


-- | A portable alternative to GNU Readline
--   
--   A Haskell wrapper around the <a>Isocline C library</a> which can
--   provide an alternative to GNU Readline. (The Isocline library is
--   included whole and there are no runtime dependencies). Please see the
--   <a>readme</a> on GitHub for more information.
@package isocline
@version 1.0.9


-- | A Haskell wrapper around the <a>Isocline C library</a> which can
--   provide an alternative to GNU Readline. (The Isocline library is
--   included whole and there are no runtime dependencies).
--   
--   Isocline works across Unix, Windows, and macOS, and relies on a
--   minimal subset of ANSI escape sequences. It has a good multi-line
--   editing mode (use shift/ctrl-enter) which is nice for inputting small
--   functions etc. Other features include support for colors, history,
--   completion, unicode, undo/redo, incremental history search, inline
--   hints, brace matching, syntax highlighting, rich text using bbcode
--   formatting, etc.
--   
--   Minimal example with history:
--   
--   <pre>
--   import System.Console.Isocline
--   
--   main :: IO ()
--   main  = do putStrLn "Welcome"
--              <a>setHistory</a> "history.txt" 200
--              input &lt;- <a>readline</a> "myprompt"     -- full prompt becomes "myprompt&gt; "
--              <a>putFmtLn</a> ("[gray]You wrote:[/gray]\n" ++ input)
--   </pre>
--   
--   Or using custom completions with an interactive loop:
--   
--   <pre>
--   import System.Console.Isocline
--   import Data.Char( toLower )
--   
--   main :: IO ()
--   main 
--     = do <a>styleDef</a> "ic-prompt" "ansi-maroon"
--          <a>setHistory</a> "history.txt" 200
--          <a>enableAutoTab</a> <a>True</a>
--          interaction
--   
--   interaction :: IO ()
--   interaction 
--     = do s &lt;- <a>readlineEx</a> "hαskell" (Just completer) Nothing 
--          putStrLn ("You wrote:\n" ++ s)
--          if (s == "" || s == "exit") then return () else interaction
--                        
--   completer :: <a>CompletionEnv</a> -&gt; String -&gt; IO () 
--   completer cenv input
--     = do <a>completeFileName</a> cenv input Nothing [".","/usr/local"] [".hs"]  -- use [] for any extension
--          <a>completeWord</a> cenv input Nothing wcompleter
--   
--   wcompleter :: String -&gt; [<a>Completion</a>]
--   wcompleter input
--     = <a>completionsFor</a> (map toLower input) 
--         ["print","println","prints","printsln","prompt"]      
--   </pre>
--   
--   See a larger <a>example</a> with syntax highlighting and more
--   extenstive custom completion in the <a>Github repository</a>.
--   
--   Enjoy, -- Daan
module System.Console.Isocline

-- | <tt>readline prompt</tt>: Read (multi-line) input from the user with
--   rich editing abilities. Takes the prompt text as an argument. The full
--   prompt is the combination of the given prompt and the prompt marker
--   (<tt>"&gt; "</tt> by default) . See also <a>readlineEx</a>,
--   <a>readlineMaybe</a>, <a>enableMultiline</a>, and
--   <a>setPromptMarker</a>.
readline :: String -> IO String

-- | <tt>readlineEx prompt mbCompleter mbHighlighter</tt>: as
--   <a>readline</a> but uses the given <tt>mbCompleter</tt> function to
--   complete words on <tt>tab</tt> (instead of the default completer). and
--   the given <tt>mbHighlighter</tt> function to highlight the input
--   (instead of the default highlighter). See also <a>readline</a> and
--   <a>readlineExMaybe</a>.
readlineEx :: String -> Maybe (CompletionEnv -> String -> IO ()) -> Maybe (String -> Fmt) -> IO String

-- | <tt>setHistory filename maxEntries</tt>: Enable history that is
--   persisted to the given file path with a given maximum number of
--   entries. Use -1 for the default entries (200). See also
--   <a>enableHistoryDuplicates</a>.
setHistory :: FilePath -> Int -> IO ()

-- | Clear the history.
historyClear :: IO ()

-- | Isocline automatically adds input of more than 1 character to the
--   history. This command removes the last entry.
historyRemoveLast :: IO ()

-- | <tt>historyAdd entry</tt>: add <tt>entry</tt> to the history.
historyAdd :: String -> IO ()

-- | Abstract list of current completions.
data CompletionEnv

-- | <tt>completeFileName compls input dirSep roots extensions</tt>:
--   Complete filenames with the given <tt>input</tt>, a possible directory
--   separator <tt>dirSep</tt>, a list of root folders <tt>roots</tt> to
--   search from (by default <tt>["."]</tt>), and a list of extensions to
--   match (use <tt>[]</tt> to match any extension). The directory
--   separator is used when completing directory names. For example, using
--   g <tt>'/'</tt> as a directory separator, we get:
--   
--   <pre>
--   /ho         --&gt; /home/
--   /home/.ba   --&gt; /home/.bashrc
--   </pre>
completeFileName :: CompletionEnv -> String -> Maybe Char -> [FilePath] -> [String] -> IO ()

-- | <tt>completeWord compl input isWordChar completer</tt>: Complete a
--   <i>word</i> (or <i>token</i>) and calls the user <tt>completer</tt>
--   function with just the current word (instead of the whole input) Takes
--   the <a>CompletionEnv</a> environment <tt>compl</tt>, the current
--   <tt>input</tt>, an possible <tt>isWordChar</tt> function, and a user
--   defined <tt>completer</tt> function that is called with adjusted input
--   which is limited to the <i>word</i> just before the cursor. Pass
--   <a>Nothing</a> to <tt>isWordChar</tt> for the default <tt>not .
--   separator</tt> where <tt>separator = c -&gt; c <a>elem</a> "
--   \t\r\n,.;:/\\(){}[]"</tt>.
completeWord :: CompletionEnv -> String -> Maybe (Char -> Bool) -> (String -> [Completion]) -> IO ()

-- | <tt>completeQuotedWord compl input isWordChar completer</tt>: Complete
--   a <i>word</i> taking care of automatically quoting and escaping
--   characters. Takes the <a>CompletionEnv</a> environment <tt>compl</tt>,
--   the current <tt>input</tt>, and a user defined <tt>completer</tt>
--   function that is called with adjusted input which is unquoted,
--   unescaped, and limited to the <i>word</i> just before the cursor. For
--   example, with a <tt>hello world</tt> completion, we get:
--   
--   <pre>
--   hel        --&gt;  hello\ world
--   hello\ w   --&gt;  hello\ world
--   hello w    --&gt;                   # no completion, the word is just 'w'&gt;
--   "hel       --&gt;  "hello world" 
--   "hello w   --&gt;  "hello world"
--   </pre>
--   
--   The call <tt>(<a>completeWord</a> compl prefx isWordChar fun)</tt> is
--   a short hand for <tt>(<a>completeQuotedWord</a> compl prefx isWordChar
--   '\\' "'\"" fun)</tt>. Pass <a>Nothing</a> to <tt>isWordChar</tt> for
--   the default <tt>not . separator</tt> where <tt>separator = c -&gt; c
--   <a>elem</a> " \t\r\n,.;:/\\(){}[]"</tt>.
completeQuotedWord :: CompletionEnv -> String -> Maybe (Char -> Bool) -> (String -> [Completion]) -> IO ()

-- | <tt>completeQuotedWordEx compl input isWordChar escapeChar quoteChars
--   completer</tt>: Complete a <i>word</i> taking care of automatically
--   quoting and escaping characters. Takes the <a>CompletionEnv</a>
--   environment <tt>compl</tt>, the current <tt>input</tt>, and a user
--   defined <tt>completer</tt> function that is called with adjusted input
--   which is unquoted, unescaped, and limited to the <i>word</i> just
--   before the cursor. Unlike <a>completeQuotedWord</a>, this function can
--   specify the <i>escape</i> character and the <i>quote</i> characters.
--   See also <a>completeWord</a>.
completeQuotedWordEx :: CompletionEnv -> String -> Maybe (Char -> Bool) -> Maybe Char -> String -> (String -> [Completion]) -> IO ()

-- | A completion entry
data Completion
Completion :: String -> String -> String -> Completion

-- | actual replacement
[replacement] :: Completion -> String

-- | display of the completion in the completion menu
[display] :: Completion -> String

-- | help message
[help] :: Completion -> String

-- | Create a completion with just a replacement
completion :: String -> Completion

-- | Is the given input a prefix of the completion replacement?
isPrefix :: String -> Completion -> Bool

-- | <tt>completionsFor input replacements</tt>: Filter those
--   <tt>replacements</tt> that start with the given <tt>input</tt>, and
--   return them as completions.
completionsFor :: String -> [String] -> [Completion]

-- | Convenience: creates a completer function directly from a list of
--   candidate completion strings. Uses <a>completionsFor</a> to filter the
--   input and <a>completeWord</a> to find the word boundary. For example:
--   <tt><a>readlineEx</a> "myprompt" (Just (<a>wordCompleter</a>
--   completer)) Nothing</tt>.
wordCompleter :: [String] -> CompletionEnv -> String -> IO ()

-- | Use an rich text formatted highlighter from inside a highlighter
--   callback.
highlightFmt :: (String -> Fmt) -> HighlightEnv -> String -> IO ()

-- | A style for formatted strings (<a>Fmt</a>). For example, a style can
--   be <tt>"red"</tt> or <tt>"b #7B3050"</tt>. See the full list of valid
--   <a>properties</a>
type Style = String

-- | A string with <a>bbcode</a> formatting. For example <tt>"[red]this is
--   red[/]"</tt>.n
type Fmt = String

-- | Style a string, e.g. <tt>style "b red" "bold and red"</tt> (which is
--   equivalent to <tt>"[b red]bold and red[/]"</tt>). See the repo for a
--   full description of all <a>styles</a>.
style :: Style -> Fmt -> Fmt

-- | Escape a string so no tags are interpreted as formatting.
plain :: String -> Fmt

-- | Style a string that is printed as is without interpreting markup
--   inside it (using <a>plain</a>).
pre :: Style -> String -> Fmt

-- | Output rich formatted text containing <a>bbcode</a>. For example:
--   <tt>putFmt "[b]bold [red]and red[/][/]"</tt> All unclosed tags are
--   automatically closed (but see also <a>styleOpen</a>). See the repo for
--   more information about <a>formatted output</a>.
putFmt :: Fmt -> IO ()

-- | Output rich formatted text containing bbcode's ending with a newline.
putFmtLn :: Fmt -> IO ()

-- | Define (or redefine) a style. For example <tt>styleDef "warning"
--   "crimon underline"</tt>, and then use it as <tt><a>putFmtLn</a>
--   "[warning]this is a warning[/]"</tt>. This can be very useful for
--   theming your application with semantic styles. See also <a>formatted
--   output</a>
styleDef :: String -> Style -> IO ()

-- | Open a style that is active for all <a>putFmt</a> and <a>putFmtLn</a>
--   until it is closed again (<a>styleClose</a>).
styleOpen :: Style -> IO ()

-- | Close a previously opened style.
styleClose :: IO ()

-- | Use a style over an action.
withStyle :: Style -> IO a -> IO a

-- | <tt>setPromptMarker marker multiline_marker</tt>: Set the prompt
--   <tt>marker</tt> (by default <tt>"&gt; "</tt>). and a possible
--   different continuation prompt marker <tt>multiline_marker</tt> for
--   multiline input (defaults to <tt>marker</tt>).
setPromptMarker :: String -> String -> IO ()

-- | Disable or enable automatic tab completion after a completion to
--   expand as far as possible if the completions are unique. (disabled by
--   default). Returns the previous value.
enableAutoTab :: Bool -> IO Bool

-- | Disable or enable color output (enabled by default). Returns the
--   previous value.
enableColor :: Bool -> IO Bool

-- | Disable or enable sound (enabled by default). | A beep is used when
--   tab cannot find any completion for example. Returns the previous
--   value.
enableBeep :: Bool -> IO Bool

-- | Disable or enable multi-line input (enabled by default). Returns the
--   previous value.
enableMultiline :: Bool -> IO Bool

-- | Disable or enable duplicate entries in the history (duplicate entries
--   are not allowed by default). Returns the previous value.
enableHistoryDuplicates :: Bool -> IO Bool

-- | Disable or enable preview of a completion selection (enabled by
--   default) Returns the previous value.
enableCompletionPreview :: Bool -> IO Bool

-- | Disable or enable automatic indentation to line up the multiline
--   prompt marker with the initial prompt marker (enabled by default).
--   Returns the previous value. See also <a>setPromptMarker</a>.
enableMultilineIndent :: Bool -> IO Bool

-- | Disable or enable syntax highlighting (enabled by default). Returns
--   the previous value.
enableHighlight :: Bool -> IO Bool

-- | Disable or enable short inline help message (for history search etc.)
--   (enabled by default). Pressing F1 always shows full help regardless of
--   this setting. Returns the previous value.
enableInlineHelp :: Bool -> IO Bool

-- | Disable or enable automatic inline hinting (enabled by default)
--   Returns the previous value.
enableHint :: Bool -> IO Bool

-- | Set the delay in milliseconds before a hint is displayed (500ms by
--   default) See also <a>enableHint</a>
setHintDelay :: Int -> IO Int

-- | Disable or enable brace matching (enabled by default) Returns the
--   previous value.
enableBraceMatching :: Bool -> IO Bool

-- | Disable or enable automatic close brace insertion (enabled by default)
--   Returns the previous value.
enableBraceInsertion :: Bool -> IO Bool

-- | Set pairs of matching braces, by default <tt>"(){}[]"</tt>.
setMatchingBraces :: String -> IO ()

-- | Set pairs of auto insertion braces, by default
--   <tt>"(){}[]\"\"''"</tt>.
setInsertionBraces :: String -> IO ()

-- | <tt>setDefaultCompleter completer</tt>: Set a new tab-completion
--   function <tt>completer</tt> that is called by Isocline automatically.
--   The callback is called with a <a>CompletionEnv</a> context and the
--   current user input up to the cursor. By default the
--   <a>completeFileName</a> completer is used. This overwrites any
--   previously set completer.
setDefaultCompleter :: (CompletionEnv -> String -> IO ()) -> IO ()

-- | <tt>addCompletion compl completion</tt>: Inside a completer callback,
--   add a new completion. If <a>addCompletion</a> returns <a>True</a> keep
--   adding completions, but if it returns <a>False</a> an effort should be
--   made to return from the completer callback without adding more
--   completions.
addCompletion :: CompletionEnv -> Completion -> IO Bool

-- | <tt>addCompletionPrim compl completion deleteBefore deleteAfter</tt>:
--   Primitive add completion, use with care and call only directly inside
--   a completer callback. If <a>addCompletion</a> returns <a>True</a> keep
--   adding completions, but if it returns <a>False</a> an effort should be
--   made to return from the completer callback without adding more
--   completions.
addCompletionPrim :: CompletionEnv -> Completion -> Int -> Int -> IO Bool

-- | <tt>addCompletions compl completions</tt>: add multiple completions at
--   once. If <a>addCompletions</a> returns <a>True</a> keep adding
--   completions, but if it returns <a>False</a> an effort should be made
--   to return from the completer callback without adding more completions.
addCompletions :: CompletionEnv -> [Completion] -> IO Bool

-- | <tt>completeWord compl input isWordChar completer</tt>: Complete a
--   <i>word</i>,<i>token</i> and calls the user <tt>completer</tt>
--   function with just the current word (instead of the whole input) Takes
--   the <a>CompletionEnv</a> environment <tt>compl</tt>, the current
--   <tt>input</tt>, an possible <tt>isWordChar</tt> function, and a user
--   defined <tt>completer</tt> function that is called with adjusted input
--   which is limited to the <i>word</i> just before the cursor. Pass
--   <a>Nothing</a> to <tt>isWordChar</tt> for the default <tt>not .
--   separator</tt> where <tt>separator = c -&gt; c <a>elem</a> "
--   \t\r\n,.;:/\\(){}[]"</tt>.
completeWordPrim :: CompletionEnv -> String -> Maybe (Char -> Bool) -> (CompletionEnv -> String -> IO ()) -> IO ()

-- | <tt>completeWordPrim compl input isWordChar completer</tt>: Complete a
--   <i>word</i> taking care of automatically quoting and escaping
--   characters. Takes the <a>CompletionEnv</a> environment <tt>compl</tt>,
--   the current <tt>input</tt>, and a user defined <tt>completer</tt>
--   function that is called with adjusted input which is unquoted,
--   unescaped, and limited to the <i>word</i> just before the cursor. For
--   example, with a <tt>hello world</tt> completion, we get:
--   
--   <pre>
--   hel        --&gt;  hello\ world
--   hello\ w   --&gt;  hello\ world
--   hello w    --&gt;                   # no completion, the word is just 'w'&gt;
--   "hel       --&gt;  "hello world" 
--   "hello w   --&gt;  "hello world"
--   </pre>
--   
--   The call <tt>(<a>completeWordPrim</a> compl prefx isWordChar fun)</tt>
--   is a short hand for <tt>(<a>completeQuotedWordPrim</a> compl prefx
--   isWordChar '\\' "'\"" fun)</tt>. Pass <a>Nothing</a> to
--   <tt>isWordChar</tt> for the default <tt>not . separator</tt> where
--   <tt>separator = c -&gt; c <a>elem</a> " \t\r\n,.;:/\\(){}[]"</tt>.
completeQuotedWordPrim :: CompletionEnv -> String -> Maybe (Char -> Bool) -> (CompletionEnv -> String -> IO ()) -> IO ()

-- | <tt>completeQuotedWordPrim compl input isWordChar escapeChar
--   quoteChars completer</tt>: Complete a <i>word</i> taking care of
--   automatically quoting and escaping characters. Takes the
--   <a>CompletionEnv</a> environment <tt>compl</tt>, the current
--   <tt>input</tt>, and a user defined <tt>completer</tt> function that is
--   called with adjusted input which is unquoted, unescaped, and limited
--   to the <i>word</i> just before the cursor. Unlike <a>completeWord</a>,
--   this function takes an explicit function to determine <i>word</i>
--   characters, the <i>escape</i> character, and a string of <i>quote</i>
--   characters. See also <a>completeWord</a>.
completeQuotedWordPrimEx :: CompletionEnv -> String -> Maybe (Char -> Bool) -> Maybe Char -> String -> (CompletionEnv -> String -> IO ()) -> IO ()

-- | As <a>readline</a> but returns <a>Nothing</a> on end-of-file or other
--   errors (ctrl-C/ctrl-D).
readlineMaybe :: String -> IO (Maybe String)

-- | As <a>readlineEx</a> but returns <a>Nothing</a> on end-of-file or
--   other errors (ctrl-C/ctrl-D). See also <a>readlineMaybe</a>.
readlineExMaybe :: String -> Maybe (CompletionEnv -> String -> IO ()) -> Maybe (String -> Fmt) -> IO (Maybe String)

-- | <tt>readlinePrim prompt mbCompleter mbHighlighter</tt>: as
--   <a>readline</a> but uses the given <tt>mbCompleter</tt> function to
--   complete words on <tt>tab</tt> (instead of the default completer). and
--   the given <tt>mbHighlighter</tt> function to highlight the input
--   (instead of the default highlighter). See also <a>readlineEx</a> and
--   <a>readlinePrimMaybe</a>.
readlinePrim :: String -> Maybe (CompletionEnv -> String -> IO ()) -> Maybe (HighlightEnv -> String -> IO ()) -> IO String

-- | As <a>readlinePrim</a> but returns <a>Nothing</a> on end-of-file or
--   other errors (ctrl-C/ctrl-D). See also <a>readlineMaybe</a>.
readlinePrimMaybe :: String -> Maybe (CompletionEnv -> String -> IO ()) -> Maybe (HighlightEnv -> String -> IO ()) -> IO (Maybe String)

-- | Get the current prompt marker.
getPromptMarker :: IO String

-- | Get the current prompt continuation marker for multi-line input.
getContinuationPromptMarker :: IO String

-- | If this returns <a>True</a> an effort should be made to stop
--   completing and return from the callback.
stopCompleting :: CompletionEnv -> IO Bool

-- | Have any completions be generated so far?
hasCompletions :: CompletionEnv -> IO Bool

-- | Thread safe call to asynchronously send a stop event to a
--   <a>readline</a> which behaves as if the user pressed <tt>ctrl-C</tt>,
--   which will return with <a>Nothing</a> (or <tt>""</tt>). Returns
--   <a>True</a> if the event was successfully delivered.
asyncStop :: IO Bool

-- | Abstract highlight environment
data HighlightEnv

-- | Set a syntax highlighter. There can only be one highlight function,
--   setting it again disables the previous one.
setDefaultHighlighter :: (HighlightEnv -> String -> IO ()) -> IO ()

-- | Set a syntax highlighter that uses a pure function that returns a
--   bbcode formatted string (using <a>style</a>, <a>plain</a> etc). See
--   <a>highlightFmt</a> for more information. There can only be one
--   highlight function, setting it again disables the previous one.
setDefaultFmtHighlighter :: (String -> Fmt) -> IO ()

-- | Initialize the terminal for the <tt>term</tt> functions. Does nothing
--   on most platforms but on windows enables UTF8 output and potentially
--   enables virtual terminal processing. See also <a>withTerm</a>.
termInit :: IO ()

-- | Done using <tt>term</tt> functions. See also <a>withTerm</a>.
termDone :: IO ()

-- | Use the <tt>term</tt> functions (brackets <a>termInit</a> and
--   <a>termDone</a>).
withTerm :: IO a -> IO a

-- | Flush terminal output. Happens automatically on newline
--   (<tt>'\n'</tt>) characters as well.
termFlush :: IO ()

-- | Write output to the terminal where ANSI CSI sequences are handled
--   portably across platforms (including Windows).
termWrite :: String -> IO ()

-- | Write output with a ending newline to the terminal where ANSI CSI
--   sequences are handled portably across platforms (including Windows).
termWriteLn :: String -> IO ()

-- | Set the terminal text color as a hexadecimal number <tt>0x</tt>rrggbb.
--   The color is auto adjusted for terminals with less colors.
termColor :: Int -> IO ()

-- | Set the terminal text background color. The color is auto adjusted for
--   terminals with less colors.
termBgColor :: Int -> IO ()

-- | Set the terminal text color as an ANSI palette color (between
--   <tt>0</tt> and <tt>255</tt>). Use 256 for the default. The color is
--   auto adjusted for terminals with less colors.
termColorAnsi :: Int -> IO ()

-- | Set the terminal text background color as an ANSI palette color
--   (between <tt>0</tt> and <tt>255</tt>). Use 256 for the default. The
--   color is auto adjusted for terminals with less colors.
termBgColorAnsi :: Int -> IO ()

-- | Set the terminal text underline mode.
termUnderline :: Bool -> IO ()

-- | Set the terminal text reverse video mode.
termReverse :: Bool -> IO ()

-- | Reset the terminal text mode to defaults
termReset :: IO ()
instance GHC.Show.Show System.Console.Isocline.Completion
instance GHC.Classes.Eq System.Console.Isocline.Completion
