text processing utilities

Highlight documentation

Language Server Protocol support

Starting with version 4.0, highlight uses the LSP protocol to enhance its output.

What does this mean?

Many editors make use of "Language Servers" to get syntax information of various programming languages without the need to implement a deep understanding of the files' syntax they process. Well known code editors with LSP support are VSCode, Kate, vim, Emacs and Eclipse.

More information about LSP and editor support: https://langserver.org/

Examples

Rust code with default highlighting

//http://rosettacode.org/wiki/Fibonacci_n-step_number_sequences#Rust

struct GenFibonacci {
    buf:    Vec<u64>,
    sum:    u64,
    idx:    usize,
}

impl Iterator for GenFibonacci {
    type Item = u64;
    fn next(&mut self) -> Option<u64> {
        let result = Some(self.sum);
        self.sum -= self.buf[self.idx];
        self.buf[self.idx] += self.sum;
        self.sum += self.buf[self.idx];
        self.idx = (self.idx + 1) % self.buf.len();
        result
    }
}

fn print(buf: Vec<u64>, len: usize) {
    let mut sum = 0;
    for &elt in buf.iter() { sum += elt; print!("\t{}", elt); }
    let iter = GenFibonacci { buf: buf, sum: sum, idx: 0 };
    for x in iter.take(len) {
        print!("\t{}", x);
    }
}

fn main() {
    print!("Fib2:");
    print(vec![1,1], 10 - 2);

    print!("\nFib3:");
    print(vec![1,1,2], 10 - 3);

    print!("\nFib4:");
    print(vec![1,1,2,4], 10 - 4);

    print!("\nLucas:");
    print(vec![2,1], 10 - 2);
}

Rust code with LSP semantic tokens and hover information

//http://rosettacode.org/wiki/Fibonacci_n-step_number_sequences#Rust

struct GenFibonacci {
    buf:    Vec<u64>,
    sum:    u64,
    idx:    usize,
}

impl Iterator for GenFibonacci {
    type Item = u64;
    fn next(&mut self) -> Option<u64> {
        let result = Some(self.sum);
        self.sum -= self.buf[self.idx];
        self.buf[self.idx] += self.sum;
        self.sum += self.buf[self.idx];
        self.idx = (self.idx + 1) % self.buf.len();
        result
    }
}

fn print(buf: Vec<u64>, len: usize) {
    let mut sum = 0;
    for &elt in buf.iter() { sum += elt; print!("\t{}", elt); }
    let iter = GenFibonacci { buf: buf, sum: sum, idx: 0 };
    for x in iter.take(len) {
        print!("\t{}", x);
    }
}

fn main() {
    print!("Fib2:");
    print(vec![1,1], 10 - 2);

    print!("\nFib3:");
    print(vec![1,1,2], 10 - 3);

    print!("\nFib4:");
    print(vec![1,1,2,4], 10 - 4);

    print!("\nLucas:");
    print(vec![2,1], 10 - 2);
}

Output of syntax errors

//http://rosettacode.org/wiki/Fibonacci_n-step_number_sequences#Rust

struc GenFibonacci {expected one of `!` or `::`, found `GenFibonacci` expected one of `!` or `::`
    buf:    Vec<u64>,
    sum:    u64,
    idx:    usize,
}

Profiles

Language servers are configured in lsp.conf: 

Servers = {

  { Server="clangd", Exec="clangd", Syntax="c", Options={"--log=error"} },
  { Server="ccls", Exec="ccls", Syntax="c", Options={"-v=-3", "--"} },
  { Server="ccls-objc", Exec="ccls", Syntax="objc", Options={"-v=-3", "--"} },

  { Server="gopls", Exec="gopls", Syntax="go", Options={} },

  { Server="rls", Exec="rls", Syntax="rust", Options={} },
  { Server="rust-analyzer", Exec="rust-analyzer", Syntax="rust", Delay=250, Options={} },

  { Server="pyls", Exec="pyls", Syntax="python", Options={"--check-parent-process"} },

  { Server="R", Exec="R", Syntax="r", Options={"--slave", "-e", "languageserver::run()"} },

  { Server="clangd-win", Exec="F:\\LLVM\\bin\\clangd.exe", Syntax="c", Options={"--log=error"} },

}

The profile settings here may be set with the corresponding --ls-* options (see highlight -h for details).

Options

Command line options: 

Language Server options (*tbd):

     --ls-profile=<server>      read LSP configuration from lsp.conf
     --ls-delay=<ms>            set server initialization delay
     --ls-exec=<bin>            set server executable name
     --ls-option=<option>       set server CLI option (can be repeated)
     --ls-hover                 execute hover requests (HTML output only)
     --ls-semantic              retrieve semantic token types (requires LSP 3.16)
     --ls-syntax=<lang>         set syntax which is understood by the server
     --ls-syntax-error          retrieve syntax error information
                                  (assumes --ls-hover or --ls-semantic)
     --ls-workspace=<dir>       set workspace directory to init. the server

Important: LSP features require absolute input file paths.

Examples


highlight -I --ls-profile ccls --ls-workspace '/home/andre/Projekte/c' ⤦
           /home/andre/Projekte/c/re.cpp  --ls-hover ⤦
           > /home/andre/Projekte/c/re.cpp.ccls.html

highlight --ls-profile rls --ls-workspace '/home/andre/Projekte/rust/hello_world' ⤦
           /home/andre/Projekte/rust/hello_world/src/main.rs ⤦
           --outdir ~/test_out

highlight -I --ls-profile clangd --ls-workspace '/home/andre/Projekte/export/highlight-4.0.beta1/src/' ⤦
           /home/andre/Projekte/export/highlight-4.0.beta1/src/core/datadir.cpp  --out-format html ⤦
           -s base16/chalk --ls-semantic --ls-syntax-error

The GUI offers an LSP tab to enable these options.

Tupel7