some feature ideas

[gurgeous]

Hey, command_kit is neat! Thanks for creating. I've been kicking the tires a bit this afternoon...

I've built some similar stuff myself, mostly for internal use, and I'd love to move over to command_kit. Looking for help? There are a few features that I'd be happy to work on if you are interested:

1. csv - reading and writing CSVs. A csv_read method that returns an array of Structs and a csv_write method that outputs an array of hash-like objects (Struct, OpenStruct, hash). This isn't intended to support all csv use cases, but helps tremendously when dealing with common CSVs.
2. banner/fatal - banner prints a timestamped line of text with a green background (see screenshot below). fatal is like banner but uses a red background and calls exit(1). I also have one called warning that uses a yellow background. Skip the color if $stdout isn't a tty.
3. exec - An exec method for running commands and raising exceptions in a unified way. Basically system(..., exception: true). It's also nice to have an exec_capture variant that returns captured output. My old implementation uses backticks and does the shell escaping manually. Might be easier to use popen.

Also happy to help with the README, setting up linting/formatting/rubocop (if you want), etc.

What do you think?

banner('hello world')

[postmodern]

1. What would be the benefit over calling CSV.read / CSV.open?
   1.1. Would this tie into a larger multi-format output method that would respect --csv, --json, --yaml methods to output some arbitrary data? I've implemented something similar in the past for CLI commands that queried ORM models.
2. OK this sounds like more advanced print "logging". I wanted to add something similar to the ANSI colored >>> Info, *** Debug, !!! Error messages from ruby-install, but there's lots of questions about formatting and what to call the module.
   2.1. I've also wondered whether to add an actual Logging module to handle more verbose logging, to either stdout or a defined log file (think like ffmpeg's log messages).
3. Hmm, I've struggled with when methods should return true, false, nil for easy error handling and when an exception should be raised. It's fairly easy to explicitly check the return value in an if/else to handle when things fail. The risk with exceptions is if they are not rescued, they can crash the whole program. I kind of want to avoid using exceptions for non-truly-exception cases.

I would love help with setting up rubocop, although it seems to dislike some of my coding styles (vertically aligned = assignments, single quote vs double quote, etc) and would require extensive configuration. I like the idea of linting, but it just seems like too much work, and I can achieve similar results by manually reviewing PRs.

I tried to pack as much into the README as possible. The API links allow new users to see all of the functionality and see brief examples in the documentation. Then there are copy/pasteable examples to show off syntax; in addition to runnable examples in the examples/ directory. Then there's the age old debate about README badges; are they useful or tacky, how many is too many, etc?

[gurgeous]

1. CSV.read(..., headers: true) isn't bad, but an Array of Structs is much easier to work with. Plus 10x better performance when accessing values. Example: ids = csv_read(...).map(&:name).uniq. Also, there's no CSV.write.
   1.1 I've mostly dealt with CSV/tabular data in my scripts, but I have no objection if we want to create JSON and YAML helpers too.
2. Yes, this looks pretty similar to the stuff in ruby-install. Personally I like to add a HH:MM:SS timestamp to keep an eye on long running operations. Background colors are nice too, so that banners really stand out. Quite often I'm reviewing loads of output. Maybe banner is a little different from log/warn/error. No reason not to add 'em all, though. They are easy! I think people who need more can fall back to Logger. We could just drop them into Printing. Or add Logging? Also, should we stick with the print_xxx prefix to avoid collisions? banner seems less likely to collide than log/warn/error.
3. I hear what you're saying. I've written a ton of standalone ruby scripts. Probably like 500 over the last few years? Sometimes the scripts are robust and used by the rest of the team. Often they are just for me, and get thrown away after a week. I almost always want them to fail fast, though. If I do exec('apt-get install xyz') I want to crash on failure! Same reason why I use set -eux in bash. More advanced users are welcome to catch the exception. Maybe that's a personal preference, though.

Re: rubocop. Happy to take a stab at it if you think it would be worthwhile. I'm totally agnostic on config, I just like to avoid manual formatting. My personal style is pretty different from the rubocop defaults. Usually I end up turning off half the rules anyway... Occasionally it finds real issues, which is nice. Most of my projects have a rake rubocop to keep things simple.

Re: README. I think the current README is pretty good. I can think of a few improvements we might make:

1. Short explanation for each module. Show off your stuff!
2. Richer example, showing more of the API (and turn on ruby highlighting)
3. Changelog (even just showing the release date of the first version increases confidence for users)
4. A badge or two wouldn't hurt. I guess in modern times these help the project to look more active. Even just the github actions badge would be nice.

I don't want to overwhelm you in here. 😄 Give me a quick yea or nay on these guys and I'll create issues. We can tackle them one at a time and I'll give you PRs to check out. Oh, and I should warn you that I've never used rspec. I'm an experienced Ruby dev but I've always used minitest. I'll do my best, tho 😄

[postmodern]

1. Potentially I could see something where a csv_read method auto-defines an anonymous Struct based on some given field names, but then I could see people wanting to supply their own Struct class.
2. We could define stock print_info, print_warn, print_error (print_error is technically already defined in CommandKit::Printing) methods to simulate the different log levels. Not sure if CommandKit should provide it's own default formatting, and whether it should support ANSI by default, or let the user define their own? (I'm a fan of >>> ... style messages, while security tools love to use [+] ... messages which I think looks dumb, imo). Also, we may want to add background color support to CommandKit::Colors (open to further discussion in Issues).
   2.1. I still kind of want to add a module that wraps around Logger, mainly because I really dislike Ruby's default Logger format of I, [2021-07-18T22:02:26.218815 #30582] INFO -- : .... Logger does provide a way to override the format string though.
3. If we do provide methods that raise an exception, should we also provide companion methods that do not? (exec! vs. exec?) If we do raise an exception, there should be an CommandKit::Error base class that users can rescue, so that any CommandKit exceptions can be handled, but any other exceptions coming from other Ruby code can be handled by on_exception and print_exception. Without raising exceptions, you'd have to explicitly check the return value and call abort. The benefit of explicitly checking the return values is you have greater control over how to handle success or failure, and customizing the error messages.

unless exec('apt-get install xyz')
  abort "Failed to install xyz"
end

vs.

begin
  install_pkgs('xyz')
rescue ExecError => error
  abort error.message
end

Originally, I started copy/pasting every example into the README, however it started getting super long. Maybe we could copy/paste the top-level summaries and example from each module's documentation into the README, and add a Table of Contents with #anchor links to the sections? Would probably improve SEO and reduce the number of questions from people who didn't click one of the API links.

All good suggestions. I'd say robucop, adding background colors to CommandKit::Colors, and README formatting are obvious yes-es. I'll have to think more about CSV, additional print methods / default formatting, and raising exceptions.

[gurgeous]

Excellent - I'll start in on these with issues one at a time. We can continue the discussion in there. We could also create separate gems for stuff that feels optional (csv, exec, etc). I think your module design would facilitate that approach.

Thanks @postmodern!

[postmodern]

I created issue #35 for background color support.

[noraj]

command_kit looks neat and qualitative but seems to miss some common features for me to replace docopt:

• 💡 positional arguments
• 💡 required elements (not just values)
• 💡 mutually-exclusive elements
• 💡 repeated elements
• 💡 sub-commands dedicated help message (git branch --help vs git --help)

Also even something not strictly argument parsing but highly related, do you plan to support automatic shell completion generation? Like docopt-compgen for docopt or dry-cli-completion for dry-cli but natively supported.

[postmodern]

• positional arguments and repeated elements are already supported.
• sub-command's already have their own help messages, so foo bar --help will display the help information for the bar sub-command and foo --help will list all available sub-commands and global options.

Mutually exclusive options/arguments or option/argument groups (ex: [ARG1 {ARG2 ARG3}]) are not yet supported, so you would have to explicit define that logic to check the arguments and options.