Interesting claim, right? Have you ever wanted to spread the word about your little script that does amazing things back to the community? Have you ever thought that your script is too hacky to go out there or even the output or way to use it looks bad? Too much hardcoded parameters?
This could be the answer for your problems and unlike the other methods, this takes very little time. You will walk away being able to write your own command, with options such as --this=20 or -t=20 and a beautiful manual page!
Of course, I don't expect a beginner to write the whole thing from the beginning to the end in 5 minutes. But once you get fluent with this method, you will get your problem solved in a very nice way in little time.
Ok, if you got this far, you deserve to know that we will be necessarily using the language Perl. I know that in 2015 not a lot of people like it but if you give it a chance, it could be a very good friend. Most of your problems are already solved in the CPAN. Including the subject of this Instructable, we will be using a very nice library :
Take your time, read the manual, it's your friend. Interesting, right? Let's proceed...
Step 1: Installing App::Rad
My first observation is that this tutorial will pass entirely in the environment of a vanilla CentOS 6.6; which in May of 2015 is the production OS that is common sense among a good share of seasoned sysadmins.
Let's install and setup CPAN :
[root@localhost ~]# yum install perl-CPAN
[root@localhost ~]# cpan
Would you like me to configure as much as possible automatically? [yes]
It will drop you straight on a nice CPAN shell. As I don't want you guys to end up like Homer Simpson's bird :
Please run this :
cpan> o conf build_requires_install_policy follow
cpan> o conf commit
commit: wrote '/usr/share/perl5/CPAN/Config.pm'
Ok, now we're ready to install App::Rad :
cpan> install App::Rad
If it still asks about dependencies, make it happy and answer yes (default).
When it finishes you should have the library in your system.
Step 2: Start Writing the Skeleton of Your Program
This step is pretty much figuring out which options you can use and put them on the table, as well as having the basic structure that will contain your program without sub-commands (as the manual mostly suggests).
We will get to the point where you leave your command in /usr/bin (then it'll go to $PATH), but for now :
[root@localhost ~]# vim command.pl
This didn't really add any value compared to a raw Perl script. But, the difference starts when you type :
[root@localhost ~]# ./my-command.pl help
Usage: ./my-command.pl command [arguments]
help show syntax and available commands
What I personally like more in this module is that it solves ALL problems of option parsing and configuration files for you. Here I will cover more option parsing. Let's say that I want to have the options "--time" and "--distance", so I can calculate my average speed from Los Angeles to San Francisco. The code would look like this :
Cool, now our little command is already functional, with decent code and reasonable output :
[root@localhost ~]# ./my-command.pl --distance=350 --time=5.5
Your average speed is 63.6363636363636 mph
Now we will start working on the more interesting and unusual stuff -- Command Line Interface prettifying and Manual.
Step 3: The Help Function
You have seen the code but not the output, so you might have missed that we're already treating the cases where needed parameters are missing :
[root@localhost ~]# ./my-command.pl --distance=350
I need to know the time at ./my-command.pl line 11.
[root@localhost ~]# ./my-command.pl --time=5.5
I need to know the distance at ./my-command.pl line 10.
Now we just need to make the Help looks better :
There would have been better ways if we were using the sub-commands as the library wants we to. But we only have a single use case so we're doing like that. Now it looks much better :
[root@localhost ~]# ./my-command.pl help
Usage: road-calculator --time=[Hours] --distance=[Miles]
This is a road trip calculator, so you can know how fast you went if you were going non-stop
So as you see in the usage, I already baptized it. Time to move it to the right place and see it working as it should :
[root@localhost ~]# mv my-command.pl /usr/bin/road-calculator
[root@localhost ~]# road-calculator --time=6 --distance=350
Your average speed is 58.3333333333333 mph
Awesome! Our command is already in $PATH. We can just type its name to run. Now, to make it completely official, let's add a manual page.
Step 4: Adding the POD (Manual Page)
Perl has a pretty interesting markup language that together with PerlDoc, make your documentation look exactly like any other Linux command's manual. So let's type something really brief with it :
The nicest thing is that you can actually attach your documentation at the end of the script and Perl will interpret it as well. Of course it won't when you execute it. So now when you type :
[root@localhost ~]# perldoc road-calculator
The outcome was so beautiful that I had to take a screenshot. It's the cover picture of this step.
And that should be it!
Our program is written, in the right place, and has a manual page. Now you could take a step further and package it as RPM/DEB and contribute to a major distribution, so people will be a package manager command away from your tool!
If you're excited about that take the chance to check OpenSuse's Build service : https://build.opensuse.org/
I hope you liked it and I'm sorry if I'm too technical or specific, this tutorial is aimed to serve Linux power users that know how to program and want to take the next step on contributing back to the community instead of leaving their nice tools in their garages.
One day I will write one for total beginners. If you have suggestions please send me a message. Thanks!