MR::App Namespace Reference

Classes
class	Argument
	A class to specify a command-line argument. More...
class	ArgumentList
	a class to hold the list of Argument's More...
class	Description
	vector of strings to hold more comprehensive command description More...
class	Example
	object for storing a single example command usage More...
class	ExampleList
	a class to hold the list of Example's More...
class	Option
	A class to specify a command-line option. More...
class	OptionGroup
	a class to hold a named list of Option's More...
class	OptionList
	a class to hold the list of option groups More...
class	ParsedArgument
class	ParsedOption
	object storing information about option parsed from command-line More...

Functions
const char *	argtype_description (ArgType type)
std::string	help_head (int format)
std::string	help_synopsis (int format)
std::string	help_tail (int format)
std::string	usage_syntax (int format)
void	check_overwrite (const std::string &name)
void	init (int argc, const char *const *argv)
	initialise MRtrix and parse command-line arguments More...
void	verify_usage ()
	verify that command's usage() function has set requisite fields [used internally] More...
void	parse_special_options ()
	option parsing that should happen before GUI creation [used internally] More...
void	parse ()
	do the actual parsing of the command-line [used internally] More...
void	sort_arguments (int argc, const char *const *argv)
	sort command-line tokens into arguments and options [used internally] More...
const Option *	match_option (const char *stub)
	uniquely match option stub to Option More...
std::string	full_usage ()
	dump formatted help page [used internally] More...
const vector< ParsedOption >	get_options (const std::string &name)
	return all command-line options matching name More...
template<typename T >
T	get_option_value (const std::string &name, const T default_value)
	Returns the option value if set, and the default otherwise. More...
std::string	operator+ (const char *left, const App::ParsedArgument &right)
	convenience function provided mostly to ease writing Exception strings More...
std::ostream &	operator<< (std::ostream &stream, const App::ParsedArgument &arg)
void	set_executable_uses_mrtrix_version ()

Variables
const char *	mrtrix_version
const char *	build_date
int	log_level
int	exit_error_code
std::string	NAME
std::string	command_history_string
bool	overwrite_files
void(*	check_overwrite_files_func )(const std::string &name)
bool	fail_on_warn
bool	terminal_use_colour
const std::thread::id	main_thread_ID
int	argc
const char *const *	argv
const char *	project_version
const char *	project_build_date
vector< ParsedArgument >	argument
	the list of arguments parsed from the command-line More...
vector< ParsedOption >	option
	the list of options parsed from the command-line More...
Description	DESCRIPTION
	additional description of the command over and above the synopsis More...
ExampleList	EXAMPLES
	example usages of the command More...
ArgumentList	ARGUMENTS
	the arguments expected by the command More...
OptionList	OPTIONS
	the options accepted by the command More...
bool	REQUIRES_AT_LEAST_ONE_ARGUMENT
	set to false if command can operate with no arguments More...
const char *	AUTHOR
	set the author of the command More...
const char *	COPYRIGHT
	set the copyright notice if different from that used in MRtrix More...
const char *	SYNOPSIS
	set a one-sentence synopsis for the command More...
Description	REFERENCES
	add references to command help page More...
OptionGroup	__standard_options
	the group of standard options for all commands More...

Function Documentation

argtype_description()

const char * MR::App::argtype_description

(

ArgType

type

)

check_overwrite()

void MR::App::check_overwrite ( const std::string &  name )

inline

Definition at line 168 of file app.h.

full_usage()

std::string MR::App::full_usage

(

)

dump formatted help page [used internally]

get_option_value()

template<typename T >

T MR::App::get_option_value ( const std::string &  name, const T  default_value  )

inline

Returns the option value if set, and the default otherwise.

Returns the value of (the first occurence of) option name or the default value provided as second argument.

Use:

float arg1 = get_option_value("myopt", arg1_default);
int arg2 = get_option_value("myotheropt", arg2_default);

Definition at line 465 of file app.h.

get_options()

const vector< ParsedOption > MR::App::get_options

(

const std::string &

name

)

return all command-line options matching name

This returns a vector of vectors, where each top-level entry corresponds to a distinct instance of the option, and each entry within a top-level entry corresponds to a argument supplied to that option.

Individual options can be retrieved easily using the as_* methods, or implicit type-casting. Any relevant range checks are performed at this point, based on the original App::Option specification. For example:

Options opt = get_options ("myopt");
if (opt.size()) {
   std::string arg1 = opt[0][0];
   int arg2 = opt[0][1];
   float arg3 = opt[0][2];
   vector<int> arg4 = opt[0][3];
   auto values = opt[0][4].as_sequence_float();
}

help_head()

std::string MR::App::help_head

(

int

format

)

help_synopsis()

std::string MR::App::help_synopsis

(

int

format

)

help_tail()

std::string MR::App::help_tail

(

int

format

)

init()

void MR::App::init	(	int	argc,
		const char *const *	argv
	)

initialise MRtrix and parse command-line arguments

this function must be called from within main(), immediately after the argument and options have been specified, and before any further processing takes place.

match_option()

const Option * MR::App::match_option

(

const char *

stub

)

uniquely match option stub to Option

operator+()

std::string MR::App::operator+ ( const char *  left, const App::ParsedArgument &  right  )

inline

convenience function provided mostly to ease writing Exception strings

Definition at line 474 of file app.h.

operator<<()

std::ostream & MR::App::operator<< ( std::ostream &  stream, const App::ParsedArgument &  arg  )

inline

Definition at line 482 of file app.h.

parse()

void MR::App::parse

(

)

do the actual parsing of the command-line [used internally]

parse_special_options()

void MR::App::parse_special_options

(

)

option parsing that should happen before GUI creation [used internally]

set_executable_uses_mrtrix_version()

void MR::App::set_executable_uses_mrtrix_version

(

)

sort_arguments()

void MR::App::sort_arguments	(	int	argc,
		const char *const *	argv
	)

sort command-line tokens into arguments and options [used internally]

usage_syntax()

std::string MR::App::usage_syntax

(

int

format

)

verify_usage()

void MR::App::verify_usage

(

)

verify that command's usage() function has set requisite fields [used internally]

Variable Documentation

__standard_options

OptionGroup MR::App::__standard_options

extern

the group of standard options for all commands

argc

int MR::App::argc

extern

argument

vector<ParsedArgument> MR::App::argument

extern

the list of arguments parsed from the command-line

ARGUMENTS

ArgumentList MR::App::ARGUMENTS

extern

the arguments expected by the command

This is designed to be used within each command's usage() function. Add argument and their description using the Argument class and the'+' operator, e.g.:

void usage() {
  ...
 
  ARGUMENTS
  + Argument ("in", "the input image").type_image_in()
  + Argument ("factor", "the factor to use in the analysis").type_float()
  + Argument ("out", "the output image").type_image_out();
}

argv

const char* const* MR::App::argv

extern

AUTHOR

const char* MR::App::AUTHOR

extern

set the author of the command

build_date

const char* MR::App::build_date

extern

check_overwrite_files_func

void(* MR::App::check_overwrite_files_func) (const std::string &name) ( const std::string &  name )

extern

command_history_string

std::string MR::App::command_history_string

extern

COPYRIGHT

const char* MR::App::COPYRIGHT

extern

set the copyright notice if different from that used in MRtrix

DESCRIPTION

Description MR::App::DESCRIPTION

extern

additional description of the command over and above the synopsis

This is designed to be used within each command's usage() function. Add a paragraph to the description using the '+' operator, e.g.:

void usage() {
  DESCRIPTION
  + "This command can be used in lots of ways "
    "and is very versatile."
 
  + "More description in this paragraph. It has lots of options "
    "and arguments.";
}

EXAMPLES

ExampleList MR::App::EXAMPLES

extern

example usages of the command

This is designed to be used within each command's usage() function. Add various examples in order to demonstrate the different syntaxes and/or capabilities of the command, e.g.:

void usage() {
  ...
 
  EXAMPLES
  + Example ("Perform the command's default functionality",
             "input2output input.mif output.mif",
             "The default usage of this command is as trivial as "
             "providing the name of the command, then the input image, "
             "then the output image.");
}

exit_error_code

int MR::App::exit_error_code

extern

Definition at line 35 of file exception.h.

fail_on_warn

bool MR::App::fail_on_warn

extern

log_level

int MR::App::log_level

extern

Definition at line 34 of file exception.h.

main_thread_ID

const std::thread::id MR::App::main_thread_ID

extern

mrtrix_version

const char* MR::App::mrtrix_version

extern

NAME

std::string MR::App::NAME

extern

Definition at line 25 of file debug.h.

option

vector<ParsedOption> MR::App::option

extern

the list of options parsed from the command-line

OPTIONS

OptionList MR::App::OPTIONS

extern

the options accepted by the command

This is designed to be used within each command's usage() function. Add options, their arguments, and their description using the Option and Argument classes and the'+' operator, e.g.:

void usage() {
  ...
 
  OPTIONS
  + Option ("advanced", "use advanced analysis")
 
  + Option ("range", "the range to use in the analysis")
  +   Argument ("min").type_float()
  +   Argument ("max").type_float();
}

overwrite_files

bool MR::App::overwrite_files

extern

project_build_date

const char* MR::App::project_build_date

extern

project_version

const char* MR::App::project_version

extern

REFERENCES

Description MR::App::REFERENCES

extern

add references to command help page

Like the description, use the '+' operator to add paragraphs (typically one citation per paragraph)."

REQUIRES_AT_LEAST_ONE_ARGUMENT

bool MR::App::REQUIRES_AT_LEAST_ONE_ARGUMENT

extern

set to false if command can operate with no arguments

By default, the help page is shown command is invoked without arguments. Some commands (e.g. MRView) can operate without arguments.

SYNOPSIS

const char* MR::App::SYNOPSIS

extern

set a one-sentence synopsis for the command

terminal_use_colour

bool MR::App::terminal_use_colour

extern