Manual

Getting started

Why Liquid?

Liquid is not for everyone! 

 

It is for power users who like programming, preferable Clojure, plain text and efficiency. 

 

Liquid is a starting point for building your own customized editor. 

 

Liquid is really good for exploring code since you can load code piece by piece, like in a repl, but without the text disappearing. 

 

Focus has been on text and a distraction free experience, which means: 

 

  • No pop ups during typing, but a typeahead that can be customized for whatever and assigned to whatever.
  • No menus, keyboard should be learned and tweaked.
  • Non blinking cursor, for a calm experience.
  • No projects, just add project root to typeahead.
  • Just you, the text and a flexible arme of functions to apply, based on keypresses and contexts.
  •  

    By using only keymappings and editor actions, it is possible to transform Liquid into a UI for anything for away text editing. 

     

    Therefore the name "Liquid". 

    Terminal

    Liquid can be executed inside a JFrame, as a server with access through a browser, but the intended way is through the Terminal. Performance and usage is optimized for terminal. JFrame is primarily to support Windows, to some extend. 

     

    On linux the terminal "Terminology" has turned out to be a very good choice. It performs very well together with Liquid. 

    Installing Liquid

    Overview

    Liquid is both a program and a library. It can be used just standalone, as part of a project or as part of a dedicated project. The last option is the choice if you want a general purpose editor, which is easy to extend. 

     

    The steps are: 

     

    1. Make a project and include Liquid as a dependency. 

    2. Load Liquid through the projects main function. This way any additional customizations can be loaded as well. 

    3. Include any external library to be used inside Liquid as a depencency.  

     

    External libraries can be any Java or Clojure library, also libriaries which were not designed to be Liquid extensions. 

     

    Look at or clone liquid-starter-kit: It illustrates how simple it is, to add some random Java JSON formatter, as extension, to allow Liquid to have a shortcut to reformat the selected text using the JSON formatter. 

     

    You can also just use liq.jar as standalone, but please consider what power lies in the library approach! 

    Idiomatic install

    The idiomatic way to install Liquid uses the clj command line tool provided by Clojure. (Windows users need to use classpaths or leiningen instead) 

     

    Most people, who will want to use Liquid, probably also want to extend and modify it. It only takes a few steps to do the install, in a fully flexible way. The fundamental approach, is to create your own project and use Liquid as a dependency, together with all other libraries, you wish to access from within Liquid. The setup presented below is almost minimal, with just a few extras to illustrate how to include other libraries. 

     

    1. Create a folder, lets say "myliquid". Create "./myliquid/deps.edn" with the following content: 

     

    {:deps {mogenslund/liquid {:git/url "https://github.com/mogenslund/liquid.git" :rev "9b335028e4e2cd4bf81ad845f683e7c6e83b9f61"}
            mogenslund/additives {:git/url "https://github.com/mogenslund/additives.git" :rev "17874b2388c66188f3fbc45be316e96603099aa1"}
            com.google.code.gson/gson {:mvn/version "2.8.2"}}
     :paths ["src"]}
    

     

    This includes "liquid", an extensions "additives", some random Java librarie "gson" and the local sourc "src" in "./myliquid". 

     

    2. Create file "./myliquid/src/myliquid/core.clj" with the following content: 

     

    (ns myliquid.core
      (:require [dk.salza.liq.core :as liq-core]
                [dk.salza.liq.editor :as editor]))
    
    (defn -main
      [& args]
      (liq-core/set-defaults)
      (apply liq-core/startup args)
      (liq-core/init-editor))
    

     

    (For a more detailed example, look at liquid-starter-kit

     

    In a terminal navigate to "./myliquid" and execute 

     

    clj -m myliquid.core
    

     

    to start Liquid. 

    Basic text operations

    Moving around

    Moving the cursor around in Liquid is done very vim-like. As default there are two keyboard-modes. Any number of modes could potentially be implmeneted (advanced typic). The keymapping defining a mode can also be assigned a color, so the cursor color indicates which mode is active. 

     

    The tab key is used as default to switch between the two default modes. 

     

    Insert mode is when the cursor is green. Then most keys will insert a character. 

     

    Navigation mode is when the cursor is blue. Then most keys will perform a navigation task. 

     

    The basic movement commands are: 

     

          j:   Left
          l:   Right
          i:   Up
          k:   Down
          J:   Beginning of line
          L:   End of line
    

     

    Notice that the movement keys are layed out like arrow keys with base on the home row. And using shift will extend the movement to the beginning and end of the line. 

     

    The "g" is a "goto" command, so 

     

          gg:  Beginning of buffer
          gi:  Goto headline or function (using typeahead)
          gl:  Goto line (using typeahead)
          G:   End of buffer
    

     

    See Cheatsheet for further commands. 

    Selections

    Selecting is done using the "v" key in navigation mode (blue cursor). When "v" is pressed the selection mark is set. Moving the cursor around using the usual navigation keys will now make a selection. By pressing "v" again, selection is cancelled. 

     

    Selected text can be deleted, copied, cut and functions can be used to transform the selected text. 

     

          v:   toggle selection
          dd:  Cut selection (delete). Will delete the line, if nothing is selected.
          gl:  Goto line (using typeahead)
          G:   End of buffer
    

     

    Transforming selection using functions is an advanced topic. 

    Contexts

    Liquid has a "context" functions that can be used to analysize the context around the cursor. The result is a type and a value. Types could be "file", "url" or "function", and value the corresponding text. Contexts can be used to apply context dependend actions like navigating to file, open url in browser or navigate to function. Some default keybindings in navigation mode (blue cursor) are: 

     

          yc:  Copy context (Word, filename, url, ...)
          gc:  Show current context in prompt
          O:   Apply default context action
    

    Text manipulation

    Using keys like "I" and "K" in navigation mode (blue cursor) will move lines up and down. The keys are the shift-versions of the up and down movement keys. 

     

          x:   Delete char
          Backspace: Delete backward
          yy:  Copy line or selection
          yc:  Copy context (Word, filename, url, ...)
          pp:  Paste on new line
          ph:  Paste
          o:   Insert new line
          r:   Replace with next char pressed
          I:   Move line up
          K:   Move line down
    

    Basic editor tasks

    Main typeahead

    The main typeahead is a very central part of Liquid. Use it to 

     

  • Change buffer
  • Open files
  • Execute functions
  • Insert snippets
  • Insert functions from classpath
  •  

    The typeahead is activated by pressing C-space. Pressing C-space again will load a new typeahead where functions from the classpath can be choosen. 

     

    The basic keybindings are: 

     

          C-space: Activate main typeahead
          C-space: C-space a second time to load list of functions on classpath
          Enter: Activate current result
          alpha-num: Typeahead
          C-k: Select next result
          C-i: Select previous result
          C-g: Cancel typeahead
    

     

    In the typeahead spaces are considered willcards, så "my e.ht" will match "myfile.html". 

    Extending the main typeahead

    Reusing the "myliquid" example from the Installation section, here are some examples, how to add functionality to the main typeahead: 

     

    (ns myliquid.core
      (:require [dk.salza.liq.core :as liq-core]
                [dk.salza.liq.editor :as editor]))
    
    (defn -main
      [& args]
      (liq-core/set-defaults)
      (apply liq-core/startup args)
      (liq-core/init-editor)
      (editor/add-searchpath "~/proj/someproject")
      (editor/add-file "/tmp/tmp.clj")
      (editor/add-snippet "(System/currentTimeMillis)")
      (editor/add-interactive
        "now"
        (fn []
          (editor/insert
            (.format
            (java.text.SimpleDateFormat. "yyyy-MM-dd")
            (new java.util.Date)))))
      (editor/updated))
    

     

    These lines will: 

     

  • Add all files below ~/proj/someproject to typeahead
  • Add the file /tmp/tmp.clj to typeahead
  • Add the snippet "(System/currentTimeMillis)" to typeahead. Will insert the text into the editor.
  • Add a function "now" to typeahead. The function will insert the current date into the editor.
  •  

    Of cause it is possible to make program snippets and loops that adds items to typeahead dynamically. 

    Switching buffers

    Switching buffers is done by using the main typeahead (??? Link here). 

     

    There is a special function for navigating to the previous buffer. It is activated by using "m" in navigation mode (blue cursor). Often you need to navigate forth and back between two buffers. Just open the first buffer through main typeahead, then the second buffer. Now you can switch between the two buffers using "m".  

     

          C-space: Activate main typeahead
          m:   Previous buffer
    

    Finding files

    To open a file in Liquid use C-f to open another typeahead which shows the files in the current directory. Typeahead can be used to filter the files. Backspace, for navigating to the parent relative to the current folder. 

     

    If a folder is activated, using Enter, then the typeahead will change to that folder. 

     

          C-f: Activate the find-file typeahead
          C-k: Select the next file
          C-i: Select the previous file
          C-g: Cancel
          Enter: Activate current result
    

     

    Buffers will be named with the full path of the file. If a file is already open, the buffer containing that file will be activated. 

    Saving files

    To save a file press "s" in navigation mode (blue cursor): 

     

          s:   Save file
    

     

    Dirty files will be marked with a star in the statusline at the bottom of the buffer. 

     

    Evaluate code

     

          C-e: Evaluate current file without capturing output (for (re)-loading internal stuff)
          E:   Evaluate current file
          e:   Evaluate current s-expression
          1:   Highlight boundries of the  current s-expression
          2:   Select current s-expression
               (Multiple presses will make the cursor switch between begin and end parenthesis.)
    

    Macros

    Macros are for recording some keypresses and replay them again. Always start in navigation mode (blue cursor) and end in navigation mode again, when stopping recording. 

     

          H:   Start and stop recording
          h:   Play recording
    

    Extending Liquid

    Redefine global keys

     

        (editor/set-global-key "f5" editor/forward-line)
    

    Redefine local keys

     

        (textapp/set-navigation-key "0" #(dk.salza.liq.editor/switch-to-buffer "scratch"))
    

    Redefine eval functions

    Typing "E" in navigation mode (blue cursor), that is shift+e, will evaluate the file. It is possible to execute different commands depending on the file extension. 

     

    The code below will make js files be executed with nodejs: 

     

        (editor/set-eval-function "js" #(cmd "node" %))
    

    Adding snippets to typeahead

    Adding functions to typeahead

    Adding folders to typeahead

    Customized typeaheads