[Pkg-puppet-devel] [facter] 94/352: Document Facter API with YARD
Stig Sandbeck Mathisen
ssm at debian.org
Sun Apr 6 22:21:35 UTC 2014
This is an automated email from the git hooks/post-receive script.
ssm pushed a commit to branch master
in repository facter.
commit 4ce8f7d543f2b1f988103d4098a74a106e704ebe
Author: Patrick Carlisle <patrick at puppetlabs.com>
Date: Mon Dec 3 17:44:45 2012 -0800
Document Facter API with YARD
This adds YARD documentation with `@api public` tags to the public API for
facter. This is a first pass, so it's probably missing some things that should
be considered public.
Conflicts:
lib/facter/util/fact.rb
lib/facter/util/resolution.rb
---
.yardopts | 5 +
README.md | 3 +-
lib/facter.rb | 230 ++++++++++++++++++++++++++++++--------
lib/facter/processor.rb | 5 +-
lib/facter/util/collection.rb | 5 +-
lib/facter/util/fact.rb | 51 ++++++---
lib/facter/util/file_read.rb | 11 +-
lib/facter/util/nothing_loader.rb | 9 +-
lib/facter/util/resolution.rb | 179 ++++++++++++++++++++++++-----
lib/facter/util/values.rb | 2 +-
lib/facter/version.rb | 79 ++++++-------
spec/unit/facter_spec.rb | 9 +-
12 files changed, 438 insertions(+), 150 deletions(-)
diff --git a/.yardopts b/.yardopts
index 0036282..a552a9b 100644
--- a/.yardopts
+++ b/.yardopts
@@ -3,4 +3,9 @@
--verbose
--markup markdown
--readme README_DEVELOPER.md
+--tag status
+--transitive-tag status
+--tag comment
+--hide-tag comment
+--no-transitive-tag api
lib/**/*.rb
diff --git a/README.md b/README.md
index 5bed36e..a4aa40b 100644
--- a/README.md
+++ b/README.md
@@ -3,8 +3,7 @@ Facter
This package is largely meant to be a library for collecting facts about your
system. These facts are mostly strings (i.e., not numbers), and are things
-like the output of `uname`, public ssh and cfengine keys, the number of
-processors, etc.
+like the output of `uname`, public ssh keys, the number of processors, etc.
See `bin/facter` for an example of the interface.
diff --git a/lib/facter.rb b/lib/facter.rb
index 760dfac..eff1665 100644
--- a/lib/facter.rb
+++ b/lib/facter.rb
@@ -16,8 +16,20 @@
require 'facter/version'
+# Functions as a hash of 'facts' about your system system, such as MAC
+# address, IP address, architecture, etc.
+#
+# @example Retrieve a fact
+# puts Facter['operatingsystem'].value
+#
+# @example Retrieve all facts
+# Facter.to_hash
+# => { "kernel"=>"Linux", "uptime_days"=>0, "ipaddress"=>"10.0.0.1" }
+#
+# @api public
module Facter
- # This is just so the other classes have the constant.
+ # Most core functionality of facter is implemented in `Facter::Util`.
+ # @api public
module Util; end
require 'facter/util/fact'
@@ -27,28 +39,25 @@ module Facter
include Comparable
include Enumerable
- # = Facter
- # Functions as a hash of 'facts' you might care about about your
- # system, such as mac address, IP address, Video card, etc.
- # returns them dynamically
-
- # == Synopsis
- #
- # Generally, treat <tt>Facter</tt> as a hash:
- # == Example
- # require 'facter'
- # puts Facter['operatingsystem']
- #
-
+ # @api private
GREEN = "[0;32m"
+ # @api private
RESET = "[0m"
+ # @api private
@@debug = 0
+ # @api private
@@timing = 0
+ # @api private
@@messages = {}
+ # @api private
@@debug_messages = {}
# module methods
+ # Accessor for the collection object which holds all the facts
+ # @return [Facter::Util::Collection] the collection of facts
+ #
+ # @api private
def self.collection
unless defined?(@collection) and @collection
@collection = Facter::Util::Collection.new(
@@ -58,7 +67,10 @@ module Facter
@collection
end
- # Add some debugging
+ # Prints a debug message if debugging is turned on
+ #
+ # @param string [String] the debug message
+ # @return [void]
def self.debug(string)
if string.nil?
return
@@ -68,7 +80,13 @@ module Facter
end
end
- # Debug once.
+ # Prints a debug message only once.
+ #
+ # @note Uniqueness is based on the string, not the specific location
+ # of the method call.
+ #
+ # @param msg [String] the debug message
+ # @return [void]
def self.debugonce(msg)
if msg and not msg.empty? and @@debug_messages[msg].nil?
@@debug_messages[msg] = true
@@ -76,21 +94,31 @@ module Facter
end
end
+ # Returns whether debugging output is turned on
def self.debugging?
@@debug != 0
end
- # show the timing information
+ # Prints a timing
+ #
+ # @param string [String] the time to print
+ # @return [void]
+ #
+ # @api private
def self.show_time(string)
puts "#{GREEN}#{string}#{RESET}" if string and Facter.timing?
end
+ # Returns whether timing output is turned on
+ #
+ # @api private
def self.timing?
@@timing != 0
end
- # Facter.json? is meant to provide a lightweight way to check if the JSON
- # "feature" is available.
+ # Returns whether the JSON "feature" is available.
+ #
+ # @api private
def self.json?
begin
require 'json'
@@ -100,34 +128,94 @@ module Facter
end
end
- # Return a fact object by name. If you use this, you still have to call
- # 'value' on it to retrieve the actual value.
+ # Returns a fact object by name. If you use this, you still have to
+ # call {Facter::Util::Fact#value `value`} on it to retrieve the actual
+ # value.
+ #
+ # @param name [String] the name of the fact
+ #
+ # @return [Facter::Util::Fact, nil] The fact object, or nil if no fact
+ # is found.
+ #
+ # @api public
def self.[](name)
collection.fact(name)
end
- class << self
- [:fact, :flush, :list, :value].each do |method|
- define_method(method) do |*args|
- collection.send(method, *args)
- end
- end
+ # (see [])
+ def self.fact(name)
+ collection.fact(name)
+ end
- [:list, :to_hash].each do |method|
- define_method(method) do |*args|
- collection.load_all
- collection.send(method, *args)
- end
- end
+ # Flushes cached values for all facts. This does not cause code to be
+ # reloaded; it only clears the cached results.
+ #
+ # @return [void]
+ #
+ # @api public
+ def self.flush
+ collection.flush
+ end
+
+ # Lists all fact names
+ #
+ # @return [Array<String>] array of fact names
+ #
+ # @api public
+ def self.list
+ collection.list
end
+ # Gets the value for a fact. Returns `nil` if no such fact exists.
+ #
+ # @param name [String] the fact name
+ # @return [Object, nil] the value of the fact, or nil if no fact is
+ # found
+ #
+ # @api public
+ def self.value(name)
+ collection.value(name)
+ end
- # Add a resolution mechanism for a named fact. This does not distinguish
- # between adding a new fact and adding a new way to resolve a fact.
+ # Gets a hash mapping fact names to their values
+ #
+ # @return [Hash{String => Object}] the hash of fact names and values
+ #
+ # @api public
+ def self.to_hash
+ collection.load_all
+ collection.to_hash
+ end
+
+ # Adds a {Facter::Util::Resolution resolution} mechanism for a named
+ # fact. This does not distinguish between adding a new fact and adding
+ # a new way to resolve a fact.
+ #
+ # @overload add(name, options = {}, { || ... })
+ # @param name [String] the fact name
+ # @param options [Hash] optional parameters for the fact - attributes
+ # of {Facter::Util::Fact} and {Facter::Util::Resolution} can be
+ # supplied here
+ # @option options [Integer] :timeout set the
+ # {Facter::Util::Resolution#timeout timeout} for this resolution
+ # @param block [Proc] a block defining a fact resolution
+ #
+ # @return [Facter::Util::Fact] the fact object, which includes any previously
+ # defined resolutions
+ #
+ # @api public
def self.add(name, options = {}, &block)
collection.add(name, options, &block)
end
+ # Iterates over fact names and values
+ #
+ # @yieldparam [String] name the fact name
+ # @yieldparam [String] value the current value of the fact
+ #
+ # @return [void]
+ #
+ # @api public
def self.each
# Make sure all facts are loaded.
collection.load_all
@@ -140,6 +228,8 @@ module Facter
class << self
# Allow users to call fact names directly on the Facter class,
# either retrieving the value or comparing it to an existing value.
+ #
+ # @api private
def method_missing(name, *args)
question = false
if name.to_s =~ /\?$/
@@ -168,19 +258,30 @@ module Facter
end
end
- # Clear all facts. Mostly used for testing.
+ # Clears all cached values and removes all facts from memory.
+ #
+ # @return [void]
+ #
+ # @api public
def self.clear
Facter.flush
Facter.reset
end
- # Clear all messages. Used only in testing. Can't add to self.clear
- # because we don't want to warn multiple times for items that are warnonce'd
+ # Clears the seen state of warning messages. See {warnonce}.
+ #
+ # @return [void]
+ #
+ # @api private
def self.clear_messages
@@messages.clear
end
- # Set debugging on or off.
+ # Sets debugging on or off.
+ #
+ # @return [void]
+ #
+ # @api private
def self.debugging(bit)
if bit
case bit
@@ -206,7 +307,11 @@ module Facter
end
end
- # Set timing on or off.
+ # Sets whether timing messages are displayed.
+ #
+ # @return [void]
+ #
+ # @api private
def self.timing(bit)
if bit
case bit
@@ -223,6 +328,12 @@ module Facter
end
end
+ # Prints a warning message. The message is only printed if debugging
+ # is enabled.
+ #
+ # @param msg [String] the warning message to be printed
+ #
+ # @return [void]
def self.warn(msg)
if Facter.debugging? and msg and not msg.empty?
msg = [msg] unless msg.respond_to? :each
@@ -230,7 +341,16 @@ module Facter
end
end
- # Warn once.
+ # Prints a warning message only once per process. Each unique string
+ # is printed once.
+ #
+ # @note Unlike {warn} the message will be printed even if debugging is
+ # not turned on. This behavior is likely to change and should not be
+ # relied on.
+ #
+ # @param msg [String] the warning message to be printed
+ #
+ # @return [void]
def self.warnonce(msg)
if msg and not msg.empty? and @@messages[msg].nil?
@@messages[msg] = true
@@ -238,24 +358,44 @@ module Facter
end
end
- # Remove them all.
+ # Removes all facts from memory. Use this when the fact code has
+ # changed on disk and needs to be reloaded.
+ #
+ # @return [void]
+ #
+ # @api public
def self.reset
@collection = nil
end
- # Load all of the default facts, and then everything from disk.
+ # Loads all facts.
+ #
+ # @return [void]
+ #
+ # @api public
def self.loadfacts
collection.load_all
end
@search_path = []
- # Register a directory to search through.
+ # Registers directories to be searched for facts. Relative paths will
+ # be interpreted in the current working directory.
+ #
+ # @param dirs [String] directories to search
+ #
+ # @return [void]
+ #
+ # @api public
def self.search(*dirs)
@search_path += dirs
end
- # Return our registered search directories.
+ # Returns the registered search directories.
+ #
+ # @return [Array<String>] An array of the directories searched
+ #
+ # @api public
def self.search_path
@search_path.dup
end
diff --git a/lib/facter/processor.rb b/lib/facter/processor.rb
index 1d11d07..b79af2d 100644
--- a/lib/facter/processor.rb
+++ b/lib/facter/processor.rb
@@ -22,8 +22,9 @@
require 'thread'
require 'facter/util/processor'
-## We have to enumerate these outside a Facter.add block to get the processorN descriptions iteratively
-## (but we need them inside the Facter.add block above for tests on processorcount to work)
+# We have to enumerate these outside a Facter.add block to get the processorN
+# descriptions iteratively (but we need them inside the Facter.add block above
+# for tests on processorcount to work)
processor_list = case Facter::Util::Processor.kernel_fact_value
when "AIX"
Facter::Util::Processor.aix_processor_list
diff --git a/lib/facter/util/collection.rb b/lib/facter/util/collection.rb
index 63233cb..120dd1c 100644
--- a/lib/facter/util/collection.rb
+++ b/lib/facter/util/collection.rb
@@ -4,6 +4,8 @@ require 'facter/util/loader'
# Manage which facts exist and how we access them. Largely just a wrapper
# around a hash of facts.
+#
+# @api private
class Facter::Util::Collection
def initialize(internal_loader, external_loader)
@@ -12,8 +14,7 @@ class Facter::Util::Collection
@external_loader = external_loader
end
- # Return a fact object by name. If you use this, you still have to call
- # 'value' on it to retrieve the actual value.
+ # Return a fact object by name.
def [](name)
value(name)
end
diff --git a/lib/facter/util/fact.rb b/lib/facter/util/fact.rb
index 3ada605..f7fcc1a 100644
--- a/lib/facter/util/fact.rb
+++ b/lib/facter/util/fact.rb
@@ -1,12 +1,28 @@
require 'facter'
require 'facter/util/resolution'
+# This class represents a fact. Each fact has a name and multiple
+# {Facter::Util::Resolution resolutions}.
+#
+# Create facts using {Facter.add}
+#
+# @api public
class Facter::Util::Fact
- TIMEOUT = 5
-
- attr_accessor :name, :ldapname
-
- # Create a new fact, with no resolution mechanisms.
+ # The name of the fact
+ # @return [String]
+ attr_accessor :name
+
+ # @return [String]
+ # @deprecated
+ attr_accessor :ldapname
+
+ # Creates a new fact, with no resolution mechanisms. See {Facter.add}
+ # for the public API for creating facts.
+ # @param name [String] the fact name
+ # @param options [Hash] optional parameters
+ # @option options [String] :ldapname set the ldapname property on the fact
+ #
+ # @api private
def initialize(name, options = {})
@name = name.to_s.downcase.intern
@@ -28,8 +44,13 @@ class Facter::Util::Fact
@value = nil
end
- # Add a new resolution mechanism. This requires a block, which will then
- # be evaluated in the context of the new mechanism.
+ # Adds a new {Facter::Util::Resolution resolution}. This requires a
+ # block, which will then be evaluated in the context of the new
+ # resolution.
+ #
+ # @return [void]
+ #
+ # @api private
def add(value = nil, &block)
begin
resolve = Facter::Util::Resolution.new(@name)
@@ -44,17 +65,21 @@ class Facter::Util::Fact
end
end
- ##
- # Flush any cached values. If the resolver has a callback block defined
- # using the on_flush DSL method, then invoke that block by sending a message
- # to Resolution#flush.
+ # Flushs any cached values.
+ #
+ # @return [void]
+ #
+ # @api private
def flush
@resolves.each { |r| r.flush }
@value = nil
end
- # Return the value for a given fact. Searches through all of the mechanisms
- # and returns either the first value or nil.
+ # Returns the value for this fact. This searches all resolutions by
+ # suitability and weight (see {Facter::Util::Resolution}). If no
+ # suitable resolution is found, it returns nil.
+ #
+ # @api public
def value
return @value if @value
diff --git a/lib/facter/util/file_read.rb b/lib/facter/util/file_read.rb
index 82404a3..2b911ac 100644
--- a/lib/facter/util/file_read.rb
+++ b/lib/facter/util/file_read.rb
@@ -1,6 +1,6 @@
module Facter
module Util
-##
+
# {Facter::Util::FileRead} is a utility module intended to provide easily
# mockable methods that delegate to simple file read methods. The intent is to
# avoid the need to execute the `cat` system command or `File.read` directly in
@@ -11,16 +11,17 @@ module Util
#
# @api public
module FileRead
- ##
# read returns the raw content of a file as a string. If the file does not
# exist, or the process does not have permission to read the file then nil is
# returned.
#
# @api public
#
- # @return [String] the raw contents of the file at {path} or {nil} if the
- # file cannot be read because it does not exist or the process does not have
- # permission to read the file.
+ # @param path [String] the path to be read
+ #
+ # @return [String, nil] the raw contents of the file or `nil` if the
+ # file cannot be read because it does not exist or the process does not have
+ # permission to read the file.
def self.read(path)
File.read(path)
rescue Errno::ENOENT, Errno::EACCES => detail
diff --git a/lib/facter/util/nothing_loader.rb b/lib/facter/util/nothing_loader.rb
index 6e337c3..e700aa1 100644
--- a/lib/facter/util/nothing_loader.rb
+++ b/lib/facter/util/nothing_loader.rb
@@ -1,13 +1,10 @@
-# An external fact loader that doesn't load anything
-
-# This makes it possible to disable loading
-# of external facts
-
module Facter
module Util
+ # An external fact loader that doesn't load anything
+ # This makes it possible to disable loading
+ # of external facts
class NothingLoader
-
def load(collection)
end
end
diff --git a/lib/facter/util/resolution.rb b/lib/facter/util/resolution.rb
index a19b81a..3003e66 100644
--- a/lib/facter/util/resolution.rb
+++ b/lib/facter/util/resolution.rb
@@ -1,22 +1,39 @@
-# An actual fact resolution mechanism. These are largely just chunks of
-# code, with optional confinements restricting the mechanisms to only working on
-# specific systems. Note that the confinements are always ANDed, so any
-# confinements specified must all be true for the resolution to be
-# suitable.
require 'facter/util/confine'
require 'facter/util/config'
require 'timeout'
+# This represents a fact resolution. A resolution is a concrete
+# implementation of a fact. A single fact can have many resolutions and
+# the correct resolution will be chosen at runtime. Each time
+# {Facter.add} is called, a new resolution is created and added to the
+# set of resolutions for the fact named in the call. Each resolution
+# has a {#has_weight weight}, which defines its priority over other
+# resolutions, and a set of {#confine _confinements_}, which defines the
+# conditions under which it will be chosen. All confinements must be
+# satisfied for a fact to be considered _suitable_.
+#
+# @api public
class Facter::Util::Resolution
- attr_accessor :interpreter, :code, :name, :timeout
+ # The timeout, in seconds, for evaluating this resolution. The default
+ # is 0 which is equivalent to no timeout. This can be set using the
+ # options hash argument to {Facter.add}.
+ # @return [Integer]
+ # @api public
+ attr_accessor :timeout
+
+ # @api private
+ attr_accessor :interpreter, :code, :name
attr_writer :value, :weight
INTERPRETER = Facter::Util::Config.is_windows? ? "cmd.exe" : "/bin/sh"
# Returns the locations to be searched when looking for a binary. This
# is currently determined by the +PATH+ environment variable plus
- # <tt>/sbin</tt> and <tt>/usr/sbin</tt> when run on unix
+ # `/sbin` and `/usr/sbin` when run on unix
+ #
+ # @return [Array<String>] the paths to be searched for binaries
+ # @api private
def self.search_paths
if Facter::Util::Config.is_windows?
ENV['PATH'].split(File::PATH_SEPARATOR)
@@ -28,12 +45,18 @@ class Facter::Util::Resolution
end
end
- # Determine the full path to a binary. If the supplied filename does not
+ # Determines the full path to a binary. If the supplied filename does not
# already describe an absolute path then different locations (determined
- # by <tt>self.search_paths</tt>) will be searched for a match.
+ # by {search_paths}) will be searched for a match.
#
# Returns nil if no matching executable can be found otherwise returns
# the expanded pathname.
+ #
+ # @param bin [String] the executable to locate
+ # @return [String,nil] the full path to the executable or nil if not
+ # found
+ #
+ # @api public
def self.which(bin)
if absolute_path?(bin)
return bin if File.executable?(bin)
@@ -70,6 +93,9 @@ class Facter::Util::Resolution
# Determine in a platform-specific way whether a path is absolute. This
# defaults to the local platform if none is specified.
+ #
+ # @param path [String] the path to check
+ # @param platform [:posix,:windows,nil] the platform logic to use
def self.absolute_path?(path, platform=nil)
# Escape once for the string literal, and once for the regex.
slash = '[\\\\/]'
@@ -83,13 +109,14 @@ class Facter::Util::Resolution
!! (path =~ regexes[platform])
end
- # Expand the executable of a commandline to an absolute path. The executable
- # is the first word of the commandline. If the executable contains spaces,
- # it has be but in double quotes to be properly recognized.
+ # Given a command line, this returns the command line with the
+ # executable written as an absolute path. If the executable contains
+ # spaces, it has be but in double quotes to be properly recognized.
#
- # Returns the commandline with the expanded binary or nil if the binary
- # can't be found. If the path to the binary contains quotes, the whole binary
- # is put in quotes.
+ # @param command [String] the command line
+ #
+ # @return [String, nil] the command line with the executable's path
+ # expanded, or nil if the executable cannot be found.
def self.expand_command(command)
if match = /^"(.+?)"(?:\s+(.*))?/.match(command)
exe, arguments = match.captures
@@ -109,13 +136,18 @@ class Facter::Util::Resolution
end
end
+ # Overrides environment variables within a block of code. The
+ # specified values will be set for the duration of the block, after
+ # which the original values (if any) will be restored.
+ #
+ # @overload with_env(values, { || ... })
#
- # Call this method with a block of code for which you would like to temporarily modify
- # one or more environment variables; the specified values will be set for the duration
- # of your block, after which the original values (if any) will be restored.
+ # @param values [Hash<String=>String>] A hash of the environment
+ # variables to override
#
- # [values] a Hash containing the key/value pairs of any environment variables that you
- # would like to temporarily override
+ # @return [void]
+ #
+ # @api public
def self.with_env(values)
old = {}
values.each do |var, value|
@@ -143,18 +175,32 @@ class Facter::Util::Resolution
rv
end
- # Execute a program and return the output of that program.
+ # Executes a program and return the output of that program.
#
# Returns nil if the program can't be found, or if there is a problem
# executing the code.
#
+ # @param code [String] the program to run
+ # @return [String, nil] the output of the program or nil
+ #
+ # @api public
+ #
+ # @note Since Facter 1.5.8 this strips trailing newlines from the
+ # returned value. If a fact will be used by versions of Facter older
+ # than 1.5.8 then you should call chomp the returned string.
+ #
+ # @overload exec(code)
+ # @overload exec(code, interpreter = nil)
+ # @param [String] interpreter unused, only exists for backwards
+ # compatibility
+ # @deprecated
def self.exec(code, interpreter = nil)
Facter.warnonce "The interpreter parameter to 'exec' is deprecated and will be removed in a future version." if interpreter
## Set LANG to force i18n to C for the duration of this exec; this ensures that any code that parses the
## output of the command can expect it to be in a consistent / predictable format / locale
with_env "LANG" => "C" do
-
+
if expanded_code = expand_command(code)
# if we can find the binary, we'll run the command with the expanded path to the binary
code = expanded_code
@@ -164,7 +210,7 @@ class Facter::Util::Resolution
return nil unless Facter::Util::Config.is_windows?
return nil if absolute_path?(code)
end
-
+
out = nil
begin
@@ -177,7 +223,7 @@ class Facter::Util::Resolution
Facter.warn(detail)
return nil
end
-
+
if out == ""
return nil
else
@@ -186,18 +232,56 @@ class Facter::Util::Resolution
end
end
- # Add a new confine to the resolution mechanism.
+ # Sets the conditions for this resolution to be used. This takes a
+ # hash of fact names and values. Every fact must match the values
+ # given for that fact, otherwise this resolution will not be
+ # considered suitable. The values given for a fact can be an array, in
+ # which case the value of the fact must be in the array for it to
+ # match.
+ #
+ # @param confines [Hash{String => Object}] a hash of facts and the
+ # values they should have in order for this resolution to be
+ # used
+ #
+ # @example Confining to Linux
+ # Facter.add(:powerstates) do
+ # # This resolution only makes sense on linux systems
+ # confine :kernel => "Linux"
+ # setcode do
+ # Facter::Util::Resolution.exec('cat /sys/power/states')
+ # end
+ # end
+ #
+ # @return [void]
+ #
+ # @api public
def confine(confines)
confines.each do |fact, values|
@confines.push Facter::Util::Confine.new(fact, *values)
end
end
+ # Sets the weight of this resolution. If multiple suitable resolutions
+ # are found, the one with the highest weight will be used. If weight
+ # is not given, the number of confines set on a resolution will be
+ # used as its weight (so that the most specific resolution is used).
+ #
+ # @param weight [Integer] the weight of this resolution
+ #
+ # @return [void]
+ #
+ # @api public
def has_weight(weight)
@weight = weight
end
# Create a new resolution mechanism.
+ #
+ # @param name [String] The name of the resolution. This is mostly
+ # unused and resolutions are treated as anonymous.
+ # @return [void]
+ #
+ # @api private
def initialize(name)
@name = name
@confines = []
@@ -206,7 +290,13 @@ class Facter::Util::Resolution
@weight = nil
end
- # Return the importance of this resolution.
+ # Returns the importance of this resolution. If the weight was not
+ # given, the number of confines is used instead (so that a more
+ # specific resolution wins over a less specific one).
+ #
+ # @return [Integer] the weight of this resolution
+ #
+ # @api private
def weight
if @weight
@weight
@@ -215,14 +305,32 @@ class Facter::Util::Resolution
end
end
- # We need this as a getter for 'timeout', because some versions
- # of ruby seem to already have a 'timeout' method and we can't
- # seem to override the instance methods, somehow.
+ # (see #timeout)
+ # This is another name for {#timeout}.
+ # @comment We need this as a getter for 'timeout', because some versions
+ # of ruby seem to already have a 'timeout' method and we can't
+ # seem to override the instance methods, somehow.
def limit
@timeout
end
- # Set our code for returning a value.
+ # Sets the code block or external program that will be evaluated to
+ # get the value of the fact.
+ #
+ # @return [void]
+ #
+ # @overload setcode(string)
+ # Sets an external program to call to get the value of the resolution
+ # @param [String] string the external program to run to get the
+ # value
+ #
+ # @overload setcode(&block)
+ # Sets the resolution's value by evaluating a block at runtime
+ # @param [Proc] block The block to determine the resolution's value.
+ # This block is run when the fact is evaluated. Errors raised from
+ # inside the block are rescued and printed to stderr.
+ #
+ # @api public
def setcode(string = nil, interp = nil, &block)
Facter.warnonce "The interpreter parameter to 'setcode' is deprecated and will be removed in a future version." if interp
if string
@@ -267,17 +375,21 @@ class Facter::Util::Resolution
@on_flush_block.call if @on_flush_block
end
+ # @deprecated
def interpreter
Facter.warnonce "The 'Facter::Util::Resolution.interpreter' method is deprecated and will be removed in a future version."
@interpreter
end
+ # @deprecated
def interpreter=(interp)
Facter.warnonce "The 'Facter::Util::Resolution.interpreter=' method is deprecated and will be removed in a future version."
@interpreter = interp
end
# Is this resolution mechanism suitable on the system in question?
+ #
+ # @api private
def suitable?
unless defined? @suitable
@suitable = ! @confines.detect { |confine| ! confine.true? }
@@ -286,11 +398,16 @@ class Facter::Util::Resolution
return @suitable
end
+ # (see value)
+ # @deprecated
def to_s
return self.value()
end
- # How we get a value for our resolution mechanism.
+ # Evaluates the code block or external program to get the value of the
+ # fact.
+ #
+ # @api private
def value
return @value if @value
result = nil
diff --git a/lib/facter/util/values.rb b/lib/facter/util/values.rb
index a8a5bfa..d691987 100644
--- a/lib/facter/util/values.rb
+++ b/lib/facter/util/values.rb
@@ -1,6 +1,6 @@
-# A util module for facter containing helper methods
module Facter
module Util
+ # A util module for facter containing helper methods
module Values
module_function
diff --git a/lib/facter/version.rb b/lib/facter/version.rb
index ff609b8..784b65e 100644
--- a/lib/facter/version.rb
+++ b/lib/facter/version.rb
@@ -3,52 +3,51 @@ module Facter
FACTERVERSION = '1.7.4'
end
- ##
- # version is a public API method intended to always provide a fast and
- # lightweight way to determine the version of Facter.
+ # Returns the running version of Facter.
#
- # The intent is that software external to Facter be able to determine the
- # Facter version with no side-effects. The expected use is:
+ # @comment The intent is that software external to Facter be able to
+ # determine the Facter version with no side-effects. The expected
+ # use is:
#
# require 'facter/version'
# version = Facter.version
#
- # This function has the following ordering precedence. This precedence list
- # is designed to facilitate automated packaging tasks by simply writing to
- # the VERSION file in the same directory as this source file.
+ # This function has the following ordering precedence. This precedence list
+ # is designed to facilitate automated packaging tasks by simply writing to
+ # the VERSION file in the same directory as this source file.
#
- # 1. If a version has been explicitly assigned using the Facter.version=
- # method, return that version.
- # 2. If there is a VERSION file, read the contents, trim any
- # trailing whitespace, and return that version string.
- # 3. Return the value of the Facter::FACTERVERSION constant hard-coded into
- # the source code.
+ # 1. If a version has been explicitly assigned using the Facter.version=
+ # method, return that version.
+ # 2. If there is a VERSION file, read the contents, trim any
+ # trailing whitespace, and return that version string.
+ # 3. Return the value of the Facter::FACTERVERSION constant hard-coded into
+ # the source code.
#
- # If there is no VERSION file, the method must return the version string of
- # the nearest parent version that is an officially released version. That is
- # to say, if a branch named 3.1.x contains 25 patches on top of the most
- # recent official release of 3.1.1, then the version method must return the
- # string "3.1.1" if no "VERSION" file is present.
+ # If there is no VERSION file, the method must return the version string of
+ # the nearest parent version that is an officially released version. That is
+ # to say, if a branch named 3.1.x contains 25 patches on top of the most
+ # recent official release of 3.1.1, then the version method must return the
+ # string "3.1.1" if no "VERSION" file is present.
#
- # By design the version identifier is _not_ intended to vary during the life
- # a process. There is no guarantee provided that writing to the VERSION file
- # while a Puppet process is running will cause the version string to be
- # updated. On the contrary, the contents of the VERSION are cached to reduce
- # filesystem accesses.
+ # By design the version identifier is _not_ intended to vary during the life of
+ # a process. There is no guarantee provided that writing to the VERSION file
+ # while a Puppet process is running will cause the version string to be
+ # updated. On the contrary, the contents of the VERSION are cached to reduce
+ # filesystem accesses.
#
- # The VERSION file is intended to be used by package maintainers who may be
- # applying patches or otherwise changing the software version in a manner
- # that warrants a different software version identifier. The VERSION file is
- # intended to be managed and owned by the release process and packaging
- # related tasks, and as such should not reside in version control. The
- # FACTERVERSION constant is intended to be version controlled in history.
+ # The VERSION file is intended to be used by package maintainers who may be
+ # applying patches or otherwise changing the software version in a manner
+ # that warrants a different software version identifier. The VERSION file is
+ # intended to be managed and owned by the release process and packaging
+ # related tasks, and as such should not reside in version control. The
+ # FACTERVERSION constant is intended to be version controlled in history.
#
- # Ideally, this behavior will allow package maintainers to precisely specify
- # the version of the software they're packaging as in the following example:
+ # Ideally, this behavior will allow package maintainers to precisely specify
+ # the version of the software they're packaging as in the following example:
#
- # $ git describe > lib/facter/VERSION
- # $ ruby -r facter -e 'puts Facter.version'
- # 1.6.14-6-g66f2c99
+ # $ git describe > lib/facter/VERSION
+ # $ ruby -r facter -e 'puts Facter.version'
+ # 1.6.14-6-g66f2c99
#
# @api public
#
@@ -62,17 +61,21 @@ module Facter
@facter_version ||= FACTERVERSION
end
+ # Sets the Facter version
+ #
+ # @return [void]
+ #
+ # @api private
def self.version=(version)
@facter_version = version
end
- ##
- # read_version_file reads the content of the "VERSION" file that lives in the
+ # This reads the content of the "VERSION" file that lives in the
# same directory as this source code file.
#
# @api private
#
- # @return [String] for example: "1.6.14-6-gea42046" or nil if the VERSION
+ # @return [String] the version -- for example: "1.6.14-6-gea42046" or nil if the VERSION
# file does not exist.
def self.read_version_file(path)
if File.exists?(path)
diff --git a/spec/unit/facter_spec.rb b/spec/unit/facter_spec.rb
index 3f9d086..1b69d56 100755
--- a/spec/unit/facter_spec.rb
+++ b/spec/unit/facter_spec.rb
@@ -17,8 +17,8 @@ describe Facter do
end
it "should delegate the :fact method to the collection" do
- Facter.collection.expects(:fact)
- Facter.fact
+ Facter.collection.expects(:fact).with("afact")
+ Facter.fact("afact")
end
it "should delegate the :list method to the collection" do
@@ -28,7 +28,6 @@ describe Facter do
it "should load all facts when listing" do
Facter.collection.expects(:load_all)
- Facter.collection.stubs(:list)
Facter.list
end
@@ -44,8 +43,8 @@ describe Facter do
end
it "should delegate the :value method to the collection" do
- Facter.collection.expects(:value)
- Facter.value
+ Facter.collection.expects(:value).with("myvaluefact")
+ Facter.value("myvaluefact")
end
it "should delegate the :each method to the collection" do
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-puppet/facter.git
More information about the Pkg-puppet-devel
mailing list