[CommonJS] System args and command

[Kris Kowal]

It strikes me that command line argument parsing might be able to take
a nod from JSGI for "command routing".

One major use case for command line tools is being able to print
"Usage: $0", the name of the command up to the point you've "routed"
to. For example, "view" can be a symbolic link to "vi", and the
command as typed shows up as arg 0, "view", so you can multiplex the
usage information based on the typed command. "git subcommand --help"
Would need to provide "git subcommand" and "git --help" needs to
provide "git".

JSGI provides the scriptName and pathInfo which are useful for routing
because the scriptName can serve as the portion of the path that has
been routed, and the pathInfo can stand for the portion of the path
that remains.

I propose that the next system module specification divide system.args
into a system.command array and a system.args array. The present
specification calls for these arguments to be combined into a single
args array, as provided to main() by the C runtime, but this is
largely inadequate since our "main" functions often undergo some
"routing".

Kris Kowal

--
You received this message because you are subscribed to the Google Groups "CommonJS" group.
To post to this group, send email to comm...@googlegroups.com.
To unsubscribe from this group, send email to commonjs+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/commonjs?hl=en.

[Christoph Dorn]

+1

I have been thinking of commands with arguments in terms of REST URIs
with parameters for a while. They map well.

I would like to see a reflective + interactive REST interface
implemented as JSGI middleware for commands (narwhal's args parser) at
some point. It could form the basis of a live command documentation and
test runner tool.

Christoph

[Donny Viszneki]

On Fri, May 7, 2010 at 2:33 PM, Kris Kowal <kris....@cixar.com> wrote:
> JSGI provides the scriptName and pathInfo which are useful for routing
> because the scriptName can serve as the portion of the path that has
> been routed, and the pathInfo can stand for the portion of the path
> that remains.
>
> I propose that the next system module specification divide system.args
> into a system.command array and a system.args array. The present
> specification calls for these arguments to be combined into a single
> args array, as provided to main() by the C runtime, but this is
> largely inadequate since our "main" functions often undergo some
> "routing".

Personally I think it is a poor choice to work with system.args at all
if you are doing web work. If you're writing to the JSGI
specification, then what is preventing the programmer from making sure
system.args looks however they want it to? The state of web
development is hardly concerned with command-line arguments at this
point.

The days of CGI being the latest thing were largely about reflecting
the filesystem and remote command execution over HTTP. To this end
things like argv have been reflected perfectly, and if what you want
is NOT proper reflection of C programming, then you should really just
man up and take on a higher level programming abstraction altogether.

Worth noting: the zeroth element of the "argv" vector can really only
be interpreted as the program name by convention: the POSIX APIs that
execute a new process, initialize everything and then enter main() do
not place any stipulations on what the zeroth argument can be. For
this reason as well, it should not be hard for JSGI programmers to
manipulate the zeroth argument to their liking without having to
divide argv into more symbolic names.

The whole pathInfo thing as a user-interface abstraction (if a URI is
a user interface) can sort of be compared to a user-land filesystem,
and this plays well with reflection/remote-command-execution style of
resource resolution when trying to design a ReSTful interface, but if
your emphasis is on ReST, why encumber yourself by tying yourself to a
real filesystem to begin with? Just look at stuff like Rails or
Django, they threw that baby out with the bathwater, and it pays off.
They're both well encapsulated and you don't have to worry about the
state of the filesystem really playing a very important role
(excepting initialization time when all your scripts are loaded into
mod_python or something) in how your web app behaves.

That's my 2 cents anyhow :)

Here's an example of what URL resolution looks like in Django:

urlpatterns = patterns('',
(r'^articles/2003/$', 'news.views.special_case_2003'),
(r'^articles/(\d{4})/$', 'news.views.year_archive'),
(r'^articles/(\d{4})/(\d{2})/$', 'news.views.month_archive'),
(r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'news.views.article_detail'),
)

Each regular expression is tested against the resource (the part of
the URL following the hostname) being requested and the view function
that is used, for convenience, can be specified as a string or as a
reference to the function itself.

It's important that JSGI offer a strong foundation for those who need
to work with a CGI environment, but I think trying to move JSGI up and
away from its roots is just ignoring the fact that there are so much
better abstractions to look forward to if you just stop building your
apps to anything CGI-like and build on top of a higher level
framework.

On Sat, May 8, 2010 at 3:39 AM, Christoph Dorn
<christ...@christophdorn.com> wrote:
> I have been thinking of commands with arguments in terms of REST URIs with
> parameters for a while. They map well.
>
> I would like to see a reflective + interactive REST interface implemented as
> JSGI middleware for commands (narwhal's args parser) at some point. It could
> form the basis of a live command documentation and test runner tool.

Could you elaborate on this a bit?

--
http://codebad.com/

[Kris Kowal]

On Tue, May 11, 2010 at 11:59 AM, Donny Viszneki
<donny.v...@gmail.com> wrote:
> Personally I think it is a poor choice to work with system.args at all
> if you are doing web work. If you're writing to the JSGI
> specification, then what is preventing the programmer from making sure
> system.args looks however they want it to? The state of web
> development is hardly concerned with command-line arguments at this
> point.

To be clear, I am not proposing that there be any working relationship
between HTTP routing and Command routing, apart from analogy. When
processing sub-commands, POSIX gives you an argv[0] and guarantees
only that argument is the name the user used in reference to the
program or script. However, it is possible to route commands within a
single program, such as "command subcommand". In those cases, the
"Usage:" should show "Usage: command subcommand [OPTIONS] …" and the
subcommand should handle only the arguments thereafter. My proposal
is that, because these are both routing problems, they probably have
similar solutions, particularly that command and args could be
separated in the same way that scriptName and pathInfo are separated.

Kris Kowal

[Donny Viszneki]

On Tue, May 11, 2010 at 3:30 PM, Kris Kowal <kris....@cixar.com> wrote:
> On Tue, May 11, 2010 at 11:59 AM, Donny Viszneki
> <donny.v...@gmail.com> wrote:
>> Personally I think it is a poor choice to work with system.args at all
>> if you are doing web work. If you're writing to the JSGI
>> specification, then what is preventing the programmer from making sure
>> system.args looks however they want it to? The state of web
>> development is hardly concerned with command-line arguments at this
>> point.
>
> To be clear, I am not proposing that there be any working relationship
> between HTTP routing and Command routing, apart from analogy.  When
> processing sub-commands, POSIX gives you an argv[0] and guarantees
> only that argument is the name the user used in reference to the
> program or script.

Where is this guarantee stated? I'm fairly certain it's only a
convention. I guess /bin/sh is guaranteed to behave a certain way. I
was arguing that this is a moot point anyway, since you don't need a
guarantee, you only need the assumption that argv[0] will make sense
to the user, and if it doesn't it's the user's problem. There are
plenty of other ways argv[0] can look different from what the user
expects.

>  However, it is possible to route commands within a
> single program, such as "command subcommand".  In those cases, the
> "Usage:" should show "Usage: command subcommand [OPTIONS] …" and the
> subcommand should handle only the arguments thereafter.  My proposal
> is that, because these are both routing problems, they probably have
> similar solutions, particularly that command and args could be
> separated in the same way that scriptName and pathInfo are separated.

Personally I think it's a mistake to fragment the user interface
across multiple programs meant to work together.

Consider the case of passing options to the linker when executing gcc.
gcc never gives you an error report like this:

usage: gcc: ld: how to use ld via gcc command

You get this:

donny@donny-desktop:~/src/hg/gpsee$ gcc -Wl,wtf foo.c -o foo
/usr/bin/ld: wtf: No such file: No such file or directory
collect2: ld returned 1 exit status

I don't feel a compelling case exists to promote the fragmentation of
the user interface across multiple programs.

--
http://codebad.com/

[Kris Kowal]

On Tue, May 11, 2010 at 1:26 PM, Donny Viszneki
<donny.v...@gmail.com> wrote:
> Personally I think it's a mistake to fragment the user interface
> across multiple programs meant to work together.

I do not understand what you mean by "fragment". I'm proposing that
we make a standard. Do you mean that, if this were a standard, there
would necessarily be non-conformant variations?

> Consider the case of passing options to the linker when executing gcc.
> gcc never gives you an error report like this:
>
> usage: gcc: ld: how to use ld via gcc command

I think this is a red herring. This is not a necessary conclusion of
separating [argv[0]] from argv[1..]. It's also not closely related to
my example since it involves options and not positional arguments.

Kris Kowal

[Donny Viszneki]

On Tue, May 11, 2010 at 5:02 PM, Kris Kowal <kris....@cixar.com> wrote:
> On Tue, May 11, 2010 at 1:26 PM, Donny Viszneki
> <donny.v...@gmail.com> wrote:
>> Personally I think it's a mistake to fragment the user interface
>> across multiple programs meant to work together.
>
> I do not understand what you mean by "fragment".  I'm proposing that
> we make a standard.  Do you mean that, if this were a standard, there
> would necessarily be non-conformant variations?

I thought I was referring to this, but it's not entirely unlikely that
I just don't understand what you're describing here:

On Fri, May 7, 2010 at 2:33 PM, Kris Kowal <kris....@cixar.com> wrote:
> It strikes me that command line argument parsing might be able to take
> a nod from JSGI for "command routing".
>
> One major use case for command line tools is being able to print
> "Usage: $0", the name of the command up to the point you've "routed"
> to. For example, "view" can be a symbolic link to "vi", and the
> command as typed shows up as arg 0, "view", so you can multiplex the
> usage information based on the typed command. "git subcommand --help"
> Would need to provide "git subcommand" and "git --help" needs to
> provide "git".

>> Consider the case of passing options to the linker when executing gcc.
>> gcc never gives you an error report like this:
>>
>> usage: gcc: ld: how to use ld via gcc command
>
> I think this is a red herring. This is not a necessary conclusion of
> separating [argv[0]] from argv[1..].  It's also not closely related to
> my example since it involves options and not positional arguments.

I think maybe I'll understand better if you can explain "command
routing" a little more for me :)

--
http://codebad.com/

[Christoph Dorn]

Donny Viszneki wrote:
> On Sat, May 8, 2010 at 3:39 AM, Christoph Dorn
> <christ...@christophdorn.com> wrote:
>> I have been thinking of commands with arguments in terms of REST URIs with
>> parameters for a while. They map well.
>>
>> I would like to see a reflective + interactive REST interface implemented as
>> JSGI middleware for commands (narwhal's args parser) at some point. It could
>> form the basis of a live command documentation and test runner tool.
>
> Could you elaborate on this a bit?

Narwhal's args parser I am referring to:

http://github.com/280north/narwhal/blob/master/lib/args.js

And an example using it:

http://github.com/280north/narwhal/blob/master/lib/narwhal/tusk.js

Add reflection to the args parser that generates a JSON representation
of all the commands and possible options at the different levels of the
command/argument tree.

This data can be used to back a REST API to discover available commands.
A documentation tool can use this to pull all relevant info.

Similar JSON structures could be posted to a REST API (or passed to
OS.command() directly) that executes the described command with provided
arguments.

This approach provides a way of invoking commands in a consistent
fashion that is easily manipulated vs plain old strings.

Christoph

[Ash Berlin]

On 11 May 2010, at 22:02, Kris Kowal wrote:
> On Tue, May 11, 2010 at 1:26 PM, Donny Viszneki
> <donny.v...@gmail.com> wrote:
>> Personally I think it's a mistake to fragment the user interface
>> across multiple programs meant to work together.
>
> I do not understand what you mean by "fragment". I'm proposing that
> we make a standard. Do you mean that, if this were a standard, there
> would necessarily be non-conformant variations?
>
>> Consider the case of passing options to the linker when executing gcc.
>> gcc never gives you an error report like this:
>>
>> usage: gcc: ld: how to use ld via gcc command
>
> I think this is a red herring. This is not a necessary conclusion of
> separating [argv[0]] from argv[1..]. It's also not closely related to
> my example since it involves options and not positional arguments.
>
> Kris Kowal

I'm in favour of separating program/script name fro the rest of the args - its what perl does ($0 vs @ARGV). But I disagree with the last part of the above, simply because command line arguments have no intrinsic meaning of their own - options vs positional arguments are just how you use the args.

-ash

[Donny Viszneki]

I actually really like this idea. I don't really see a strong
connection though between it and the OP :P

On Thu, May 13, 2010 at 12:24 PM, Christoph Dorn
<christ...@christophdorn.com> wrote:
> Add reflection to the args parser that generates a JSON representation of
> all the commands and possible options at the different levels of the
> command/argument tree.
>
> This data can be used to back a REST API to discover available commands.   A
> documentation tool can use this to pull all relevant info.
>
> Similar JSON structures could be posted to a REST API (or passed to
> OS.command() directly) that executes the described command with provided
> arguments.
>
> This approach provides a way of invoking commands in a consistent fashion
> that is easily manipulated vs plain old strings.

--
http://codebad.com/