Topics on this page relate to plugins in general but do not fit into any of the previous topics and are too minor in scope and content to warrant their own pages.
Sometimes, the usage of your application or plugin is not correct, certain conditions are not met, or some other circumstance arises in which the application or plugin cannot continue. In these instances, the best course of action is to print the error message and exit the current process.
Ruby provides a few methods to do this. Most commonly:
throw: raises an exception.
fail/raise: raises a runtime error.
exit: raises a
SystemExiterror but still runs
ensureblocks and can be rescued.
exit!: kills the process immediately.
Each of these has their place, but their usefulness is based primarily on the information you, as the developer, provide. For example, using
exit! without any error message
just kills the process, without any information going back to the user.
fail can be used to dump a stack trace, but for those that aren’t power users, and
especially for those who are newer to programming, this can be almost as bad as providing no details, with the exception of sending the stack trace to someone else.
Information on the what, where, when, and why for failing and exiting the process is readily available online, both for Ruby and for programming in general. Discussions on those matters get into best practices, use cases, coding styles, etc., and are way out of the scope of this guide. What will be covered is how Origen can help you when you choose to exit the process and/or raise an exception.
Origen provides two methods to help with this:
Origen.app.fail!. The former behaves almost identically to the standard
fail method, with the exception of accepting a hash instead of string, and prepending the current application that is calling
Note that these are
Origen::Application instance methods, and
Origen.app will always reference the application. For usage in plugins,
Origen.app! should be used instead. See here
for additional information.
Origen.app!.name #=> my_app fail #=> RuntimeError with no message # Just fail the application, without adding details: Origen.app!.fail #=> RuntimeError with message: 'Fail in my_app' # Fail the application with some context: Origen.app!.fail(message: 'An unknown condition occured!') #=> RuntimeError with message: 'Fail in my_app: An unknown condition occured!' # Fail the application with some context and a custom exception: Origen.app!.fail(message: 'An unknown condition occured!', exception_class: StandardError) #=> StandardError with message: 'Fail in my_app: An unknown condition occured!'
exception_class should be a
class object (of type
class), not an instance of the class.
Origen.app.fail! performs the same function as
Origen.app.fail but raises a
SystemExit and quits the process cleanly
(no stack trace). It also prints the message using Origen’s Logger,
instead of using the exception message to convey information.
The key difference, however, is if the current process is run with
debug enabled (using the
--debug command line options)
Origen.app.fail! behaves identically to
Origen.app.fail. The intention is give a user-facing API a clean exit while displaying in the
familiar Origen-logger format, while allowing users to generate more useful bug reports, or just for the curious user themselves to get more information.
Origen.debugger_enabled? #=> false Origen.app!.name #=> :my_app Origen.app.fail!(message: 'An unknown condition occured!') #=> [ERROR] 0.009[0.009] || Fail in my_app: An unknown condition occured! #=> *Process Terminates*
Origen.debugger_enabled? #=> true Origen.app!.name #=> :my_app Origen.app.fail!(message: 'An unknown condition occured!') #=> RuntimeError with message: Fail in my_app: An unknown condition occured! #=> *Process terminates with #raise instead of #exit* #=> *Exception and stack trace printed to console*
By default, the
status of a process exited with
Origen.app.fail! will be
1. You can provide an option
to exit with that status instead.
Full API documentation is available on the API