Add bash comments formatter

[ctmbl]

Really this isn't a need to this repo, but I wrote this python script for bump.sh and found it quite cool so we can use it if you'd like 👍

PS: sorry for the one commit PR 🥲

EDIT:
Actually I though the title was explicit enough but it isn't so here is what the script does.
It's a simple python script with a shebang to execute it directly.
It needs a file path as only argument and will check that it exists and isn't a directory or symlink.
This file should be a bash (or whatever other script that use # comments) and my script will look for # - beginning lines (I use such comments to separate bash script sections) to format them:

• 80 character lines (configurable)
• center the section text
• ask the user to confirm for each formatting

[amtoine]

a one-commit PR is fine 😉

@ctmbl, could you please give a quick use case of that script to understand what it does? 😋

[ctmbl]

@amtoine That's right sorry I didn't explain the purpose! see my first message edit

[amtoine]

@amtoine That's right sorry I didn't explain the purpose! see my first message edit

thanks a lot @ctmbl 😮

this script is quite cool then 🤩
i was able to transform

#!/usr/bin/env bash
# - my first section
echo "first section"


# - my second section
echo "second section"


# - a very long section title that will span the whole line
echo "very long section"

# - my last section
echo "last section"

into

#!/usr/bin/env bash
# ------------------------------ my first section ------------------------------
echo "first section"


# ----------------------------- my second section ------------------------------
echo "second section"


# ---------- a very long section title that will span the whole line -----------
echo "very long section"

# ------------------------------ my last section -------------------------------
echo "last section"

with a simple

> ./scripts/bash-comments-lint.py foo.sh

really neat 👌

comments

• as said in the threads, i think a little bit of argparse or equivalent would be nice.
  i like using argparse in all my python scripts, even if it's only for --help 😉
• also in the threads, adding options to bypass the confirmations and change the line length would be appreciated
• maybe your script is a little bit hard to read, not a lot of comments and a lot of regex / string manipulations going on

but in the end, the script does the job very nicely so, if you feel these are out of scope, i can open an issue for the points above and move the requested changes to another PR 😋

[ctmbl]

@amtoine I just implemented what you suggested and it looks pretty good!
Don't hesitate to point out anything that can be improve according to you 😋

[amtoine]

that's kinda cool 👌

i think a --auto flag would be cooool to compute the perfect witdth of a section title automatically based on the length of the comments 🤩
for instance, the following nushell command on the script i talk about in my first review gives 55, the length of the longest comment 💪

open foo.sh
| lines
| find --regex "^# -"
| str replace "^# -* " ""
| str replace " -*$" ""
| each {split chars | length}
| math max

that's just an idead of course 😉

[ctmbl]

i think a --auto flag would be cooool to compute the perfect witdth of a section title automatically based on the length of the comments star_struck

I see but how to compute this perfect length? 🤔
knowing that the longest comment is 55 doesn't say how long the section should be 😕
Also this length is more about convention (I was thinking of python PEP8 when I chose 80) than anything else, if a comment is too long maybe its the comment fault not the length? but maybe I'm missing something?

[amtoine]

I see but how to compute this perfect length? thinking knowing that the longest comment is 55 doesn't say how long the section should be confused Also this length is more about convention (I was thinking of python PEP8 when I chose 80) than anything else, if a comment is too long maybe its the comment fault not the length? but maybe I'm missing something?

i do not know exactly, this was just an idea, quite out of the scope of this PR 😉
the script is fine for now, maybe i'll open an issue some day if i have a clearer idea 😋

[gbrivady]

Not exactly a bash expert, but the Python stuff looks fine to me

[ctmbl]

the script is fine for now, maybe i'll open an issue some day if i have a clearer idea yum

That seems right to me!

[amtoine]

@atxr or @vSt11,
we would need a review from one of you two to merge this 😉

[atxr]

This script is a nice idea!
I'll probably use it for other projects :)
🚀

[ctmbl]

tks ! 🚀

[Laudut]

Whow ! Nice Job !

Maybe 2 points :

• You delete most of special characters in formatting ( &"'(-)=°+? ). So "# - essential ??? " become "# --- essential ----".
• In line 42 you use again a "new_line.replace( ... )" and recalculates something you had already calculated in line 30

[ctmbl]

@Laudut

Thanks for the review! actually both of your remarks are really relevant, let me answer them:

You delete most of special characters in formatting ( &"'(-)=°+? ). So "# - essential ??? " become "# --- essential ----".

That's true, but given that this script is supposed to format Sections comments I guess you don't use these characters in sections?

In line 42 you use again a "new_line.replace( ... )" and recalculates something you had already calculated in line 30

ooops 🙃 surely I was too lazy to do things properly!
I'll modify it given that I noted yesterday that the script also formats lines that are... already formatted, so I'll do a quick patch for both of these issues!

Once again thanks for this great review!

[ctmbl]

@Laudut here is the patch! 😉

[Elymme]

Looks good to me. More comments to explain everything would suit me better but that's fine.
Adding the expected type and/or format of the arguments before a function would be nice though

[ctmbl]

@Elymme tks for the review!

What do you mean by " Adding the expected type and/or format of the arguments before a function would be nice though" do you mean like

def f(a: int, s: str, o: SomeObject):
  pass

?

[Elymme]

@ctmbl Yeah exactly that. I think it improves clarity.

[ctmbl]

@Elymme actually you're right, and my choice of variable name is really poor too.
However because the script is really short and that it has really only one function I'll leave it that way, if we were to improve it something sure it will be one of the main goal!