By Renée French
Nyne
Nyne automates what are typically manual tasks when using Acme. Think of nyne as
the .vimrc
of Acme. Instead of needing to set custom indentation settings and
manually run external commands like clang-format against your file, nyne does
all of that for you. It can also optionally expand hard tabs to soft tabs, which
is a feature not included in Acme by default.
Included in a full install of nyne are bundled utilities for acme:
nyne
: The core autoformatting engine that is run from within acme
nynetab
: Implements tab expansion for the given buffer if not configured for
nyne
a+
: Indent selected source code
a-
: Unindent selected source code
com
: Comment/uncomment selected source code
Configuration
Nyne and the bundled utilities use a TOML
configuration file during the build to generate static code used for all
formatting rules. This file is expected to be located at
$HOME/.config/nyne/nyne.toml
by default, but can be overriden by by exporting
the $NYNERULES
variable in your environment like
NYNERULES=/home/daniel/.nyne
. Copy the example to this
location and modify it for your needs beforebuilding nyne.
Think of nyne.toml
as roughly the equavalent of a config.h
file used to
configure many C programs. Because this file is used to generate static
configuration for Nyne that is baked into the binary, any changes made to this
file after build will not be noticed. In order for the changes to be picked up,
you must rebuild nyne and restart the nyne
executable if already running. This
has the added benefit that the bundled utilities can be executed without nyne
running and without having to re-read a config file while maintaining all of
your configuration options.
Scratch Area
In the example, you will see a section marked "tag" at the
top. This section contains configuration for the "menu" that looks like this:
# Array of strings that contain commands to be written to the acme
# scratch area
menu = [
"|fmt",
"|com",
"|a-",
"|a+",
"Ldef",
"Lrefs",
"Lcomp",
"win"
]
Along with the default "Put", "Undo", and "Redo" commands, these menu options
will be written to the acme scratch area when a new window is opened.
Looking at the format
block in the example configuration
file, you will see a block for each language that looks like the following. The
configuration options are documented below.
# "go" is an arbitrary name given to this configuration block. The
# name must be unique
[format.go]
# An array of strings that include file extensions that nyne should
# apply the given formatting rules to
extensions = [".go"]
# An integer representing the tab width used for indentation
indent = 8
# A boolean that determines whether to use hard tabs or spaces for
# indentation
tabexpand = false
# A string that contains the comment style for the given language.
# If the comment style has a defined start and end comment structure
# (/* */ in C), then set commentstyle to the complete comment structure
# like this: `commentstyle = "/* */"`. com will infer that this means /*
# should be placed at the beginning and */ should be placed at the end.
commentstyle = "// "
# The "commands" blocks is used to define the external program to
# be run against against your buffer on file save. Any number of these
# blocks may be defined.
[[format.go.commands]]
# A string representing the executable used to format the buffer
exec = "gofmt"
# An array of strings containing the arguments to the
# executable. $NAME is a macro that will be replaced with the absolute
# path to the file you are working on. This is a required argument.
args = [ "$NAME" ]
# A boolean representing whether the executable will print to
# stdout. If the command writes the file in place, be sure to set this
# to false.
printsToStdout = true
Install
The build for nyne assumes that you have followed the configuration instructions
above and have plan9port utilities
installed and available in your $PATH
. If you cannot execute mk
in
particular, head over to the main
plan9port page and follow the installation
guide for your system.
To install nyne, first clone this repository:
%: git clone https://git.sr.ht/~danieljamespost/nyne --branch 0.1.1 --single-branch
Then use mk to build the
nyne binaries:
%: mk
This will build nyne
, nynetab
, a+
, a-
, and com
and place them in
./bin
. Once they are built, you are ready to install them to a directory in
your $PATH
. On my system, I keep commands used for Acme in $home/bin
and
have that directory added to my path. Assuming your system is setup like mine,
you can install nyne and the bundled utilities with:
%: installdir=$home/bin mk install
If the commands above completed successfully, you should now be able to execute
any of the nyne utilities.
To cleanup the build files simply run mk nuke
. To uninstall nyne and all
utilities, run installdir=$home/bin mk uninstall
.
Usage
nyne
Once you have built and installed nyne, simply execute nyne
in acme by middle
clicking on the text "nyne" typed in the upper most window tag. Nyne will watch
for windows to be opened that match any of the extensions you have configured.
If it finds a match, it will write the menu options you've configured to the
scratch area and begin listening for file save events received when you middle
click Put
. When this event is received, it will format the buffer using your
configured external formatting programs. If the program does not print to
stdout, a new file will be written to /tmp
, formatted using youc configured
commands, and the output applied to your active buffer in acme.
If tabexpand
is enabled for a given file extension, nynetab
will be used to
convert tabs to spaces when you enter tab
with your keyboard.
nynetab
Nynetab is what is used under the hood for tab expansion in nyne. If you are
editing a buffer that has an extension not configured for nyne, simply execute
nynetab <tab size>
in an Acme buffer to begin tab expansion. Otherwise, simply
executing nynetab
will start tab expansion using your configured settings.
a+/a-
a+
and a-
use your indentation settings to indent or unindent your selection
in acme using either tabs or spaces depending on what is configured. To use
these commands, write |a+
or |a-
to the scratch area in your acme window,
select the text you want to indent, and then middle click on |a+
to indent or
|a-
to unindent your selection.
com
com
uses the commentstyle
you've configured a given file extension to
comment or uncomment a given selection in acme. Just as with a+
or a-
, you
can use com
by writing |com
to your scratch area, selecting the text you
want to un/comment, and then middle click on |com
to execute the command.
Bugs or Feature Requests
If you find a bug or if there is a feature you would like to see in Nyne, please
post it in the official
Issue Tracker.
Contributing
Please do! Nyne uses an email based workflow for managing patches. If you've
never used the git-send-email
command before, checkout this
interactive guide for how to set it up and get
comfortable with the workflow. Patches or questions about the submission process
can be sent to
~danieljamespost/[email protected].