内容简介:The goal of this library is to provide human friendly and standard way to use exit status codes in command line applications. Instead of sayingThe exit statuses range from 0 to 255 (inclusive). Any other exit status than 0 indicates a failure of some kind.
TTY::Exit
Terminal exit codes for humans and machines.
The goal of this library is to provide human friendly and standard way to use exit status codes in command line applications. Instead of saying exit(64)
, you can say exit_with(:usage_error)
. Both indicate a failure to the parent process but the :usage_error
is so much nicer! Wouldn't you agree? That's why tty-exit
gathers a list of all the most common exit codes as used by POSIX-compliant tools on different Unix systems for you to use.
The exit statuses range from 0 to 255 (inclusive). Any other exit status than 0 indicates a failure of some kind. The exit codes in the range 64-78 are adapted from the OpenBSD sysexits.h . The codes between 125 and 128 are reserved for shell statuses as defined in Advanced Bash Scripting Guide, Appendix E . The codes in the 129-154 range correspond with the fatal signals as defined in signal .
TTY::Exitprovides independent terminal exit codes component for TTY toolkit.
Installation
Add this line to your application's Gemfile:
gem 'tty-exit'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install tty-exit
Contents
1. Usage
To exit from any program use exit_with
method. Instead of a number, you can use a readable name for the exit status:
TTY::Exit.exit_with(:usage_error)
The above will exit program immediately with an exit code indicating a failure:
puts $?.exitstatus # => 64
All the reserved exit statuses have a matching exit message. To display a default message, as a second argument to exit_with
you can pass :default
value:
TTY::Exit.exit_with(:usage_error, :default)
That will produce the following user friendly message:
# => "ERROR(64): Command line usage error"
The preferred way is to include TTY::Exit module in your code:
class Command include TTY::Exit def execute exit_with(:config_error, :default) end end
This will print an error message and return appropriate exit status:
cmd = Command.new cmd.execute # => "ERROR(78): Configuration Error" puts $?.exitstatus # => 78
To see the full list of reserved exit codes go tosection.
2. API
2.1 exit_code
There are many built-in exit codes that can be referenced using a name.
For example to return an exit code denoting success, you can use :ok
or :success
:
TTY::Exit.exit_code(:ok) # => 0 TTY::Exit.exit_code(:success) # => 0
Any other exit status than 0 indicates a failure of some kind. For example, when a command cannot be found use :not_found
:
TTY::Exit.exit_code(:not_found) # => 127
You can also use an exit code directly:
TTY::Exit.exit_code(127) # => 127
2.2 exit_message
One of the downsides of exit codes is that they are not very communicative to the user. Why not have both? An exit code and a user friendly message. That's what exit_message
is for. All the reserved exit codes have corresponding user friendly messages.
For example, when returning exit code 64
for usage error:
TTY::Exit.exit_message(:usage_error) TTY::Exit.exit_message(64)
Will return:
# => "ERROR(64): Command line usage error"
The default messages are used by the exit_with
method and can be overwritten by a custom one.
2.3 exit_with
To exit program with an exit code use exit_with
. This method accepts a name or a code for the exit status.
TTY::Exit.exit_with(:usage_error) TTY::Exit.exit_with(64)
Both will produce the same outcome.
As a second argument you can specify a user friendly message to be printed to stderr
before exit. To use predefined messages use :default
as a value:
TTY::Exit.exit_with(:usage_error, :default) # => "ERROR(64): Command line usage error"
Optionally, you can provide a custom message to display to the user.
TTY::Exit.exit_with(:usge_error, "Wrong arguments") # => "Wrong arguments"
Finally, you can redirect output to a different stream using :io
option. By default, message is printed to stderr
:
TTY::Exit.exit_with(:usage_error, io: $stdout)
Since TTY::Exit
is a module, you can include it in your code to get access to all the methods:
class Command include TTY::Exit def execute exit_with(:usage_error, :default) end end
2.4 register_exit
If the provided exit codes don't match your needs, you can add your own using the register_exit
method.
For example, to register a custom exit with :too_long
name and the status 7
that will notify user and programs about too many arguments do:
class Command include TTY::Exit register_exit(:too_long, 7, "Argument list too long") def execute exit_with(:too_long, :default) end end
Then when the command gets run:
cmd = Command.new cmd.execute # => # ERROR(7): Argument list too long
2.5 exit_reserved?
To check if an exit code is already reserved by Unix system use exit_reserved?
. This is useful in situations where you want to add it your command line application custom exit codes. The check accepts only integer numbers in range 0 to 255 inclusive:
TTY::Exit.exit_reserved?(126) # => true TTY::Exit.exit_reserved?(100) # => false
2.6 exit_valid?
The exit statuses range from 0 to 255 (inclusive). The exit_valid?
method helps you check if an exit status is within the range or not.
TTY::Exit.exit_valid?(11) # => true TTY::Exit.exit_valid?(522) # => false
2.7 exit_success?
Any other exit status than 0 indicates a failure of some kind. The exit_success?
is a more descriptive way to determine if a program succeeded or not.
TTY::Exit.exit_success?(0) # => true TTY::Exit.exit_success?(7) # => false
2.8 exit_codes
You can access all the predefined exit codes and their names with exit_codes
method:
TTY::Exit.exit_codes # => # "{:ok=>0, :success=>0, :error=>1, :shell_misuse=>2, :usage_error=>64, :data_error=>65, ... }"
2.9 exit_messages
To see what default messages are for the predefined exit codes use exit_messages
:
TTY::Exit.exit_messages # => # "{0=>"Successful termination", 1=>"An error occurred", 2=>"Misuse of shell builtins", 64=>"Command line usage error", ... }"
The exit statuses range from 0 to 255 (inclusive). Any other exit status than 0 indicates a failure of some kind. The exit codes in the range 64-78 are adapted from the OpenBSD sysexits.h . The codes between 125 and 128 are reserved for shell statuses as defined in Advanced Bash Scripting Guide, Appendix E . The codes in the 129-154 range correspond with the fatal signals as defined in signal .
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org .
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-exit . This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct .
License
The gem is available as open source under the terms of the MIT License .
Code of Conduct
Everyone interacting in the TTY::Exit project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct .
Copyright
Copyright (c) 2020 Piotr Murach. See LICENSE for further details.
以上所述就是小编给大家介绍的《TTY-Exit: terminal exit codes for humans and machines》,希望对大家有所帮助,如果大家有任何疑问请给我留言,小编会及时回复大家的。在此也非常感谢大家对 码农网 的支持!
猜你喜欢:本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们。
The Art and Science of Java
Eric Roberts / Addison-Wesley / 2007-3-1 / USD 121.60
In The Art and Science of Java, Stanford professor and well-known leader in CS Education Eric Roberts emphasizes the student-friendly exposition that led to the success of The Art and Science of C. By......一起来看看 《The Art and Science of Java》 这本书的介绍吧!