ruby-jss 1.0.0b2 → 1.0.0b6

data/lib/jss/api_object/peripheral.rb

@@ -148,7 +148,7 @@ module JSS
       @init_data[:general][:fields].each{|f| @fields[f[:name]] = f[:value] }
 
       ### get the field defs for this PeriphType, omitting the leading nil
-      @field_defs ||= JSS::PeripheralType.new(:name => @type).fields.compact
+      @field_defs ||= JSS::PeripheralType.fetch(:name => @type).fields.compact
 
 
     end # initialize
@@ -269,7 +269,7 @@ module JSS
     ###
     def check_field(field, value)
       ### get the field defs for this PeriphType, omitting the leading nil
-      @field_defs ||= JSS::PeripheralType.new(:name => @type, api: @api).fields.compact
+      @field_defs ||= JSS::PeripheralType.fetch(:name => @type, api: @api).fields.compact
 
       ### we must have the right number of fields, and they must have the same names
       ### as the definition

data/lib/jss/api_object/sitable.rb

@@ -98,7 +98,7 @@ module JSS
     #
     def site_object
       return nil unless site_assigned?
-      JSS::Site.new id: @site_id
+      JSS::Site.fetch id: @site_id
     end # cat obj
 
     # Does this object have a site assigned?

data/lib/jss/api_object.rb

@@ -295,7 +295,7 @@ module JSS
       return identifier if all_ids(refresh, api: api).include? identifier
       all_lookup_keys.keys.each do |key|
         next if key == :id
-        id = map_all_ids_to(key).invert[identifier]
+        id = map_all_ids_to(key, api: api).invert[identifier]
         return id if id
       end # do key
       nil
@@ -996,7 +996,7 @@ module JSS
 
       raise JSS::MissingDataError, "Args must include a lookup key, one of: :#{lookup_keys.join(', :')}" unless lookup_key
 
-      vid = self.class.valid_id args[lookup_key], :refresh
+      vid = self.class.valid_id args[lookup_key], :refresh, api: args[:api]
 
       raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} found with #{lookup_key} '#{args[lookup_key]}'" unless vid
 

data/lib/jss/client/management_action.rb

@@ -63,8 +63,8 @@ module JSS
 
     # Skipping all the force-alerts stuff until we figure out cleaner
     # ways to do it in 10.13+
-    # The plan is to make the NotificationCenter notification always be an
-    # 'alert' (which stays visible til the user clicks) rather than a
+    # The plan is to be able to make the NotificationCenter notification be an
+    # 'alert' (which stays visible til the user clicks) or a
     # 'banner' (which vanishes in a few seconds), regardless of the user's
     # setting in the NC prefs.
 

data/lib/jss/utility.rb

@@ -211,7 +211,7 @@ module JSS
     # if we're here, its a Pathname
     raise JSS::MissingDataError, "No such file: #{plist}" unless plist.file?
 
-    Plist.parse_xml `/usr/libexec/PlistBuddy -x -c print #{Shellwords.escape(plist.to_s)}`
+    Plist.parse_xml `/usr/libexec/PlistBuddy -x -c print #{Shellwords.escape(plist.to_s)}`.force_encoding('UTF-8')
   end # parse_plist
 
   # Converts anything that responds to #to_s to a Time, or nil

data/lib/jss/validate.rb

@@ -42,10 +42,13 @@ module JSS
     #
     # @param val[String] The value to validate
     #
+    # @param msg[String] A custom error message when the value is invalid
+    #
     # @return [String] The valid value
     #
-    def self.mac_address(val)
-      raise JSS::InvalidDataError, "Not a valid MAC address: '#{val}'" unless val =~ MAC_ADDR_RE
+    def self.mac_address(val, msg = nil)
+      msg ||= "Not a valid MAC address: '#{val}'"
+      raise JSS::InvalidDataError, msg unless val =~ MAC_ADDR_RE
       val
     end
 
@@ -53,14 +56,17 @@ module JSS
     #
     # @param val[String] The value to validate
     #
+    # @param msg[String] A custom error message when the value is invalid
+    #
     # @return [String] The valid value
     #
-    def self.ip_address(val)
+    def self.ip_address(val, msg = nil)
+      msg ||= "Not a valid IPv4 address: '#{val}'"
       ok = true
       parts = val.strip.split '.'
       ok = false unless parts.size == 4
       parts.each { |p| ok = false unless p.jss_integer? && p.to_i < 256 && p.to_i >= 0 }
-      raise JSS::InvalidDataError, "Not a valid IPv4 address: '#{val}'" unless ok
+      raise JSS::InvalidDataError, msg unless ok
       val
     end
 
@@ -77,11 +83,16 @@ module JSS
     #
     # @param val[Object] The value to check for uniqueness
     #
+    # @param msg[String] A custom error message when the value is invalid
+    #
+    # @param api[JSS::APIConnection] The api connection to use for validation
+    #
     # @return [Object] the validated unique value
     #
-    def self.unique_identifier(klass, identifier, val, api: JSS.api)
+    def self.unique_identifier(klass, identifier, val, msg = nil, api: JSS.api)
+      msg ||= "A #{klass} already exists with #{identifier} '#{val}'"
       return val unless klass.all(:refresh, api: api).map { |i| i[identifier] }.include? val
-      raise JSS::AlreadyExistsError, "A #{klass} already exists with #{identifier} '#{val}'"
+      raise JSS::AlreadyExistsError, msg
     end
 
     # Confirm that the given value is a boolean value, accepting
@@ -93,13 +104,16 @@ module JSS
     #
     # @param bool [Boolean,String,Symbol] The value to validate
     #
+    # @param msg[String] A custom error message when the value is invalid
+    #
     # @return [Boolean] the valid boolean
     #
-    def self.boolean(bool)
+    def self.boolean(bool, msg = nil)
+      msg ||= 'Value must be boolean true or false'
       return bool if JSS::TRUE_FALSE.include? bool
       return true if bool.to_s =~ /^(true|yes)$/i
       return false if bool.to_s =~ /^(false|no)$/i
-      raise JSS::InvalidDataError, 'Value must be boolean true or false'
+      raise JSS::InvalidDataError, msg
     end
 
     # Confirm that a value is an integer or a string representation of an
@@ -109,11 +123,14 @@ module JSS
     #
     # @param val[Object] the value to validate
     #
+    # @param msg[String] A custom error message when the value is invalid
+    #
     # @return [void]
     #
-    def self.integer(val)
+    def self.integer(val, msg = nil)
+      msg ||= 'Value must be an integer'
       val = val.to_i if val.is_a?(String) && val.jss_integer?
-      raise JSS::InvalidDataError, 'Value must be an integer' unless val.is_a? Integer
+      raise JSS::InvalidDataError, msg unless val.is_a? Integer
       val
     end
 
@@ -121,30 +138,16 @@ module JSS
     #
     # @param val [Object] the thing to validate
     #
+    # @param msg[String] A custom error message when the value is invalid
+    #
     # @return [String] the valid non-empty string
     #
-    def self.non_empty_string(val)
-      raise JSS::InvalidDataError, 'value must be a non-empty String' unless val.is_a?(String) && !val.empty?
+    def self.non_empty_string(val, msg = nil)
+      msg ||= 'value must be a non-empty String'
+      raise JSS::InvalidDataError, msg unless val.is_a?(String) && !val.empty?
       val
     end
 
-    # Confirm that the given value is a boolean value, accepting
-    # strings and symbols and returning real booleans as needed
-    # Accepts: true, false, 'true', 'false', :true, :false, 'yes', 'no', :yes,
-    # or :no (all Strings and Symbols are case insensitive)
-    #
-    #
-    # @param bool [Boolean,String,Symbol] The value to validate
-    #
-    # @return [Boolean] the valid boolean
-    #
-    def self.boolean(bool)
-      return bool if JSS::TRUE_FALSE.include? bool
-      return true if bool.to_s =~ /^(true|yes)$/i
-      return false if bool.to_s =~ /^(false|no)$/i
-      raise JSS::InvalidDataError, 'Value must be boolean true or false'
-    end
-
   end # module validate
 
 end # module JSS

data/lib/jss/version.rb

@@ -27,6 +27,6 @@
 module JSS
 
   ### The version of the JSS ruby gem
-  VERSION = '1.0.0b2'.freeze
+  VERSION = '1.0.0b6'.freeze
 
 end # module

data/test/README.md

@@ -0,0 +1,149 @@
+# About the ruby-jss test suite
+
+For years, I've attempted to use some ruby testing framework to automate testing of ruby-jss.
+
+Every time I've run into walls because unit testing suites are designed for unit testing, and that's not really what we need to do.  Yes we need to test individual methods of classes and so on, but when working with a REST API, there's a lot of
+scaffolding that needs to happen before tests can even start - and that scaffolding itself is testing the code. And the details of the scaffolding will vary in different environments.
+
+For example, the tests *must* be very interactive from the start - you have to tell them what server to connect with, what credentials to use, and so on.
+
+Once connected, objects have to be created before they can be listed, fetched, updated, or deleted - so test order matters.
+
+Also, you need to be able to have later tests refer to the same objects you created in earlier tests. Once I've tested that I can create an object on the server and re-fetch it once, I shuold be able to use that object for all future tests without fetching every time.
+
+Reading most tutorials about ruby testing just leads you in circles when you consider needs such as these.
+
+Many propnents of unit testing might find this suite odd.  Thats ok. Any functional testing suite is better than none and I'm open to suggestions for improvement.
+
+### Here's how to use it:
+
+tldr:
+
+  `/path/to/your/ruby-jss/gem/installation/test/bin/runtests --server myjss.company.com --user myjssusername`
+
+Must be run on a mac, it uses your keychain to store connection data and credentials, so you only have to provide them the first time or when changing them.
+
+See below for the help output
+
+### Here's how this thing works:
+
+ - The tests are ultimatly MiniTest::Spec specifications, defined in files in the 'specs' folder.
+   - See http://ruby-doc.org/stdlib-2.0.0/libdoc/minitest/rdoc/MiniTest.html
+   - also, google around for help with minitest specs
+
+
+ - They do NOT use minitest/autorun. Instead, the 'runtests' executable handles loading and running them
+   - See below for the help output
+
+
+ - The runtests command, via methods in the JSSTestHelper module, handles connecting to servers.
+   - it takes options to define connection parameters.
+     - At the moment they are limited to user, hostname and port, but will be expanded eventually
+   - it prompts for passwords as needed
+   - it must be run on a Mac! It stores connection parameters in your keychain.
+   - it uses connection parameters from your keychain if they are present. meaning after the first use,
+     it will connect to the same server as the same user with no commandline options.
+   - If any commandline options are different from whats in the keychain, the keychain will be updated,
+     prompting for new passwords if needed.
+
+-  The JSSTestHelper module also provides ways for tests to share data.
+
+ - The runtests command will run the spec files listed on the command line, or all of them if none are listed.
+ - The tests are run verbosely, so you can see what tests are being run.
+ - Some tests are interactive - they will ask you to make choices about what's happening.
+
+WARNING: **Be very careful about running these tests on your production JSS !!!**
+
+These tests create and delete objects in the JSS. While they _shouldn't_ hurt any of the existing data - we cannot make any guarantees that they won't hurt something you care about.
+
+As the license text for ruby-jss states:
+
+```
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the Apache License with the above modification is
+    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.
+```
+
+As a reminder, if you connect to the same server that's listed in your /etc/ruby-jss.conf, you'll be asked for confirmation before the tests are run.
+
+
+ ### The Spec Files
+
+ Each spec file defines one or more MiniTest::Spec's, each one being a 'describe SomeClass' block, containing methods and individual tests in 'it' blocks.
+
+ If you plan to write any tests, please read up on how to write MiniTest Specs.
+
+ However, here's some info that wasn't obvious when I first started, and makes life much easier when writing specs:
+
+ - the 'describe' blocks eventually become classes
+   - you can do anything inside them that you would do in a class definition.
+ - the 'it' blocks become methods in the class defined by the 'describe' block.
+ - the 'it' blocks are run one at a time, each in a separate instance of the class defined by the 'describe' block.
+ - by default, the 'it' blocks are run in a random order. See below if you need them to run in the defined order.
+
+ All of the above means that you can use constants, class methods, class-instance variables and instance methods in concert for processing and passing things between the individual tests.
+
+### Running tests in order
+
+The individual spec files are run in the order given on the command line. If none are given on the command line, all files are run in alphabetical order.
+
+If you define multiple 'describe' blocks in a file, they will be run in random order.
+
+The individual tests in a describe block are also run in random order, by default.
+
+If you need the tests to run in order within a 'describe' block, then define this class method somewhere inside it:
+
+       def self.test_order
+         :alpha
+       end
+
+The presence of that method will cause MiniTest to run them in the order defined.
+
+### Help output from 'runtests -H'
+
+
+```
+   Usage: runtests [options] [spec [spec ...]]
+
+   Runs one or more specification tests of ruby-jss.
+
+   The specifications are files in the directory:
+       /Users/chrisl/git/gemdev/ruby-jss/test/specs
+
+   The files must have a _spec.rb suffix, however you need not use the suffix when
+   listing tests to run on the command line, e.g. 'patch_source' will run
+   'patch_source_spec.rb'
+
+   If no specs files are listed on the command line, all will be run, in
+   alphabetical order.
+
+   By default, JSS connection settings are used from your /etc/ruby-jss.conf file
+   and/or ~/.ruby-jss.conf. Connection settings from the command line will be used
+   if provided.
+
+   WARNING: These tests create, modify, and delete objects in the JSS.
+     While no existing objects should be changed, * Be Careful * running them on
+     a production server.
+     If the server you're connecting to matches one defined in /etc/ruby-jss.conf
+     you will be asked for confirmation before proceding.
+
+   The first time you connect from this machine to a given server, you must provide
+   a username for the connection with --user, and will be prompted for the password.
+   Once authenticated, credentials for the server are saved in your keychain, and
+   future connections to that server will read the user & password from there.
+   If a different user is later specified for that server, you'll be prompted again
+   for a password, and the keychain will be updated.
+
+   Options
+     --server, -s <host>         the hostname for the JSS API connection
+     --port, -p <port>           the port for the API connection
+     --user, -u <user>           the API username for the connection
+                                   NOTE: must have permissions to perform the tests!
+     --db-server, -S <host>      the hostname for the JSS API connection
+     --db-port, -P <port>        the port for the API connectino
+     --db-user, -U <user>        the API username for the connection
+     --gem-dir, -g, -i <path>    the path from which to require ruby-jss
+                                   (sets GEM_HOME to this path before requiring)
+     --help, -h, -H              show this help
+```

data/test/bin/runtests

@@ -0,0 +1,290 @@
+#!/usr/bin/ruby
+
+### Copyright 2018 Pixar
+
+###
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###
+###    You may obtain a copy of the Apache License at
+###
+###        http://www.apache.org/licenses/LICENSE-2.0
+###
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+###
+###
+
+# Uses the MiniTest::Spec infrastructure to run one or tests of ruby-jss
+#
+# We do not use minitest/autorun, so that we have more control over which tests
+# are run and how. But the individual spec files are standard MiniTest::Spec
+# 'describe' blocks
+#
+# Those blocks become classes when the tests are run, and for each test,
+# an instance of the class is created.
+# As such, the interior of the blocks can be treated like class definitions,
+# defining constants, class methods, instance methods and so on.
+#
+# As well as that class-based infratructure, this tool includes a JSSTestHelper
+# module which defines usefule constants and helper methods, accessible from
+# anywhere via the module name.
+#
+
+require 'pathname'
+require 'getoptlong'
+require 'keychain'
+require 'minitest/spec'
+# require 'minitest/autorun' # DO NOT REQUIRE AUTORUN - we manually run each file below.
+
+# app
+class App
+
+  SPEC_SUFFIX = '_spec.rb'.freeze
+
+  # Server and port come from CLI opts or ruby-jss.conf
+  #
+  # User comes from CLI opt or keychain
+  #
+  # pw come from keychain, or is prompted and stored
+  # in keychain with user.
+  #
+  # TODO: support for other APIConnection options
+  #
+  OPTS = GetoptLong.new(
+    ['--server', '-s', GetoptLong::REQUIRED_ARGUMENT],
+    ['--port', '-p', GetoptLong::REQUIRED_ARGUMENT],
+    ['--user', '-u', GetoptLong::REQUIRED_ARGUMENT],
+    ['--db-server', '-S', GetoptLong::REQUIRED_ARGUMENT],
+    ['--db-port', '-P', GetoptLong::REQUIRED_ARGUMENT],
+    ['--db-user', '-U', GetoptLong::REQUIRED_ARGUMENT],
+    ['--gem-dir', '-g', '-i', GetoptLong::REQUIRED_ARGUMENT],
+    ['--saved-data', '-d', GetoptLong::NO_ARGUMENT],
+    ['--help', '-h', '-H', GetoptLong::NO_ARGUMENT]
+  )
+
+  # Setup
+  def initialize
+    load_ruby_jss
+    parse_opts
+
+    @bindir = Pathname.new File.dirname(__FILE__)
+    @appdir = @bindir.parent
+    @libdir = @appdir + 'lib'
+    @specdir = @appdir + 'specs'
+
+    @tests_to_run = ARGV.dup
+    @tests_to_run = @specdir.children.map { |c| c.basename.to_s }.sort if @tests_to_run .empty?
+
+    @minitest_opts = ['--verbose']
+
+    helper_module = @libdir + 'testhelper.rb'
+    load helper_module.to_s
+  end # init
+
+  # Load the gem
+  def load_ruby_jss
+    if @custom_gem_dir
+      ENV['GEM_HOME'] = @custom_gem_dir
+      ENV['GEM_PATH'] = "#{@custom_gem_dir}:#{ENV['GEM_PATH']}"
+      Gem.paths = ENV
+    end
+    require 'ruby-jss'
+  end
+
+  # Parse ARGV
+  def parse_opts
+    OPTS.each do |opt, arg|
+      case opt
+      when '--server'
+        @api_server = arg
+      when '--user'
+        @api_user = arg
+      when '--port'
+        @api_port = arg
+      when '--db-server'
+        @db_server = arg
+      when '--db-user'
+        @db_user = arg
+      when '--db-port'
+        @db_port = arg
+      when '--gem-dir'
+        @custom_gem_dir = arg
+      when '--saved-data'
+        @show_saved_data = true
+      when '--help'
+        @show_help = true
+      end # case
+    end # opts.each
+  end
+
+  # the default values
+  def apply_defaults
+    @api_server ||= JSS::CONFIG.api_server_name
+    @api_port ||= JSS::CONFIG.api_server_port
+    @db_server ||= JSS::CONFIG.db_server_name
+    @db_port ||= JSS::CONFIG.db_server_port
+  end
+
+  def run
+    return if show_help
+    return if show_saved_data
+    connect_to_servers
+    return unless prod_server_confirmed_if_needed?
+    run_tests
+  end
+
+  # if @api_server == matches the one in /etc/ruby-jss.conf
+  # get confirmation before running tests on the production server.
+  # If a local ~/.ruby-jss.conf defines a diferent server,
+  # or a different server if given with --server, no confirmation is needed
+  def prod_server_confirmed_if_needed?
+    conf = Pathname.new '/etc/ruby-jss.conf'
+    return true unless conf.file?
+
+    prod_server_line = conf.readlines.select { |l| l.start_with? 'api_server_name' }.first
+    return true unless prod_server_line
+
+    prod_server = prod_server_line.chomp.split(': ').last
+    return true unless prod_server == @api_server
+
+    print "Really run the tests on the production server '#{prod_server}'? (y/n): "
+    doit = gets.chomp
+    doit == 'y'
+  end
+
+  def connect_to_servers
+    jss_keychain_creds = JSSTestHelper::Auth.rw_credentials_from_keychain(:jss)
+    if jss_keychain_creds
+      @api_server ||= jss_keychain_creds[:server]
+      @api_port ||= jss_keychain_creds[:port]
+      @api_user ||= jss_keychain_creds[:user]
+      pw = jss_keychain_creds[:pw]
+    else
+      apply_defaults
+      raise 'Please specify a server with --server' unless @api_server
+      raise 'Please specify a user with --user' unless @api_user
+      pw = 'nopw'
+    end
+
+    JSSTestHelper::Auth.connect_to_api(server: @api_server, port: @api_port, user: @api_user, pw: pw )
+  end
+
+  def run_tests
+    JSSTestHelper.say "Starting tests of ruby-jss v #{JSS::VERSION}"
+    JSSTestHelper.say "API Connection: #{@api_user}@#{@api_server}:#{@api_port} running Jamf Pro #{JSS.api.server.version}"
+
+    base_runnables = MiniTest::Runnable.runnables.dup
+
+    @tests_to_run.each do |t|
+      t += SPEC_SUFFIX unless t.end_with? SPEC_SUFFIX
+      specfile = @specdir + t
+
+      puts
+
+      if specfile.file?
+        JSSTestHelper.say "Running test #{specfile.basename}: "
+        load specfile.to_s
+
+        MiniTest.run @minitest_opts.dup
+
+        # clear this files specs from the run list..
+        MiniTest::Runnable.runnables.select! { |r| base_runnables.include? r }
+        puts
+      else
+        JSSTestHelper.say "Skipping unknown test #{specfile.basename}"
+      end # if
+
+    end # each
+  end # run tests
+
+  # display saved keychain data if asked
+  def show_saved_data
+    return false unless @show_saved_data
+    jss_keychain_creds = JSSTestHelper::Auth.rw_credentials_from_keychain(:jss)
+    msg =
+      if jss_keychain_creds
+        "JSS API Tests will run as user '#{jss_keychain_creds[:user]}' on server '#{jss_keychain_creds[:server]}', port #{jss_keychain_creds[:port]}"
+      else
+        'No JSS API credentials saved, please use --server, --user and --port (if needed)'
+      end
+    puts msg
+    true
+  end
+
+  # display help if asked
+  def show_help
+    return false unless @show_help
+    puts <<-USAGEBLURB
+Usage: #{File.basename __FILE__} [options] [spec [spec ...]]
+
+Runs one or more specification tests of ruby-jss.
+
+The specifications are files in the directory:
+    #{@specdir}
+
+The files must have a _spec.rb suffix, however you need not use the suffix when
+listing tests to run on the command line, e.g. 'patch_source' will run
+'patch_source_spec.rb'
+
+If no specs files are listed on the command line, all will be run, in
+alphabetical order.
+
+By default, JSS connection settings are used from your /etc/ruby-jss.conf file
+and/or ~/.ruby-jss.conf. Connection settings from the command line will be used
+if provided.
+
+WARNING: These tests create, modify, and delete objects in the JSS.
+  While no existing objects should be changed, * Be Careful * running them on
+  a production server.
+  If the server you're connecting to matches one defined in /etc/ruby-jss.conf
+  you will be asked for confirmation before proceding.
+
+The first time you connect from this machine to a given server, you must provide
+a username for the connection with --user, and will be prompted for the password.
+Once authenticated, credentials for the server are saved in your keychain, and
+future connections to that server will read the user & password from there.
+If a different user is later specified for that server, you'll be prompted again
+for a password, and the keychain will be updated.
+
+Options
+  --server, -s <host>         the hostname for the JSS API connection
+  --port, -p <port>           the port for the API connection
+  --user, -u <user>           the API username for the connection
+                                NOTE: must have permissions to perform the tests!
+  --db-server, -S <host>      the hostname for the JSS API connection
+  --db-port, -P <port>        the port for the API connectino
+  --db-user, -U <user>        the API username for the connection
+  --gem-dir, -g, -i <path>    the path from which to require ruby-jss
+                                (sets GEM_HOME to this path before requiring)
+  --saved-data, -d            show the connection data saved in the keychain,
+                                if any. (no tests run, password not shown)
+  --help, -h, -H              show this help
+    USAGEBLURB
+    true
+  end # show_help
+
+end # class app
+
+#################  The main block  ########################
+if $PROGRAM_NAME == __FILE__
+  begin
+    app = App.new
+    app.run
+    exit 0
+  rescue => the_exception
+    warn "An error occurred: #{the_exception.message}"
+    warn the_exception.backtrace
+    exit 1
+  end # begin
+end # if $0 == __FILE__