============== GHCiTUI MANUAL ============== ------------ CLI Synopsis ------------ .. code-block:: Usage: ghcitui [--version] [--debug-console] [-v] [--daemon-log LOGFILE] [-c|--cmd CMD] [-C|--workdir DIR] [TARGET] ghcitui: A TUI interface for GHCi Available options: -h,--help Show this help text --version Print the version number and exit --debug-console Display the debug console -v Set verbosity for output logs. Pass multiple times (e.g -vvv) to increase the logging. Use --daemon-log to specify where the logs go. --daemon-log LOGFILE File path for debugging daemon logs. Used with -v. Setting this to 'stdout' or 'stderr' sends logs to each, respectively. Defaults to /tmp/ghcitui.log. -c,--cmd CMD Command to start the internal interpreter -C,--workdir DIR Set working dir --------------------- Starting and Stopping --------------------- ******** Starting ******** GHCiTUI runs a REPL in the current directory by default. By default, it launches ``cabal repl``. .. code-block:: bash $ cd your/cabal/project/root/directory $ ghcitui You can specify another starting directory with the ``-C `` flag. .. code-block:: bash $ ghcitui -C some/other/directory You can specify a different starting command with ``--cmd `` or ``-c ``. .. code-block:: bash $ ghcitui -c 'ghci' $ ghcitui --cmd 'stack ' This is handy if you don't want to use ``cabal repl``. Any executable can be used with ``--cmd`` is that the underlying command communicates textually through ``ghci``. ******** Stopping ******** To quit, press ```` or ``q`` while in the code viewport panel to quit. While not in the code viewport panel, you may press ```` to get to the viewport panel. ------ Layout ------ GHCiTUI is an in-terminal viewer for GHCi. The TUI is broken up into three primary panels, with some additional auxiliary panels for special use cases: .. code-block:: ┌──────────────────┬──────┐ │ │ Info │ │ │ │ │ Source Viewer │ │ │ │ │ │ │ │ ├──────────────────┤ │ │ │ │ │ Live Interpreter │ │ │ │ │ └──────────────────┴──────┘ **Source Viewer:** This panel shows source code. You can step, continue, and toggle breakpoints among other operations in this panel. **Live Interpreter:** This panel shows the GHCi/REPL passthrough. You can enter expressions and GHCi commands here like you would normally, with some additional keybindings. **Info:** This panel displays miscellaneous info about whatever is currently running. For example, it can display the current bindings, loaded modules, and the current program trace. ---------- Navigation ---------- At any point in time, you can revert back to the Source Viewer panel with the ```` key, and you can always quit by hitting ```` in the Source Viewer panel. On top of each panel is a label where the navigation key combination is located. For example, the key combination above the Modules panel displays ``[M]``. Pressing this key combination will move the focus to that panel. ----------- Keybindings ----------- At this time, keybindings are hardcoded. This will hopefully change in the future with a keybinding configuration file. ************* Source Viewer ************* - ``?``: Display help inside GHCiTUI. - ``Ctrl+x``: Toggle between the Source Viewer and the Live Interpreter panels. - ``M``: Switch to the module panel. - ````, ``q``: Quit. - ````, ``k``: Move the cursor up. (``j`` and ``k`` from Vim keybinds) - ````, ``j``: Move the cursor down. (``j`` and ``k`` from Vim keybinds). - ````: Move the source viewer one page up. - ````: Move the source viewer one page down. - ``+``, ``-``: Increase/decrease the left panel sizes. - ``b``: Toggle breakpoint at current line. Not every line in a source file can have a breakpoint placed on it. - ``s``: Advance execution by one step. Same as the ``:step`` in GHCi. - ``c``: Advance execution until next breakpoint. Same as ``:continue`` in GHCi. - ``t``: Advance execution until next breakpoint under tracing. Same as ``:trace`` in GHCi. - ``Ctrl+c``: Send an interrupt to the daemon. Useful for breaking infinite loops. *********************** Live Interpreter (REPL) *********************** - ``Ctrl+x``: Toggle between the Source Viewer and the Live Interpreter panels. - ````: Switch to Source Viewer. - ```` while in scrolling mode: Exit scrolling mode. - ````: Scroll back in time through the REPL command history. - ````: Scroll forward in time through the REPL command history. - ````: Scroll the Live Interpreter window one page up. - ````: Scroll the Live Interpreter window one page down. - ``Ctrl+n``: Toggle scrolling mode. - ``+``, ``-`` while in scrolling mode: Increase/decrease the live panel size. - ````: Enter a command to the REPL. - ````: Autocomplete (yes there's basic autocomplete support) - ``Ctrl+c``: Send an interrupt to the daemon. Useful for breaking infinite loops. ******* Modules ******* - ``?``: Display help inside GHCiTUI. - ``Ctrl+x``: Switch to the Live Interpreter. - ````, ``C``: Switch to Source Viewer. - ````, ``k``: Move the module selection up. - ````, ``j``: Move the module selection down. - ``+``, ``-``: Increase/decrease the info panel size. - ````, ``o``: Open the selected module. ------- Tracing ------- Tracing works the same as in GHCi, but there's a panel to display the current backtrace in the "Trace History" subpanel. To populate the Trace History panel, run ``:trace`` in the Live Interpreter panel with a breakpoint set. For example: .. code-block:: $ cat Main.hs main = putStrLn "Hello" >> putStrLn "World!" And then inside ghcitui... .. code-block:: # In the Live Interpreter Panel... ghci> :l Main.hs [1 of 2] Compiling Main ( Main.hs, interpreted ) Ok, one module loaded ghci> :b main Breakpoint 0 activated at Main.hs:1:8-44 ghci> :trace main Stopped in Main.main, Main.hs:1:8-44 _result :: IO () = _ ghci> :step This should then populate the Trace History panel. ------------------------------- Reporting Bugs/Feature Requests ------------------------------- You can file bugs and feature requests both at: https://github.com/CrystalSplitter/ghcitui/issues Please check to see if the bug/request already exists before filing a new one.