ruby-jss 1.2.3 → 1.2.4a1

data/lib/jamf/ruby_extensions/string/conversions.rb

@@ -0,0 +1,65 @@
+# Copyright 2019 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.
+
+module JamfRubyExtensions
+
+  module String
+
+    module Conversions
+
+      # Convert the strings "true" and "false"
+      # (after stripping whitespace and downcasing)
+      # to TrueClass and FalseClass respectively
+      #
+      # Return nil if any other string.
+      #
+      # @return [Boolean,nil] the boolean value
+      #
+      def j_to_bool
+        case strip.downcase
+        when 'true' then true
+        when 'false' then false
+        end # case
+      end # to bool
+
+      # Convert a string to a Jamf::Timestamp object
+      #
+      # @return [Time] the time represented by the string.
+      #
+      def j_to_timestamp
+        Jamf::Timestamp.new self
+      end
+
+      # Convert a String to a Pathname object
+      #
+      # @return [Pathname]
+      #
+      def j_to_pathname
+        Pathname.new self
+      end
+
+    end # module
+
+  end # module
+
+end # module

data/lib/jamf/ruby_extensions/string/predicates.rb

@@ -0,0 +1,47 @@
+# Copyright 2019 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.
+#
+#
+
+module JamfRubyExtensions
+
+  module String
+
+    module Predicates
+
+      INTEGER_RE = /\A[0-9]+\Z/.freeze
+
+      # Is this string also a positive integer?
+      # (i.e. it consists only of numberic digits)
+      #
+      # @return [Boolean]
+      #
+      def j_integer?
+        self =~ INTEGER_RE ? true : false
+      end
+
+    end # module
+
+  end # module
+
+end # module

data/lib/jamf/utility.rb

@@ -0,0 +1,423 @@
+# Copyright 2019 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.
+#
+#
+
+# The Module
+module Jamf
+
+  # Constants
+  ###################################
+
+  # These Utility constants are useful all over the place.
+  # Many of them are commonly used Strings.
+
+  BLANK = ''.freeze
+
+  UNDERSCORE = '_'.freeze
+
+  # A collection of useful utility methods. Mostly for
+  # converting values between formats, parsing data, and
+  # user interaction.
+
+  # TODO: confirm need for each method in Jamf Pro API.
+
+  # Converts an OS Version into an Array of higher OS versions.
+  #
+  # It's unlikely that this library will still be in use as-is by the release of OS X 10.30.20.
+  # Hopefully well before then JAMF will implement a "minimum OS" in the JSS itself.
+  #
+  # @param min_os [String] the mimimum OS version to expand, e.g. ">=10.6.7"  or "10.6.7"
+  #
+  # @return [Array] Nearly all potential OS versions from the minimum to 10.19.x.
+  #
+  # @example
+  #   JSS.expand_min_os ">=10.6.7" # => returns this array
+  #    # ["10.6.7",
+  #    #  "10.6.8",
+  #    #  "10.6.9",
+  #    #   ...
+  #    #  "10.6.20",
+  #    #  "10.7.x",
+  #    #  "10.8.x",
+  #    #  ...
+  #    #  "10.30.x"]
+  #
+  #
+  def self.expand_min_os(min_os)
+    min_os = min_os.delete '>='
+
+    # split the version into major, minor and maintenance release numbers
+    (maj, min, maint) = min_os.split('.')
+    maint = 'x' if maint.nil? || maint == '0'
+
+    # if the maint release number is an "x" just start the list of OK OS's with it
+    if maint == 'x'
+      ok_oses = [maj + '.' + min.to_s + '.x']
+
+    # otherwise, start with it and explicitly add all maint releases up to 20
+    # (and hope apple doesn't do more than 20 maint releases for an OS)
+    else
+      ok_oses = []
+      (maint.to_i..20).each do |m|
+        ok_oses << maj + '.' + min + '.' + m.to_s
+      end # each m
+    end
+
+    # now account for all OS X versions starting with 10.
+    # up to at least 10.30.x
+    ((min.to_i + 1)..30).each do |v|
+      ok_oses << maj + '.' + v.to_s + '.x'
+    end # each v
+    ok_oses
+  end
+
+  # Scripts and packages can have processor limitations.
+  # This method tests a given processor, against a requirement
+  # to see if the requirement is met.
+  #
+  # @param requirement[String] The processor requirement.
+  #   either 'ppc', 'x86', or some variation on "none", nil, or empty
+  #
+  # @param processor[String] the processor to check, defaults to
+  #  the processor of the current machine. Any flavor of intel
+  ##   is (i486, i386, x86-64, etc) is treated as "x86"
+  #
+  # @return [Boolean] can this pkg be installed with the processor
+  #   given?
+  #
+  def self.processor_ok?(requirement, processor = nil)
+    return true if requirement.to_s.empty? || requirement =~ /none/i
+    processor ||= `/usr/bin/uname -p`
+    requirement == (processor.to_s.include?('86') ? 'x86' : 'ppc')
+  end
+
+  # Scripts and packages can have OS limitations.
+  # This method tests a given OS, against a requirement list
+  # to see if the requirement is met.
+  #
+  # @param requirement[String,Array] The os requirement list, a comma-seprated string
+  #   or array of strings of allows OSes. e.g. 10.7, 10.8.5 or 10.9.x
+  #
+  # @param processor[String] the os to check, defaults to
+  #  the os of the current machine.
+  #
+  # @return [Boolean] can this pkg be installed with the processor
+  #   given?
+  #
+  def self.os_ok?(requirement, os_to_check = nil)
+    return true if requirement.to_s =~ /none/i
+    return true if requirement.to_s == 'n'
+    requirement = JSS.to_s_and_a(requirement)[:arrayform]
+    return true if requirement.empty?
+
+    os_to_check ||= `/usr/bin/sw_vers -productVersion`.chomp
+
+    # convert the requirement array into an array of regexps.
+    # examples:
+    #   "10.8.5" becomes  /^10\.8\.5$/
+    #   "10.8" becomes /^10.8(.0)?$/
+    #   "10.8.x" /^10\.8\.?\d*$/
+    req_regexps = requirement.map do |r|
+      if r.end_with?('.x')
+        /^#{r.chomp('.x').gsub('.', '\.')}\.?\d*$/
+
+      elsif r =~ /^\d+\.\d+$/
+        /^#{r.gsub('.', '\.')}(.0)?$/
+
+      else
+        /^#{r.gsub('.', '\.')}$/
+      end
+    end
+
+    req_regexps.each { |re| return true if os_to_check =~ re }
+    false
+  end
+
+  # Given a list of data as a comma-separated string, or an Array of strings,
+  # return a Hash with both versions.
+  #
+  # Some parts of the JSS require lists as comma-separated strings, while
+  # often those data are easier work with as arrays. This method is a handy way
+  # to get either form when given either form.
+  #
+  # @param somedata [String, Array] the data to parse, of either class,
+  #
+  # @return [Hash{:stringform => String, :arrayform => Array}] the data as both comma-separated String and Array
+  #
+  # @example
+  #   JSS.to_s_and_a "foo, bar, baz" # Hash => {:stringform => "foo, bar, baz", :arrayform => ["foo", "bar", "baz"]}
+  #
+  #   JSS.to_s_and_a ["foo", "bar", "baz"] # Hash => {:stringform => "foo, bar, baz", :arrayform => ["foo", "bar", "baz"]}
+  #
+  def self.to_s_and_a(somedata)
+    case somedata
+    when nil
+      valstr = ''
+      valarr = []
+    when String
+      valstr = somedata
+      valarr = somedata.split(/,\s*/)
+    when Array
+      valstr = somedata.join ', '
+      valarr = somedata
+    else
+      raise Jamf::InvalidDataError, 'Input must be a comma-separated String or an Array of Strings'
+    end # case
+    { stringform: valstr, arrayform: valarr }
+  end # to_s_and_a
+
+  # Parse a plist into a Ruby data structure.
+  # This enhances Plist::parse_xml taking file paths, as well as XML Strings
+  # and reading the files regardless of binary/XML format.
+  #
+  # @param plist[Pathname, String] the plist XML, or the path to a plist file
+  #
+  # @return [Object] the parsed plist as a ruby hash,array, etc.
+  #
+  def self.parse_plist(plist)
+    # did we get a string of xml, or a string pathname?
+    case plist
+    when String
+      return Plist.parse_xml plist if plist.include? '</plist>'
+      plist = Pathname.new plist
+    when Pathname
+      true
+    else
+      raise ArgumentError, 'Argument must be a path (as a Pathname or String) or a String of XML'
+    end # case plist
+
+    # if we're here, its a Pathname
+    raise Jamf::MissingDataError, "No such file: #{plist}" unless plist.file?
+
+    Plist.parse_xml `/usr/libexec/PlistBuddy -x -c print #{Shellwords.escape(plist.to_s)}`.force_encoding('UTF-8')
+  end # parse_plist
+
+  # TODO: Sill needed in Jamf API?
+  #
+  # Converts anything that responds to #to_s to a Time, or nil
+  #
+  # Return nil if the item is nil, 0 or an empty String.
+  #
+  # Otherwise the item converted to a string, and parsed with DateTime.parse.
+  # It is then examined to see if it has a UTC offset. If not, the local offset
+  # is applied, then the DateTime is converted to a Time.
+  #
+  # @param a_datetime [#to_s] The thing to convert to a time.
+  #
+  # @return [Time, nil] nil is returned if a_datetime is nil, 0 or an empty String.
+  #
+  def self.parse_time(a_datetime)
+    return nil if NIL_DATES.include? a_datetime
+
+    the_dt = DateTime.parse(a_datetime.to_s)
+
+    # The microseconds in DateTimes are stored as a fraction of a day.
+    # Convert them to an integer of microseconds
+    usec = (the_dt.sec_fraction * 60 * 60 * 24 * (10**6)).to_i
+
+    # if the UTC offset of the datetime is zero, make a new one with the correct local offset
+    # (which might also be zero if we happen to be in GMT)
+    the_dt = DateTime.new(the_dt.year, the_dt.month, the_dt.day, the_dt.hour, the_dt.min, the_dt.sec, Jamf::TIME_ZONE_OFFSET) if the_dt.offset.zero?
+    # now convert it to a Time and return it
+    Time.at the_dt.strftime('%s').to_i, usec
+  end # parse_time
+
+  # TODO: Sill needed in Jamf API?
+  #
+  # Converts JSS epoch (unix epoch + milliseconds) to a Ruby Time object
+  #
+  # @param epoch[String, Integer, nil]
+  #
+  # @return [Time, nil] nil is returned if epoch is nil, 0 or an empty String.
+  #
+  def self.epoch_to_time(epoch)
+    return nil if NIL_DATES.include? epoch
+    Time.at(epoch.to_i / 1000.0)
+  end # parse_date
+
+  # TODO: Move to APIObject
+  #
+  # Given a name, singular or plural, of a Jamf::APIObject subclass as a String
+  # or Symbol (e.g. :computer/'computers'), return the class itself
+  # (e.g. Jamf::Computer)
+  # The available names are the RSRC_LIST_KEY
+  # and RSRC_OBJECT_KEY values for each APIObject subclass.
+  #
+  # @seealso JSS.api_object_names
+  #
+  # @param name[String,Symbol] The name of a Jamf::APIObject subclass, singluar
+  #   or plural
+  #
+  # @return [Class] The class
+  #
+  def self.api_object_class(name)
+    klass = api_object_names[name.downcase.to_sym]
+    raise Jamf::InvalidDataError, "Unknown API Object Class: #{name}" unless klass
+    klass
+  end
+
+  # TODO: Move to APIObject
+  #
+  # APIObject subclasses have singular names, and are, of course
+  # capitalized, e.g. 'Computer'
+  # But we often want to refer to them in the plural, or lowercase,
+  # e.g. 'computers'
+  # This method returns a Hash of the RSRC_LIST_KEY (a plural symbol)
+  # and the RSRC_OBJECT_KEY (a singular symbol) of each APIObject
+  # subclass, keyed to the class itself, such that both :computer
+  # and :computers are keys for Jamf::Computer and both :policy and
+  # :policies are keys for Jamf::Policy, and so on.
+  #
+  # @return [Hash] APIObject subclass names to Classes
+  #
+  def self.api_object_names
+    return @api_object_names if @api_object_names
+    @api_object_names ||= {}
+    JSS.constants.each do |const|
+      klass = JSS.const_get const
+      next unless klass.is_a? Class
+      next unless klass.ancestors.include? Jamf::APIObject
+      @api_object_names[klass.const_get(:RSRC_LIST_KEY).to_sym] = klass if klass.constants.include? :RSRC_LIST_KEY
+      @api_object_names[klass.const_get(:RSRC_OBJECT_KEY).to_sym] = klass if klass.constants.include? :RSRC_OBJECT_KEY
+    end
+    @api_object_names
+  end
+
+  # TODO: Update or remove for Jamf API
+  # Parse a JSS Version number into something comparable.
+  #
+  # This method returns a Hash with these keys:
+  # * :major => the major version, Integer
+  # * :minor => the minor version, Integor
+  # * :maint => the revision, Integer (also available as :patch and :revision)
+  # * :build => the revision, String
+  # * :version => a Gem::Version object built from :major, :minor, :revision
+  #   which can be easily compared with other Gem::Version objects.
+  #
+  # NOTE: the :version value ignores build numbers, so comparisons
+  # only compare major.minor.maint
+  #
+  # @param version[String] a JSS version number from the API
+  #
+  # @return [Hash{Symbol => String, Gem::Version}] the parsed version data.
+  #
+  def self.parse_jss_version(version)
+    major, second_part, *_rest = version.split('.')
+    raise Jamf::InvalidDataError, 'JSS Versions must start with "x.x" where x is one or more digits' unless major =~ /\d$/ && second_part =~ /^\d/
+
+    release, build = version.split(/-/)
+
+    major, minor, revision = release.split '.'
+    minor ||= 0
+    revision ||= 0
+
+    {
+      major: major.to_i,
+      minor:  minor.to_i,
+      revision:  revision.to_i,
+      maint:  revision.to_i,
+      patch:  revision.to_i,
+      build:  build,
+      version: Gem::Version.new("#{major}.#{minor}.#{revision}")
+    }
+  end
+
+  # @return [Boolean] is this code running as root?
+  #
+  def self.superuser?
+    Process.euid.zero?
+  end
+
+  # Retrive one or all lines from whatever was piped to standard input.
+  #
+  # Standard input is read completely the first time this method is called
+  # and the lines are stored as an Array in the module var @stdin_lines
+  #
+  # @param line[Integer] which line of stdin is being retrieved.
+  #  The default is zero (0) which returns all of stdin as a single string.
+  #
+  # @return [String, nil] the requested ling of stdin, or nil if it doesn't exist.
+  #
+  def self.stdin(line = 0)
+    @stdin_lines ||= ($stdin.tty? ? [] : $stdin.read.lines.map { |l| l.chomp("\n") })
+
+    return @stdin_lines.join("\n") if line <= 0
+    idx = line - 1
+    @stdin_lines[idx]
+  end
+
+  # Prompt for a password in a terminal.
+  #
+  # @param message [String] the prompt message to display
+  #
+  # @return [String] the text typed by the user
+  #
+  def self.prompt_for_password(message)
+    begin
+      $stdin.reopen '/dev/tty' unless $stdin.tty?
+      $stderr.print "#{message} "
+      system '/bin/stty -echo'
+      pw = $stdin.gets.chomp("\n")
+      puts
+    ensure
+      system '/bin/stty echo'
+    end # begin
+    pw
+  end
+
+  # Very handy!
+  # lifted from
+  # http://stackoverflow.com/questions/4136248/how-to-generate-a-human-readable-time-range-using-ruby-on-rails
+  #
+  def self.humanize_secs(secs)
+    [[60, :second], [60, :minute], [24, :hour], [7, :day], [52.179, :week], [1_000_000, :year]].map do |count, name|
+      next unless secs > 0
+
+      secs, n = secs.divmod(count)
+      n = n.to_i
+      "#{n} #{n == 1 ? name : (name.to_s + 's')}"
+    end.compact.reverse.join(' ')
+  end
+
+  # un/set devmode mode.
+  # Useful when coding - methods can call JSS.devmode? and then
+  # e.g. spit out something instead of performing some action.
+  #
+  # @param [Symbol] Set devmode :on or :off
+  #
+  # @return [Boolean] The new state of devmode
+  #
+  def self.devmode(setting)
+    @devmode = setting == :on
+  end
+
+  # is devmode currently on?
+  #
+  # @return [Boolean]
+  #
+  def self.devmode?
+    @devmode
+  end
+
+end # module