Merge remote-tracking branch 'origin/kpaulisse-release-0-7' into kpaulisse-catalog-object-api

Author: Kevin Paulisse

README.md

@@ -51,6 +51,7 @@ The example above reflects the changes in the Puppet catalog from switching an u
 - [Requirements](/doc/requirements.md)
 - [Limitations](/doc/limitations.md)
 - [List of all command line options](/doc/optionsref.md)
+- [API](/doc/dev/api.md)
 
 ### Project
 

bin/octocatalog-diff

@@ -20,54 +20,13 @@ end
 
 config_test = ARGV.include?('--config-test')
 
-paths = [
-  ENV['OCTOCATALOG_DIFF_CONFIG_FILE'],
-  File.join(Dir.pwd, '.octocatalog-diff.cfg.rb'),
-  File.join(ENV['HOME'], '.octocatalog-diff.cfg.rb'),
-  '/opt/puppetlabs/octocatalog-diff/octocatalog-diff.cfg.rb',
-  '/usr/local/etc/octocatalog-diff.cfg.rb',
-  '/etc/octocatalog-diff.cfg.rb'
-]
+logger = Logger.new(STDERR)
+logger.level = Logger::DEBUG if config_test
 
-cfgfile = nil
-
-paths.each do |path|
-  next if path.nil?
-  puts "Looking for config in: #{path}" if config_test
-  next unless File.file?(path)
-  begin
-    cfgfile = path
-    puts "Loading config: #{path}" if config_test
-    require path
-  rescue => exc
-    STDERR.puts "#{exc.class} error with #{path}: #{exc.message}\n#{exc.backtrace}"
-    exit 1
-  end
-  break
-end
-
-options = {}
-
-if cfgfile
-  begin
-    options = OctocatalogDiff::Config.config
-  rescue => exc
-    STDERR.puts "#{exc.class} error with #{cfgfile}: #{exc.message}\n#{exc.backtrace}"
-    exit 1
-  end
-  unless options.is_a?(Hash)
-    STDERR.puts "Configuration must be Hash not #{options.class}!"
-    exit 1
-  end
-  if config_test
-    options.each do |key, val|
-      puts ":#{key} => (#{val.class}) #{val.inspect}"
-    end
-    exit 0
-  end
-elsif config_test
-  STDERR.puts 'No configuration files found'
-  exit 1
+options = OctocatalogDiff::API::V1.config(logger: logger, test: config_test)
+if config_test
+  logger.info 'Exiting now because --config-test was specified'
+  exit(0)
 end
 
 argv = ARGV.dup

doc/advanced-filter.md

@@ -9,7 +9,7 @@ Please note that there are other options to ignore specified diffs, including:
 
 Here is the list of available filters and an explanation of each:
 
-- [YAML](#YAML) - Ignore whitespace/comment differences if YAML parses to the same object
+- [YAML](/doc/advanced-filter.md#yaml) - Ignore whitespace/comment differences if YAML parses to the same object
 
 ## YAML
 

doc/dev/api.md

@@ -0,0 +1,5 @@
+# octocatalog-diff API documentation
+
+The octocatalog-diff API allows developers to construct and work with certain octocatalog-diff internals in their own projects.
+
+The current API version is [API v1](/doc/dev/api/v1.md), which is available as of octocatalog-diff version 0.7.

doc/dev/api/v1.md

@@ -0,0 +1,19 @@
+# octocatalog-diff v1 API documentation
+
+## catalog
+
+`catalog` allows you to build a catalog using the octocatalog-diff compiler or to obtain a catalog from a Puppet server.
+
+[Read more about `catalog`](/doc/dev/api/v1/catalog.md)
+
+## catalog-diff
+
+`catalog-diff` allows you compare two catalogs and obtain the differences between them. Catalogs can be built if necessary.
+
+[Read more about `catalog-diff`](/doc/dev/api/v1/catalog-diff.md)
+
+## config
+
+`config` allows you read and parse an [octocatalog-diff configuration file](/doc/configuration.md).
+
+[Read more about `config`](/doc/dev/api/v1/config)

doc/dev/api/v1/catalog-diff.md

@@ -0,0 +1,21 @@
+# octocatalog-diff v1 API documentation: catalog-diff
+
+## Overview
+
+`catalog-diff` allows you compare two catalogs and obtain the differences between them. Catalogs can be built if necessary.
+
+This is analogous to using the default arguments with the octocatalog-diff command-line script.
+
+```
+catalog_diff_result = OctocatalogDiff::API::V1.catalog_diff(
+
+)
+```
+
+## Options
+
+**NOTE**: Additional options as described in the [options reference](/doc/optionsref.md) may also have an effect on catalog difference generation.
+
+## Return value
+
+## Exceptions

doc/dev/api/v1/catalog.md

@@ -0,0 +1,22 @@
+# octocatalog-diff v1 API documentation: catalog
+
+## Overview
+
+`catalog` returns an `OctocatalogDiff::Catalog` object built with the octocatalog-diff compiler, obtained from a Puppet server, or read in from a file. This is analogous to using the `--catalog-only` option with the octocatalog-diff command-line script.
+
+```
+catalog_obj = OctocatalogDiff::API::V1.catalog(
+
+)
+```
+
+## Options
+
+
+**NOTE**: Additional options as described in the [options reference](/doc/optionsref.md) may also have an effect on catalog generation.
+
+## Return value
+
+The return value is an [`OctocatalogDiff::Catalog`](/doc/dev/api/v1/octocatalogdiff-catalog.md) object.
+
+## Exceptions

doc/dev/api/v1/config.md

@@ -0,0 +1,37 @@
+# octocatalog-diff v1 API documentation: config
+
+## Overview
+
+`config` reads and parses an [octocatalog-diff configuration file](/doc/configuration.md).
+
+```
+options = OctocatalogDiff::API::V1.config(
+  filename: "String",
+  logger: Logger,
+  test: <true|false>
+)
+```
+
+## Options
+
+- **`:filename`** (String, optional): Full path to configuration file to read. If not provided, the configuration file will be searched as described in [Configuration](/doc/configuration.md).
+
+- **`:logger`** (Logger, optional): Logger object. If provided, debug messages and fatal errors will be logged to this object.
+
+- **`:test`** (Boolean, optional): Test mode, defaults to false. If true, the value of the configuration settings will be logged to the logger (with priority DEBUG) and an exception will be raised if the configuration file cannot be located.
+
+## Return value
+
+If the configuration file is located and valid, the return value is a Hash consisting of the options defined in the configuration file.
+
+If the configuration file cannot be found, the return value is an empty Hash (`{}`). Except, with `:test => true`, an exception will be raised.
+
+## Exceptions
+
+- `OctocatalogDiff::Errors::ConfigurationFileContentError`
+
+  Raised if the configuration file could not be evaluated. A more specific error message will help identify the cause. Possible causes include the file not being valid ruby, the file not containing the expected structure or methods, or the method returning something other than a Hash.
+
+- `OctocatalogDiff::Errors::ConfigurationFileNotFoundError`
+
+  Raised if the configuration file could not be found, *and* `:test => true` was supplied. (Note, if no configuration file is found, but `:test => false`, no error is raised, and `{}` is returned.)

doc/dev/api/v1/octocatalogdiff-catalog.md

@@ -0,0 +1,11 @@
+# octocatalog-diff v1 API documentation: OctocatalogDiff::Catalog
+
+## Overview
+
+`OctocatalogDiff::Catalog` is a class that represents a compiled catalog.
+
+This object is the return value from the [`catalog`](/doc/dev/api/v1/catalog.md) API call.
+
+## Methods
+
+## Exceptions

doc/optionsref.md

@@ -436,7 +436,7 @@ on which this is running. (<a href="../lib/octocatalog-diff/cli/options/facts_te
     <td valign=top>
       Specify one or more filters to apply to the results of the catalog difference.
 For a list of available filters and further explanation, please refer to
-[Filtering results](/doc/advanced-filter.md). (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/filters.rb">filters.rb</a>)
+<a href="advanced-filter.md">Filtering results</a>. (<a href="../lib/octocatalog-diff/cli/options/filters.rb">filters.rb</a>)
     </td>
   </tr>