How can I access command line parameters in Rust?

Question

The Rust tutorial does not explain how to take parameters from the command line. fn main() is only shown with an empty parameter list in all examples.

What is the correct way of accessing command line parameters from main?

score 212 · Accepted Answer · edited Jul 03 '23 at 01:18

You can access the command line arguments by using the std::env::args or std::env::args_os functions. Both functions return an iterator over the arguments. The former iterates over Strings (that are easy to work with) but panics if one of the arguments is not valid unicode. The latter iterates over OsStrings and never panics.

Note that the first element of the iterator is the name of the program itself (this is a convention in all major OSes), so the first argument is actually the second iterated element.

An easy way to deal with the result of args is to convert it to a Vec:

use std::env;

fn main() {
    let args: Vec<_> = env::args().collect();
    if args.len() > 1 {
        println!("The first argument is {}", args[1]);
    }
}

You can use the whole standard iterator toolbox to work with these arguments. For example, to retrieve only the first argument:

use std::env;

fn main() {
    // we use nth(1) for the first argument because
    // nth(0) traditionally corresponds to the binary path
    if let Some(arg1) = env::args().nth(1) {
        println!("The first argument is {}", arg1);
    }
}

You can find libraries on crates.io for parsing command line arguments:

clap: you describe the options you want to parse using a fluent API. Faster than docopt and gives you more control.
getopts: port of the popular C library. Lower-level and even more control.

score 29 · Answer 2 · edited Mar 18 '21 at 05:44

29

Docopt is also available for Rust, which generates a parser for you from a usage string. As a bonus in Rust, a macro can be used to automatically generate the struct and do type based decoding:

docopt!(Args, "
Usage: cp [-a] SOURCE DEST
       cp [-a] SOURCE... DIR

Options:
    -a, --archive  Copy everything.
")

And you can get the arguments with:

let args: Args = Args::docopt().decode().unwrap_or_else(|e| e.exit());

The README and documentation have plenty of full working examples.

Disclaimer: I am one of the authors of this library.

edited Mar 18 '21 at 05:44

Peter Mortensen

30,738
21
105
131

answered Oct 23 '14 at 02:22

BurntSushi5

13,917
7
52
45

docopt has been unmaintained for a long time now. https://github.com/docopt/docopt.rs – Sedat Kapanoglu Jul 03 '23 at 01:20

score 12 · Answer 3 · edited Dec 16 '18 at 19:33

12

Rust has getopt-style CLI argument parsing in the getopts crate.

edited Dec 16 '18 at 19:33

Shepmaster

388,571
95
1,107
1,366

answered Jul 08 '13 at 21:24

Tobu

24,771
4
91
98

score 10 · Answer 4 · answered Jan 09 '16 at 12:33

For me, getopts always felt too low-level and docopt.rs was too much magic. I want something explicit and straightforward that still provides all the features if I need them.

This is where clap-rs comes in handy.
It feels a bit like argparse from Python. Here is an example of how it looks like:

let matches = App::new("myapp")
                      .version("1.0")
                      .author("Kevin K. <kbknapp@gmail.com>")
                      .about("Does awesome things")
                      .arg(Arg::with_name("CONFIG")
                           .short("c")
                           .long("config")
                           .help("Sets a custom config file")
                           .takes_value(true))
                      .arg(Arg::with_name("INPUT")
                           .help("Sets the input file to use")
                           .required(true)
                           .index(1))
                      .arg(Arg::with_name("debug")
                           .short("d")
                           .multiple(true)
                           .help("Sets the level of debugging information"))
                      .get_matches();

You can access your parameters like so:

println!("Using input file: {}", matches.value_of("INPUT").unwrap());

// Gets a value for config if supplied by user, or defaults to "default.conf"
let config = matches.value_of("CONFIG").unwrap_or("default.conf");
println!("Value for config: {}", config);

(Copied from the official documentation)

I like that clap-rs lets you define your interface in a yaml file. Also, it produces really nice looking usage statements. — Chuck Wooters, Feb 19 '17 at 20:43
Is this still up to date? The API in the documentation looks different now — Lennart, May 19 '23 at 08:44

score 4 · Answer 5 · edited Mar 18 '21 at 05:41

4

As of version 0.8/0.9, the correct path to the function args() would be ::std::os::args, i.e.:

fn main() {
  let args: ~[~str] = ::std::os::args();
  println(args[0]);
}

It seems that Rust is still pretty volatile right now with even standard I/O, so this may become out of date fairly quickly.

edited Mar 18 '21 at 05:41

Peter Mortensen

30,738
21
105
131

answered Dec 05 '13 at 21:46

Nick

375
1
3
14

Thanks for the update! Guess I will have to reconsider accepted answer after 1.0 is released. – shutefan Jan 16 '14 at 20:59

score 4 · Answer 6 · answered Oct 09 '17 at 14:30

Also check out structopt:

extern crate structopt;
#[macro_use]
extern crate structopt_derive;

use structopt::StructOpt;

#[derive(StructOpt, Debug)]
#[structopt(name = "example", about = "An example of StructOpt usage.")]
struct Opt {
    /// A flag, true if used in the command line.
    #[structopt(short = "d", long = "debug", help = "Activate debug mode")]
    debug: bool,

    /// An argument of type float, with a default value.
    #[structopt(short = "s", long = "speed", help = "Set speed", default_value = "42")]
    speed: f64,

    /// Needed parameter, the first on the command line.
    #[structopt(help = "Input file")]
    input: String,

    /// An optional parameter, will be `None` if not present on the
    /// command line.
    #[structopt(help = "Output file, stdout if not present")]
    output: Option<String>,
}

fn main() {
    let opt = Opt::from_args();
    println!("{:?}", opt);
}

https://github.com/TeXitoi/structopt

structopt is now available through clap, too. – Caesar Apr 01 '22 at 00:27 — Caesar, Apr 01 '22 at 00:27

score 4 · Answer 7 · answered Oct 11 '22 at 20:58

I personally don't like using a library in smaller projects if it is not necessary and parsing commandline arguments in Rust is pretty straight forward:

fn main() {
    let config: String;

    let mut args = env::args().skip(1);
    while let Some(arg) = args.next() {
        match &arg[..] {
            "-h" | "--help" => help(),
            "--version" => {
                println!("{} {}", prog().unwrap_or_default(), VERSION);
            }
            "-q" | "--quiet" => {
                println!("Quiet mode is not supported yet.");
            }
            "-v" | "--verbose" => {
                println!("Verbose mode is not supported yet.");
            }
            "-c" | "--config" => {
                if let Some(arg_config) = args.next() {
                    config = arg_config;
                } else {
                    panic!("No value specified for parameter --config.");
                }
            }
            _ => {
                if arg.starts_with('-') {
                    println!("Unkown argument {}", arg);
                } else {
                    println!("Unkown positional argument {}", arg);
                }
            }
        }
    }
}

In order to handle non-string arguments you can use the String::parse() method to try to parse the given string as the specified type:

"-s" | "--size" => {
    if let Some(arg_size) = arg_it.next() {
        size = arg_size
            .parse::<usize>()
            .expect("Size argument expects an integer value.");
    } else {
        panic!("No value specified for parameter size.");
    }
}

If you would like to handle values with an equal sign (=) instead of a whitespace, you can include the following code above the match clause and match the key value instead:

let (key, value) = match arg.contains('=') {
    true => {
        let str_vec: Vec<&str> = arg.split('=').collect();
        (String::from(str_vec[0]), Some(String::from(str_vec[1])))
    },
    false => {
        (arg, None)
    }
};

score 3 · Answer 8 · edited May 05 '16 at 22:08

3

Rust changed again. os::args() is deprecated in favor of std::args(). But std::args() is not an array, it returns an iterator. You can iterate over the command line arguments, but cannot access them with subscripts.

http://doc.rust-lang.org/std/env/fn.args.html

If you want the command line arguments as a vector of strings, this will work now:

use std::env;
...
let args: Vec<String> = env::args().map(|s| s.into_string().unwrap()).collect();

Rust - learn to embrace the pain of change.

edited May 05 '16 at 22:08

malbarbo

10,717
1
42
57

answered Feb 05 '15 at 23:47

John Nagle

1,530
1
14
15

10

You now need only do `env::args().collect()`. – tshepang Feb 23 '15 at 02:11

score 2 · Answer 9 · edited Mar 18 '21 at 05:40

2

What barjak said works for strings, but if you need the argument as a number (in this case a uint) you need to convert like this:

fn main() {
    let arg : ~[~str] = os::args();
    match uint::from_str(arg[1]){
         Some(x)=>io::println(fmt!("%u",someFunction(x))),
         None=>io::println("I need a real number")
    }
}

edited Mar 18 '21 at 05:40

Peter Mortensen

30,738
21
105
131

answered May 11 '13 at 17:46

Calvin

784
4
10

score 2 · Answer 10 · edited Nov 25 '15 at 17:14

The Rust book "No stdlib" chapter covers how to access the command lines parameters (another way).

// Entry point for this program
#[start]
fn start(_argc: isize, _argv: *const *const u8) -> isize {
    0
}

Now, the example does also have #![no_std] which I think means that normally, the std library would have the true entry point for your binary and call a global function called main(). Another options is to 'disable the main shim' with #![no_main]. Which if I'm not mistaken is saying to the compiler that you are taking full control over how your program is started.

#![no_std]
#![no_main]

#[no_mangle] // ensure that this symbol is called `main` in the output
pub extern fn main(argc: isize, argv: *const *const u8) -> isize {
    0
}

_{I do not think this is a 'good' way of doing things if all you want to do is read command line arguments. The std::os module mentioned in other answers seems to be a much better way of doing things. I post this answer for the sake of completion.}

Yilmaz · Answer 11 · 2022-02-28T05:24:10.853

If you want to iterate over command-line arguments:

use std::env::{args,Args};

fn main() {
    let mut args:Args=args();
    // args.nth(0) cannot borrow as mutable. that is why  let mut args
    // nth return an element of iterator
    let first=args.nth(1).unwrap();
    // iterator has next method. we want to get the first element of next iterator. NOT args.nth(2)
    // chars returns an iterator
    let operator=args.nth(0).unwrap().chars().next().unwrap();
    let second=args.nth(0).unwrap();
}

If you want to access the n'th argument directly:

fn get_nth_arg(n:usize)->String{
    std::env::args().nth(n).unwrap()
}

score 1 · Answer 12 · edited Mar 18 '21 at 05:42

1

~~As of newer Rust versions (Rust > 0.10/11) the array syntax won't work. You will have to use the get method.~~

The array syntax works (again) in the nightly. So you can choose between the getter or array index.

use std::os;

fn main() {
  let args = os::args();
  println!("{}", args.get(1));
}

// Compile
rustc args.rs && ./args hello-world // returns hello-world

edited Mar 18 '21 at 05:42

Peter Mortensen

30,738
21
105
131

answered Aug 11 '14 at 17:19

pat

5,757
5
25
30

This is obsolete statement. Latest Rust nightlies do support indexing syntax on `Vec`s. I guess it is there for a month or so. See [this example](http://is.gd/YRvx3C). – Vladimir Matveev Aug 14 '14 at 18:54

score 1 · Answer 13 · edited Mar 18 '21 at 05:42

1

Rust has evolved since Calvin's answer from May 2013. Now one would parse command line arguments with as_slice():

use std::os;

fn seen_arg(x: uint)
{       
    println!("you passed me {}", x);
}
fn main() {
    let args = os::args();
    let args = args.as_slice();
    let nitems = {
            if args.len() == 2 {
                    from_str::<uint>(args[1].as_slice()).unwrap()
            } else {
                    10000
            }
    };

    seen_arg(nitems);
}

edited Mar 18 '21 at 05:42

Peter Mortensen

30,738
21
105
131

answered Oct 17 '14 at 13:36

Rob Latham

5,085
3
27
44

Just for the record: `as_slice()` doesn't exist anymore and `&args` should be used instead. – Slava Semushin Oct 13 '16 at 19:15

How can I access command line parameters in Rust?

13 Answers13

Linked

Related