Xiong has asked for the wisdom of the Perl Monks concerning the following question:

You explore a new command line tool. You have not bothered to read any of its documentation. For that matter, you don't know what the tool might do. An interactive mode is available, a fact of which you may or may not be aware. You decide to type the command with no arguments.

What should the tool do?
What do you expect?
What would annoy you?
What would you prefer?

Updates:

2010-04-24: I see that some desires are mutually exclusive.

2010-26-06: BrowserUk has an excellent point; slavish conformance to the past is a straightjacket. Several replies note the hazard of typing random commands without first reading the man page, or at least taking the smaller risk of <somecommand -h>. However, I have not chosen to march an animated ASCII Jack-in-the-Box, thumbing its nose, across the terminal window. I have a short usage message now, but I'm keeping the brownie points in mind.

- the lyf so short, the craft so long to lerne -

Replies are listed 'Best First'.
Re: CLI Default Action
by moritz (Cardinal) on Apr 23, 2010 at 21:41 UTC
    What should the tool do?

    Depends entirely on the tool. Common behavior is to read from STDIN, to perform a default action or to show a help message. Either is fine.

    What do you expect?

    If it doesn't seem to to do anything, I expect it to terminate when I send EOF (Ctrl+D)

    What would annoy you?

    If it erased my data

    What would you prefer?

    That it not erased my data.

    Update: There are tools like screen that confuse the hell out of you if you have no idea what it does, and you start it. Tools like that should show some kind of informational message unless started with an option or arguments (and unless a config file is present). Apart from that it's silly (and possibly dangerous) to start a program of which you have no clue. As a former part-time sys admin I stopped doing that :-)

    Perl 6 - links to (nearly) everything that is Perl 6.
Re: CLI Default Action (Updated)
by BrowserUk (Patriarch) on Apr 23, 2010 at 21:45 UTC
    • What should the tool do?

      Something benign, but useful :)

    • What do you expect?

      To be told, in brief, what it expects.

    • What would annoy you?

      Being told: "You didn't give the appropriate arguments; type 'xyz --help' to get help".

    • What would you prefer?
      Usage: 'xyz [-a] [-b] [-c pqr] -u user file [file ...] Type ? [opt] for extended help; return to exit; or enter your command +line now xyz>

      Even better if at that prompt I could use uparrow to retrieve the last N command lines I've used with this program.

      For ultimate brownie points, allow me to enter a partial command line followed by ? and it displays the help for the preceding argument element, and returns to the prompt with the input buffer pre-filled with the command as was when I hit return. minus the ?.

      Eg.

      Usage: 'xyz [-a] [-b] [-c pqr] -u user file [file ...] Type ? [opt] for extended help; return to exit; or enter your command +line now xyz>-a? Option -a: output all information xyz>-a -c? Option -c pqr: set the c... to the (required) value 'pqr' xyz>-a -c pqr -u? Option -u user: (required) specify the user id for ... xyz>-a -c pqr -u fred ? You must specify one (or more) filenames (wildcards allowed) to be pro +cessed. xyz>-a -c pqr -u fred this*.txt that*.txt theOther.txt (processing)...

      Ie. I get just the help I need, when I need it, without having to start over, start a new session, or wade through screenfuls of stuff trying to find it.


    Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
    "Science is about questioning the status quo. Questioning authority".
    In the absence of evidence, opinion is indistinguishable from prejudice.
Re: CLI Default Action
by rowdog (Curate) on Apr 23, 2010 at 22:34 UTC
    You explore a new command line tool. You have not bothered to read any of its documentation. For that matter, you don't know what the tool might do. An interactive mode is available, a fact of which you may or may not be aware. You decide to type the command with no arguments.

    I wouldn't. I might try prog --help and prog -h if I had some clue what the program was, otherwise I'd reach for man prog and/or Google.

    What should the tool do?

    The default action or whatever the author wants.

    What do you expect?

    Anything. I have no expectations of what the default would be.

    What would annoy you?

    I wouldn't be annoyed, except with myself if I didn't bother to RTFM before blindly executing a command.

    What would you prefer?

    Something sensible, like a default action, if appropriate.

Re: CLI Default Action
by toolic (Bishop) on Apr 23, 2010 at 23:27 UTC
    What should the tool do? What do you expect? What would you prefer?
    Behave the way its documentation describes.
    What would annoy you?
    • The absence of a standard way to get help from the commandline, for example: man command or command -h
    • The lack of sufficient help documentation from the command line. Just getting command -h -foo bar is usually not very helpful.
    • Promtping for input by default.
Re: CLI Default Action
by liverpole (Monsignor) on Apr 24, 2010 at 18:15 UTC
    Hi Xiong,

        "What should the tool do?"

    Whenever I write a command-line tool, (and unless it's a one-off, throwaway), I always make the tool print a syntax message if no arguments are specified.  For example:

    use strict; use warnings; use File::Basename; use Getopt::Long; my $iam = basename $0; my $syntax = qq{ syntax: $iam [switches] <directory> Welcome to '$iam' -- the fabulous tool for doing [insert function description here]. Switches: -v ... display verbose output }; # Process switches with Getopt::Long here my $dir = shift or die $syntax;

    It's as much for my benefit (when I forget in 6 months what I wrote the utility for) as for others' benefit.  I find it frustrating when someone writes a program that you have to "just know" to type "prog -\?" (or whatever) to get help.

    Even if the program doesn't need any arguments at all, you can almost always think of some way of extending it (now, or in the future), which will make it sensible to allow at least one argument.  For example, if you're almost always operating on the current directory, it only takes 1 character to type '.' for the current directory, allows you to be flexible if a different directory is needed, and therefore makes it possible to print a syntax message when no arg is given.

    Come to think of it, that addresses your other 3 questions, too.


    s''(q.S:$/9=(T1';s;(..)(..);$..=substr+crypt($1,$2),2,3;eg;print$..$/
Re: CLI Default Action
by ww (Archbishop) on Apr 23, 2010 at 22:21 UTC
    I.
    1. cd / (or cd \)
    2. rm -rf (or <c>rd /s/q)

    II.

    1. That the nice folks with the white, formal jacket with buttons up the back will arrive soon (with my meds || to take me away)
    2. That the programmer considers him/her/it-self a real epic d00d among v4nd4ls

    III. That your scenario probably happens rather frequently.

    IV. That the tool were written to pop up a usage message, possibly beginning with the words

    "Hey, stupid! RTFM!"
Re: CLI Default Action
by ikegami (Patriarch) on Apr 24, 2010 at 21:14 UTC
    Assuming it can take input from STDIN when used as a command line tool, you could determine whether to enter interactive mode or not based on -t STDIN.
Re: CLI Default Action
by BrowserUk (Patriarch) on Apr 25, 2010 at 12:38 UTC
    2010-04-24: I see that some desires are mutually exclusive.

    As a program author, you have a choice.

    • Stick with the mistakes of the past--because that's how it's always been done.
    • Or do something different that is hopefully better.

    Programs are tools for the users, to improve their productivity; not tools for lazy programmers, to enforce their blinkered view of RTFM.


    Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
    "Science is about questioning the status quo. Questioning authority".
    In the absence of evidence, opinion is indistinguishable from prejudice.