file-exec(3)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

NAME

file-exec - Executes the current buffer using a compiler or interpreter
file-format - Format the current buffer using a dedicated formatter
file-lint - check the current buffer for problems using a dedicated linter
major-mode-tools-setup - File major-mode tool setup

SYNOPSIS

file-exec [ "command-line-arguments" ]
file-format
file-lint
major-mode-tools-setup

DESCRIPTION

The file-exec macro for interpreted languages executes the current buffer using the command line interpreter defined for this language. In case of programming languages which needs to be compiled, first the code is compiled to machine code and then executed. Before the program is executed save-some-buffers(2) is executed to allow the user to ensure that all relevant buffers are saved. If bit 0x01 of the numeric argument n is clear then all modified buffers are automatically saved, when set (the default) the user is prompted for each buffer. If bit 0x02 of the numeric argument is clear (the default) the user is prompted for any additional command-line-arguments which are passed to application or the script command. The arguments given are stored in a buffer variable, and used as the default arguments next time the script is executed.

After executing the program, an *FHOOK-exec* buffer is opened with the output of the script or program. The script executes the current buffer if required using the current MicroEmacs character encodings.

The file-format macro formats the current buffer using a dedicated formatting tool for the buffer's programming language. For R for example, the package `formatR` must be pre-installed by the user, this is typically done by running `install.packages('formatR')` within an R console.

The file-lint macro checks the currently edited file using a language specific linter, for example for R, the package `lintr` must be installed by the user for instance using the usual `install.packages('lintr)` syntax from within a R console.

The command opens an *FHOOK-lint* buffer with the output from the linter, warnings or styling issues raised are typically high-lighted. the buffer is configured to for get-next-line(2) to make traverse through the issues as easy as possible.

SETUP

The major-mode-tools-setup command can be used to configure the three tools for the current file's major mode, this dialog can be accessed by clicking on the bottom left Tools button in the major-mode-setup(3) dialog. Note, however, that as the tool configurations should work with all files of the same major-mode, the command-lines should use tags (%l...) rather than literal file names. Of particular importance are the %f, %p and %" tags, for further details see the documentation for the Command field of file-tool-setup(3), which uses the same format.

The exec-file command has 3 additional configuration checkboxes; when enabled, Raw output suppresses the 3 line header, which details the location and command-line being run, and stops long lines in the command output from being wrapped. No line wrap also stops the wrapping of long lines, but does not suppress the header. When enabled, Supports buffers indicates that, if the current buffer does not have a file name, the exec-file command can save the buffer contents to a temporary file and then run the given utility with the temp file. This typically requires the execution process to not be dependent on any other local content. Note that the generated temp file is removed 20 seconds after the start of the execution so this option should not be used if the execution requires the file to be present for longer.

For creators of MicroEmacs file hooks, the file tools can also support the use of multiple interpreters/tools, e.g. clang and gcc to compile a C file. The configuration of each tool can include tests to verify the availability of the tool on the current computer as well as the required command-line to run.

To get the file-exec, file-format and file-lint commands properly working, configuration variables are typically required for the current buffer's major-mode. For example, the following configuration is taken from hkpython.emf:

set-variable .fhook-python.coms "\bpython3\bpython2\bpython\b" 
set-variable .fhook-python.coms-windows "\b~/AppData/Local/Programs/Python/Python\\d+\\(-\\d+\\)?/python.exe\bC:/Python\\d+\\(-\\d+\\)?/python.exe\b" 
set-variable .fhook-python.exec1   "\b%v[com]\b\b\b\b%\"%v[com]%\" \"%p%f\" %v[args|20|Additional command-line arguments|]\b" 
set-variable .fhook-python.format1 "\bruff\bruff -h\b0\b\bruff format %\"%f%\"\bRuff\b" 
set-variable .fhook-python.format2 "\b%v[com]\b%\"%v[com]%\" -m yapf -h\b0\b\b%\"%v[com]%\" -m yapf -i %\"%p%f%\"\bYapf\b" 
set-variable .fhook-python.format3 "\b%v[com]\b%\"%v[com]%\" -m black -h\b0\b\b%\"%v[com]%\" -m black -q %\"%p%f%\"\bBlack\b" 
set-variable .fhook-python.lint1   "\bruff\bruff -h\b0\b\bruff check %\"%f%\"\bRuff\b" 
set-variable .fhook-python.lint2   "\b%v[com]\b%\"%v[com]%\" -m pylint -h\b0\b\b%\"%v[com]%\" -m pylint %\"%p%f%\"\bPylint\b:\\d+:\\d+: E\\d+:\b:\\d+:\\d+: W\\d+:\b:\\d+:\\d+: [CR]\\d+:\b"

Where the .exec#, .format# and .lint# variables configure a tool to use the specified utility, python hhas been configured to check for and potentially use 3 different utilities for formatting, file-format will use the first utility found. The format of these variables is as follows:

|<program>|<test>|<test-success-exit-code>|<path>|<command-line>|<ID>|<err-regex>|<wrn-regex>|<inf-regex>|<flags>|

Only the <program> and <command-line> parameters are required, <test> and <test-success-exit-code> parameters should only be used when the mere presence of the <program> is not a guarantee that the utility is fully installed and correctly running. For example, Yapf is a python module that must be installed in addition to python itself, to the presence of a python script engine, i.e. the python3 program, is no guarantee that the yapf module has also been installed. Instead the command "<python> -m yapf -h" and the exit code is tested, 0 being a success.

NOTES

file-exec, file-format and file-lint are macros defined in hktools.emf. For programming lanuages like C++, Fortran and R there are already useful variable defaults defined in the hkHOOK.emf files, the user can overwrite these settings using major-mode-tools-setup.

The executables or the interpreters will need to be installed in the system path for the commands to function correctly, otherwise the full path will need to be given in the settings.

When setting up tools it can be useful to add "%v[<tool>-opts|]" in places where standard options, such as user name or server, may need to be supplied. Users can then define a .fhook-<major-mode>.<tools>-opts variable in their my<major-mode>.emf file so they do not have to type these values every time they restart MicroEmacs. For example, to execute an SQL statement in MySql the base server, access and database details are required, rather than require the user to supply this every time the main command can be defined as:

mysql %v[exec-opts|] %v[exec-args|20|Additional command-line arguments|--host=localhost --user=<user> --password=<passwd> <db-name>] -e 'source %p%f'

The user can then add the following line to their mysql.emf file:

set-variable .fhook-sql.exec-opts "--host=localhost --user=JDOE --password=12345"

So the base DB access is pre-defined and only the database name is required, a better default can also be supplied by adding:

set-variable .fhook-sql.exec-args "MYDB"

The user will still be prompted, but the default is now likely to be correct. The user can avoid being prompted by defining the variable var-name-np ('np' = no-prompt), i.e. adding:

set-variable .fhook-sql.exec-args-np "MYDB"