Commentor: evolution of my Comment Divider

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,1 allow you to set vertical and horizontal spacing using the familiar top/bottom, left/right shorthand 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. 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!! 🎉