A few months ago, I wrote a small Nushell script designed to take user-provided text and generate comments formatted for various programming languages.
After using it for a while, a few flaws naturally emerged:
- Limited availability: Being written as a Nushell command restricted its use to those who run this (otherwise great) shell.
- Performance: Although Nushell performs well overall, heavy text processing isn't its primary strength.
- General limitations: The script had a restricted set of styles, fixed layouts, and lacked support for custom borders or margins.
To overcome these limitations - and because I wanted to learn a new programming language - I decided to rewrite the project from scratch in Odin.
Porting the tool to Odin was a great learning experience, even if I only scratched the surface ๐ .
Although this new version is still in its early stages and has room for improvement, it is already quite stable and reliable for daily use.
The Program
Commentor (a portmanteau of Comment and Generator) is a lightweight command-line utility. It takes piped input from the user and generates a fully formatted comment block for a specified language, styled to your liking.
The syntax is simple:
echo <text> | commentor [flags]
For example, to generate an 80-character-wide block comment for a C-style language with centered, filled text, you can run:
echo "Hello World" | commentor -language=c -style=block -width=80 -margin-css=0,1 -text-align=center -text-filler=- -text-padding=1
Which produces:
/* ------------------------------ Hello World ------------------------------- */
You can also define custom padding, margins, and borders!
echo "Hello World" | commentor -language=c -style=inline-block -width=80 -margin-css=2,1 -padding-css=3,1 -text-align=center -text-filler=- -text-padding-css=1 -border:style=round
/* โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ */
/* โ ---------------------------------------------------------------------- โ */
/* โ ---------------------------------------------------------------------- โ */
/* โ ---------------------------------------------------------------------- โ */
/* โ ---------------------------- Hello World ----------------------------- โ */
/* โ ---------------------------------------------------------------------- โ */
/* โ ---------------------------------------------------------------------- โ */
/* โ ---------------------------------------------------------------------- โ */
/* โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ */
Notice the CSS-like shorthand? Flags like
-margin-css=2,1allow you to set vertical and horizontal spacing using the familiartop/bottom, left/rightshorthand syntax common in web design!
To see all available options and flags, run:
commentor -h
Usage:
commentor
Flags:
-border:<string>=<string> | sets a predefined border style or customize it.
-divider | generates a comment divider.
-language:<string> | identifier for the language style.
-list:<string> | prints a list. [Possible values: alignments, border-styles, languages, styles]
-margin:<string>=<uint> | comment margin.
-margin-css:<string> | comment margins as CSS-like shorthand.
-newline | should put the comment tokens on separate line?
-no-indent | do not indent block comments.
-padding:<string>=<uint> | comment padding.
-padding-css:<string> | comment paddings as CSS-like shorthand.
-style:<string> | style to be used for the comment. [Default 'inline']
-text-align:<string> | alignment for the text inside the comment. [Default 'left']
-text-filler:<rune> | character to use as filler text margins. [Default ' ']
-text-padding:<string>=<uint> | text padding.
-text-padding-css:<string> | text paddings as CSS-like shorthand.
-version | prints the version of this program.
-width:<uint> | maximum width for the comment. [Default 80]
By default, the utility tries to auto-detect the comment width, falling back to 80 characters if it cannot.
Styles and languages are fully customizable via a JSON configuration file generated automatically on its first run.
IDE Support
Due to its classic command-line nature, it is incredibly easy to integrate Commentor into your daily workflow.
Since I do most of my development in the Zed editor, I have included an integration example below. However, any editor or IDE with a task system should run it with minimal effort.
1. Define Tasks in Zed
Open the command palette and select zed: open tasks. Add the following task (this example uses Nushell; adapt the shell configuration as needed):
{
"label": "Commentor - Header - Single Line",
"command": "r#'$ZED_SELECTED_TEXT'# | commentor -language=\"$ZED_LANGUAGE\" -width=79 -border:style=text | wl-copy",
"use_new_terminal": true,
"reveal": "no_focus",
"hide": "on_success",
"shell": {
"with_arguments": {
"program": "nu",
"args": [
"--no-std-lib",
"--env-config",
"~/.config/nushell/env.nu",
"-c"
]
}
}
}
2. Configure Keybindings in Zed
Open the command palette and select zed: open keymap file. Add keybindings to trigger your tasks:
{
"context": "Editor && mode == full",
"bindings": {
"ctrl-1": [
"task::Spawn",
{ "task_name": "Commentor - Header - Single Line" }
]
// ...
}
}
How to Build
The project is currently only distributed in source-code form provides executables for GNU/Linux and Windows (and as usual, they work on my machine but need to be tested on yours ๐
). You can find the repository on Codeberg.
To build and install Commentor on your system, clone the repository and use the built-in task runner norn (written in Odin ๐):
git clone https://codeberg.org/Ragnarokkr/commentor.git
cd commentor
odin run norn -- build debug # for testing
odin run norn -- build release # for production
odin run norn -- install <dest_path> # to install the optimized executable to a custom path
Make sure you have the Odin compiler installed and available in your system's
PATH.
That's All Folks!! ๐
