Cobra subcommands

[Charles]

Tools like svn, git and hg have subcommands such as:

Code: Select all

svn status -v somefile.txt
hg clone http://foo.com/bar
hg add somefile.txt
hg commit -m 'Comment'

The general form is:

Code: Select all

<program> <global-options> <sub-command> <sub-command-options> <files>

I'm thinking this would work well for Cobra which already effectively has subcommands including compile, run, test, document and highlight, and could gain more. Let's spell out some examples:

Code: Select all

# run (which implies compilation since you're passing in source)
cobra run Foo.cobra

# but run is also the default
cobra Foo.cobra

# passing args to your program
cobra Foo.cobra -- arg1 arg2

# compile only
cobra compile Foo.cobra

# commands often have abbreviations
cobra c Foo.cobra

# test
cobra -v test Foo.cobra Bar.cobra

# highlight
cobra highlight -styles:cobra Foo.cobra Bar.cobra
cobra highlight -styles:pygments Foo.cobra Bar.cobra


The above approach makes it trivial to have command-specific options.

I know hops already proposed something similar and also provided a patch. What I'm suggesting here is that the well known form currently used by the source code control clients is both well designed and familiar enough that we should adopt it for Cobra.

Did I miss any important examples or issues? Any feedback?

[hopscc]

I think that this is confusing two different workflows

The VCS systems that do this have a (sub)set of sub commands that are all commonly used cyclically through a workflow
(get, status, diff, checkin - say) that do markedly different things and are approximately equally likely to be run.
The possible actions are a cycle through various work states


The cobra compiler does one thing with various added benefits
compile and run
compile and run with args
compile (only)
compile and run tests
compile (partially) and emit annotated source
(additionally)
compile (partially) and emit metrics

The approximate frequency of use is as listed.

The difference is that this is a single action with occasional variants/branches, non cyclic, non varying workflow commands

Using a pure subcommand interface forces the same interface load on every subcommand over the existing case that minimises the loading for the most common case.

[Charles]

The commands for SCC are not equally likely to be run. I issue "svn update" much more than "svn checkout", and "svn diff" much more than "svn checkin".

I agree there is a workflow there and I also agree that the different functions of cobra.exe have overlap. But it's not clear to me why those points would exclude a sub-command approach. We almost use that approach now which you'll realize if you look at the existing CommandLine.run's if-else ladder for invoking .doTestify, .doRun, doTest, .doCompile, etc.

I currently see branching there on:

testify, run, test, compiler, highlight, document, document-library, help, version, about, build-standard-library[, metrics]

Are you worried that options will have to be specified twice? They could be specified once and shared.

[hopscc]

Sorry should have replied to this Question:

Are you worried that options will have to be specified twice?

I'm more worried that I;ll be forced to specify a longer more baroque command line for the most common case (compile source to exe , compile and run) for
the purported benefit of gaining a common sub-command oriented syntax for all the cases.

I also have reservations about the current functionality growth of adding more and more varying compiler-functionality-using behaviours into a monolithic (admittedly well structured) compiler code base..

To my biases it would be preferable to build a compilation library and a pure compiler exe using it
( or a single purpose source to exe compiler and a library)
supporting the core compiler behaviours (run, test, compiler, help,version, about)
and implement the 'minor' subfunction/variants
(testify, highlight, document, document-library, build-standard-library[, metrics] (version, about))
as stand alones executables using the compilation library.

[Charles]

Sorry should have replied to this Question:

Are you worried that options will have to be specified twice?

I'm more worried that I;ll be forced to specify a longer more baroque command line for the most common case (compile source to exe , compile and run) for
the purported benefit of gaining a common sub-command oriented syntax for all the cases.

When Cobra source files are specified, the default will be to compile and run as it is now. So you still have:

> cobra Prog.cobra

I'm more worried about breakage of existing scripts and makefiles, but I think that could be minimized by supporting -c/-compile and -r/-run when used in the first argument position

I also have reservations about the current functionality growth of adding more and more varying compiler-functionality-using behaviours into a monolithic (admittedly well structured) compiler code base..

To my biases it would be preferable to build a compilation library and a pure compiler exe using it
( or a single purpose source to exe compiler and a library)
supporting the core compiler behaviours (run, test, compiler, help,version, about)
and implement the 'minor' subfunction/variants
(testify, highlight, document, document-library, build-standard-library[, metrics] (version, about))
as stand alones executables using the compilation library.

What would the additional executables be called? Why should one have to remember that compiling is "cobra -c ..." but highlighting is "cobra-highlight ...". With the subcommand interface, it's uniform.

Although I haven't mentioned this before, I'm leaning towards a cobra.exe that has the smallest commands--help, version, about--built-in with everything else a foo.dll that gets loaded when needed. But this would not be generally notable/visible to users of Cobra.

A further change I have in mind is requiring the .cobra extension on filenames so that the transition to arguments is clear. I think making the source file extensions optional was a wrong turn.

[Charles]

This is the specification I have so far. I start with examples and then list key points.

Examples

cobra
cobra about
cobra version
cobra help
cobra help document-library

Both the same:
cobra c -d Foo.cobra Bar.cobra
cobra compile -d Foo.cobra Bar.cobra

All 3 the same:
cobra Foo.cobra Bar.cobra arg1 arg2
cobra r Foo.cobra Bar.cobra arg1 arg2
cobra run Foo.cobra Bar.cobra arg1 arg2

More:
cobra doc-lib Foo.dll
cobra document-library Foo.dll
cobra testify -threads:4

Some backwards compatibility for common cases:
cobra -c Foo.cobra Bar.cobra
cobra -compile Foo.cobra Bar.cobra
cobra -r Foo.cobra Bar.cobra arg1 arg2
cobra -run Foo.cobra Bar.cobra arg1 arg2

Details

General form:
cobra <global-options> <sub-command> <sub-command-options> <source-files> <program-arguments>

Subcommands in no particular order:

about, version, help
compile, run, test
highlight, document, document-library
metrics
build-standard-library, testify

Subcommands may have abbreviations like "doc-lib" for "document-library". These can be seen in help.

The .cobra extension is required on source files.

Recognize the transition from source files to command line arguments intended for the program when extensions (*.cobra) are no longer present. Only for the "run" command.

When no arguments are present, default to "about".

When Cobra source files are present, but no subcommand is, default to "run".

Support -c and -compile in place of "compile" and -r and -run in place of "run".

Cobra subcommands may live in DLLs that are loaded on demand, but this is an implementation detail.

The @args directive is only applicable when doing a "compile", "run" or "test", and cannot specify a different subcommand.

[todd.a]

I think this works great for the SC tools but when I hear subcommands, OpenSSL's client comes to mind--always need to dig though a lot of docs, but this might simply be due to the scope of the tool. I do prefer having commands versus separate programs like cobradoc, cobratest, etc. but I like pacman's option format (http://www.archlinux.org/pacman/pacman.8.html), which gives subcommand behavior but more succinct.

My concern with the global and subcommand options is potential confusion when the same option is only present between some subcommands and not others. I'm sure there will be warnings for invalid command combinations but I see more help lookups like openssl.

I also second having a compiler lib with a special cmdline tool. This might also help with integrating with other tools. Btw, I don't mind the way the options are currently done, but if growth is the objective then I understand.

[Charles]

You won't have to dig around when you enter "cobra MyProg.cobra" to compile and run in one shot, because that will still be supported. In fact, "cobra MyProg.cobra progArg1 progArg2" will work as expected which is not the case now.

Regarding options that apply in some places and not others, I think that is appropriate. Otherwise what does it mean to use an option with a subcommand that doesn't use it?

We already have a script for building Cobra.Lang.Compiler.dll and I was planning on making that a default of the installer, but again that's fairly invisible to most users most of the time.

I've started coding on the subcommands on my local system. I'll see how it turns out.