Documentation for run is unclear: what are args?

[fingolfin]

The documentation for run says this:

    run(command, args...; wait::Bool = true)

Run a command object, constructed with backticks (see the [Running External Programs](@ref)
section in the manual). Throws an error if anything goes wrong, including the process
exiting with a non-zero status (when `wait` is true).

...

But nowhere is explained what args is about. One might think that it is meant to be arguments to the command; but that doesn't seem the case:

julia> run(`ls`, "-l")
ERROR: MethodError: no method matching spawn_opts_inherit(::String)
Closest candidates are:
  spawn_opts_inherit() at process.jl:312
  spawn_opts_inherit(::Tuple{Union{RawFD, Base.FileRedirect, IO},Union{RawFD, Base.FileRedirect, IO},Union{RawFD, Base.FileRedirect, IO}}) at process.jl:306
  spawn_opts_inherit(::Union{RawFD, Base.FileRedirect, IO}) at process.jl:312
  ...
Stacktrace:
 [1] run(::Cmd, ::String; wait::Bool) at ./process.jl:439
 [2] run(::Cmd, ::String) at ./process.jl:438
 [3] top-level scope at REPL[6]:1

So, what is args really for?

[fingolfin]

For that matter, is there a way to run or construct a "backtick command", given a Vector{String} of arguments, other than using join ? It seems wasteful to join the arguments only to then have Julia separate them again (and of course one also has to be careful about quoting whitespace in arguments.

OK, I just (re-)discovered https://docs.julialang.org/en/v1/manual/running-external-programs/#Running-External-Programs-1 and learned that Julia interpolates Vector{String} arguments for me, so this is not an issue, nice!

[rfourquet]

Julia interpolates Vector{String} arguments for me

The Cmd constructor also accepts a Vector{String}.

[fingolfin]

Yeah, the problem is that run does not reference that. At least these days run has a link to a place where the backticks are explained (I added that some time ago), but all in all, I still feel the documentation in general needs tons more intralinks and examples.

E.g. it just took me 10 minutes to figure out (starting from the run documentation) that I don't need to mess with wait and success etc. in order to avoid the exception in run in case of an error: I can simply use p=run(ignorestatus(cmd)). Of course if one reads the documentation from top to bottom, one "knows" this, but otherwise you are screwed. But note it It is not even mentioned on https://docs.julialang.org/en/v1/manual/running-external-programs

If nobody beats me to it, I'll eventually submit a PR to improve this particular issue.

But really, the same holds for basically every part of the Julia documentation I've looked at so far. Which is why I usually actually do read everything "around" the documentation of a command in the hopes of finding clues how to actually use it; but that doesn't scale too well. It's also not available in the built-in help , i.e. ?run gives me no help with this whatsoever (in GAP, the built-in help actually allows me to scroll around in the documentation, just like the help in my browser).

So, I've a feeling that Julia really needs a "improve the documentation push".

[rfourquet]

in GAP, the built-in help actually allows me to scroll around in the documentation

Yes I used it recently and found that really nice, also with the wish that some "reference" docs would be available at the Julia REPL without having to go to the online manual. In case you are not aware, note also that there is now (#34226) some support for "extended help", which is shown at the REPL with ??.

[StefanKarpinski]

in GAP, the built-in help actually allows me to scroll around in the documentation

Do you know how it's implemented? Pipe to less?

[fingolfin]

Yes, invokes less (but not via a pipe; the manual chapters are in .txt files with escape codes to render them nicely, aned less is told the filename and line offset; but of course that's a minor technical detail).

Alternatively, one can configure the help system to open the HTML documentation in a browser at the appropriate position; or also the PDF version (I think there's also support for DVI, but that's kinda oldfashioned ;-).

[fingolfin]

There is more, though: e.g. one can browse the help in the terminal; search the help and navigate entries (select with up/down arrow the one you like and press return to view it) etc., all via ncurses. That said, if one could set ?foobar to just jump to the HTML documentation that would also be fine (perhaps that's already possible and I just don't know how?)

But more important (and also much more work ;-) is to actually have better documentation, including many more refs, be it included in the text "... To suppress an exception being thrown, use ignorestatus(link)" or as a simple list at the end: "see also ignorestatus and FOOBAR.". The only way to get there is a concerted effort I guess, either by lots of people chipping in a bit, or a few people doing major work on that front (possibly hired to do so -- if one has the funding)... I am not going to complain too much here, though, as otherwise you might start listing all the projects I work on that have bad documentation, often far worse what Julia has ;-) but then they are also far less important ;-)

[denius]

Thus I don't understand which I should to run:

run(`ls`, ["-l"])

or

run(`ls`, "-l")

or may be

run(`ls`, ("-l",))

None work.

My last task was to run the some command with the args...
I had the solution in

run(`ls $(join(args, " "))`)

but it doesn't work for emty args... === ().

Please tell me which code should work. Thank you.

[fingolfin]

Try run(`ls $args`)

[denius]

It is not worked in the case of empty args because $args gives "" -- one empty argument. Thus I should create if length(args) == 0 ... else ... constructions to resolve this issue.

julia> args = ""
julia> run(`ls $args`)
ls: cannot access '': No such file or directory
ERROR: failed process: Process(`ls ''`, ProcessExited(2)) [2]

Stacktrace:
 [1] pipeline_error at ./process.jl:525 [inlined]
 [2] run(::Cmd; wait::Bool) at ./process.jl:440
 [3] run(::Cmd) at ./process.jl:438
 [4] top-level scope at REPL[2]:1

[fingolfin]

It does work if args is a vector/array of string arguments.

[denius]

Ok, thank you. It's just that this case is not mentioned in the documentation, and I decided to clarify this point.

[fingolfin]

I agree the documentation should be clarified (which is why I submitted this issue!) but as discussed in the comments for this issue, your particular usecase is actually discussed in the following section, which I recommend for reading: https://docs.julialang.org/en/v1/manual/running-external-programs/#Running-External-Programs-1