Plugins

Miscellaneous Topics

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 SystemExit error but still runs ensure blocks 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, and 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 Origen.app.fail.

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!'

Note that 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 -d or --debug command line options) then 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 exit_status to exit with that status instead.

Full API documentation is available on the API