search

stan-dev / cmdstan

CmdStan, the command line interface to Stan
https://mc-stan.org/users/interfaces/cmdstan
BSD 3-Clause "New" or "Revised" License
212 stars 93 forks source link

interpret return codes for users #991

Open mitzimorris opened 3 years ago

mitzimorris commented 3 years ago

Summary:

Improve error hadling by mapping stan::services::error_codes to messages that make sense to end-user.

Description:

Module stan::services adopted a small set of POSIX error codes following Unix conventions - https://github.com/stan-dev/stan/blob/develop/src/stan/services/error_codes.hpp

Use of these codes is not consistent across the services, nor does command.hpp do a very good job of interpreting them for the user. Modify command.hpp to provide better feedback for common user mistakes, such as missing data inputs, etc.

All exceptions thrown from command.hpp are caught by main.cpp which uniformly returns error code 70 (stan::services::error_codes::SOFTWARE).

The stan::services error codes shouldn't be reported to end user in CmdStan. Instead, we should replace error code 70 et all with more generally accepted codes

Current Version:

v2.26.1

mitzimorris commented 3 years ago

note this: https://github.com/stan-dev/stan/issues/2534

mitzimorris commented 3 years ago

PR #992 improved error messaging by sending error messages to stderr instead of stdout. however, the problem with return codes remains; leaving issue open for further improvements.

mitzimorris commented 3 years ago

suggestion would be to follow this: https://shapeshed.com/unix-exit-codes/

What exit code should I use?

The Linux Documentation Project has a list of reserved codes that also offers advice on what code to use for specific scenarios. These are the standard error codes in Linux or UNIX.

1 - Catchall for general errors 2 - Misuse of shell builtins (according to Bash documentation) 126 - Command invoked cannot execute 127 - “command not found” 128 - Invalid argument to exit 128+n - Fatal error signal “n” 130 - Script terminated by Control-C 255* - Exit status out of range

mitzimorris commented 3 years ago

given the above, all stan::services return codes should map to either 1 or 126. recommend 1.