Skip to content

Latest commit

 

History

History
452 lines (309 loc) · 12.4 KB

README.md

File metadata and controls

452 lines (309 loc) · 12.4 KB
Raw

melpa badge melpa stable badge jcs-elpa badge

quickrun.el

Introduction

quickrun.el is Emacs port of quickrun.vim.

CI

quickrun.el is a extension to execute editing buffer. quickrun.el is similar to executable-interpret, but quickrun.el provides more convenient commands. quickrun.el execute not only script languages(Perl, Ruby, Python etc), but also compiling languages(C, C++, Go, Java etc) and markup language.

Requirements

  • Emacs 26.1 or higher.

Installation

You can install quickrun.el from MELPA with package.el.

Or install directly:

$ cd load-path-dir
$ wget https://raw.githubusercontent.com/syohex/emacs-quickrun/master/quickrun.el

After Installation add following to your configuration file(~/.emacs.d/init.el, ~/.emacs etc)

(require 'quickrun)

Support Programming Languages

quickrun.el supports following programming languages and markup languages as default. But you can register your own command and apply other languages.

Programming Language(commands used)

  • Assembly Language (nasm, masm)
  • Applescript (osascript)
  • C (gcc / clang / Visual C++)
  • C++ (g++ / clang++ / Visual C++)
  • C# (dotnet / mono)
  • Objective-C (gcc -objc)
  • D Language (dmd)
  • Fortran (gfortran)
  • Java (javac / java)
  • Perl (perl)
  • Perl6 (perl6)
  • Ruby (ruby / mruby)
  • Python (python)
  • PHP (php)
  • Emacs Lisp (elisp)
  • Scheme (gosh)
  • Smalltalk (gst)
  • Racket (racket)
  • Common Lisp (clisp / sbcl / ccl)
  • Clojure (jark / clj-env-dir)
  • Javascript (node / v8 / js / jrunscript / cscript / deno)
  • Coffee Script (coffee)
  • JSX (jsx)
  • Markdown (Markdown.pl / bluecloth / kramdown / pandoc / redcarpet)
  • Haskell (runghc)
  • Go Language (go / gccgo)
  • Io (io)
  • Lua (lua)
  • Groovy (groovy)
  • Scala (scala) Please use UTF-8 encoding
  • HAML (haml)
  • SASS (sass)
  • LESS (lessc)
  • Erlang (escript)
  • OCaml (ocamlc)
  • F# (fsharpc)
  • ShellScript (shebang's shell)
  • AWK (awk)
  • Rust (rustc)
  • Dart (dart)
  • Elixir (elixir)
  • TypeScript (tsc)
  • Tcl (tclsh)
  • Swift (swift, xcrun)
  • ATS2 (patscc)
  • R (Rscript)
  • Nim/NimScript (nim)
  • Julia (julia)
  • Gnuplot (gnuplot)
  • Kotlin (kotlin)
  • Crystal (crystal)
  • V (v)
  • Zig (zig)
  • Nix (nix)

See also quickrun--support-languages global variable.

Basic Usage

quickrun

Execute current buffer. If quickrun.el does not find command-key, then quickrun.el asks you command-key(You always input command if you use C-u prefix key)

quickrun-select

Like quickrun command but select the backend before the execution.

quickrun-region

Execute region. (Java is not supported)

quickrun-with-arg

Execute current buffer with arguments. quickrun.el asks you command line argument

quickrun-shell

Execute current buffer in eshell for interactive command such as program which reads input from STDIN.

quickrun-compile-only

Compile current buffer with compile.el framework, not execute. quickrun with C-u C-u prefix behaves same as quickrun-compile-only.

quickrun-compile-only-select

Like quickrun-compile-only command but select the backend before the execution.

quickrun-replace-region

Replace region of code with its output.

quickrun-autorun-mode

Minor mode which executes quickrun after saving buffer.

helm-quickrun

M-x quickrun with helm interface

anything-quickrun

M-x quickrun with anything interface

Note

If quickrun returns command not found, please check (executable-find "THE_COMMAND_NAME") [for example (executable-find "gnuplot")] . If this returns nil, I strongly recommend you use https://github.com/purcell/exec-path-from-shell

Send File to STDIN

If executed_file.qrinput(like foo.c.qrinput) is existed in directory same as executed buffer file, quickrun.el sends its content to stdin of executed program. Please set quickrun-input-file-extension to nil If you want to disable this feature.

Customize

quickrun-focus-p(Default: t)

If this value is nil, quickrun.el does not move focus to output buffer.

quickrun-truncate-lines(Default: t)

The truncate-lines' value for quickrun` buffer.

User Defined Command

You can add your own command or override existsing command by quickrun-add-command as below.

;; Use this parameter as C++ default
(quickrun-add-command "c++/c1z"
  '((:command . "g++")
    (:exec    . ("%c -std=c++1z %o -o %e %s"
         "%e %a"))
    (:remove  . ("%e")))
  :default "c++")

;; Use this parameter in pod-mode
(quickrun-add-command "pod"
  '((:command . "perldoc")
    (:exec    . "%c -T -F %s"))
  :mode 'pod-mode)

;; You can override existing command
(quickrun-add-command "c/gcc"
  '((:exec . ("%c -std=c++1z %o -o %e %s"
          "%e %a")))
  :override t)

First argument of quickrun-add-command is command key. Second argument of it is command parameter, which is described laster. quickrun-add-command also takes key parameters, :default, :mode, :override.

Argument Description
:default lang Use this command parameter as default in specified language
:mode mode this command parameter in specified mode
:override bool Override existing parameter with specified parameter

Command Parameter

Command alist has following parameters,

:command(mandatory parameter)

Command name. %c is expanded into this value.

:cmdopt(optional)

Command(:command) option. %o is expanded into this value.

:exec

Executed commands. You can also set command list parameter. If you set list parameter, quickrun.el executes command list in order.

If this parameter is omitted, quickrun.el use default execute command template "%c %o %s %a".

:timeout(optional)

Timeout in seconds for the process spawn by the command. This value takes precedence over the quickrun-timeout-seconds custom variable.

:compile-only

Command exected by quickrun-compile-only. This option is used for syntax check or converting another language(e.g. CoffeeScript => JavaScript).

:compile-conf

Configuration of quickrun-compile-only. This parameter must be alist.

:remove

Remove files after executing. If command create some intermediate files, you should set this parameter. :remove value is atom or list.

:outputter

Please see Outputter section.

:default-directory

Directory where commands are executed.

:tempfile

Use temporary file or not. quickrun.el uses temporary file if you omit this parameter.

NOTE: If you set this parameter, you cannot use quickrun-region.

:description

Description of this command. This parameter is used in helm-quickrun or anything-quickrun

Placeholders

You can use following placeholders in command parameter

Placeholder Expanded
%c Command
%o Command line option
%s Source(absolute path)
%a Script's arguments
%n Source without extension(absolute path)
%N Source without extension(nondirectory)
%d Directory name of Source(absolute path)
%e Source with executable suffix(absolute path)
%E Source with executable suffix(nondirectory)

Source file name(%s, %n etc) is not original file name except Java language. Because quickrun.el copys source file to temporary file firstly.

Change Default Command

quickrun-set-default changes default command in language that is registerd multiple command parameters(like c, c++,Javascript).

(quickrun-set-default "c" "c/clang")

This means that quickrun uses "c/clang" for C files.

Timeout Seconds

quickrun.el kills process if program run over 10 seconds as default. This avoids infinite loop program or endless program by some mistakes. You control timeout second to set quickrun-timeout-seconds. This feature is disabled if quickrun-timeout-seconds is nil. The timeout can also be set per command with the :timeout parameter. (You can also kill process by C-c C-c in quickrun buffer)

Key bindings in quickrun buffer

Key Command
q Close quickrun window
C-c C-c Kill quickrun process

Buffer Local Variables

Buffer local variables is priority to default parameters.

quickrun-option-cmd-alist

Command alist.

quickrun-option-command

Command key(Expanded to %c)

quickrun-option-cmdkey

Command key of command parameter.

quickrun-option-cmdopt

Command option(Expanded to %o)

quickrun-option-args

Program argument(Expanded to %a.)

quickrun-option-shebang

If this value is non-nil and first line of source file is started "#!", the following string is treated as ":command".

quickrun-option-outputter

Outputter function. See Outputter section

Example of buffer local variable

Setting C++11.

#include <iostream>
#include <vector>
#include <string>

int main (int argc, char *argv[])
{
    std::vector <std::string> lst = { "a", "b", "c", "d" };

    for (auto x : lst) {
        std::cout << "[" << x << "]" << std::endl;
    }

    for (auto i = 1; i < argc; i++) {
        std::cout << "[" << argv[i] << "]" << std::endl;
    }

    return 0;
}

/*
  Local Variables:
  quickrun-option-cmd-alist: ((:command . "g++")
                              (:exec    . ("%c -std=c++0x -o %n %s"
                                           "%n apple orange melon"))
                              (:remove  . ("%n")))
  End:
*/

Hooks

quickrun-after-run-hook

Run hooks after execute all commands.

Outputter

Outputter is a function for processing command output. Default outputter is to output to *quickrun* buffer and processing ANSI Color sequence.

quickrun.el defines following functions as default.

buffer:buffername

Output to buffer. outputter buffer sample

file:filename

Output to file. outputter file sample

variable:varname

Output to variable. outputter variable sample

browser

Output to Web browser(using function browse-url) outputter browser sample

message

Output to *Message* buffer(using function message) outputter message sample

multi

Use multiple outputters. outputter multi sample

null

No output. outputter null sample

Using quickrun as function from other functions

quickrun can be used as function from other functions. You can pass configuration by :source argument. Sample is following:

(defun test-perl ()
  (interactive)
  (let* ((cmd "git rev-parse --show-toplevel")
         (topdir (with-temp-buffer
                   (call-process-shell-command cmd nil t nil)
                   (goto-char (point-min))
                   (if (re-search-forward "^\\(.+\\)$" nil t)
                       (match-string 1)))))
    (quickrun :source `((:command . "prove")
                        (:default-directory . ,topdir)
                        (:exec . ("%c -bv --color %s"))))))