openvox 8.19.0

data/lib/puppet/face/help.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require_relative '../../puppet/face'
+require_relative '../../puppet/application/face_base'
+require_relative '../../puppet/util/constant_inflector'
+require 'pathname'
+require 'erb'
+
+Puppet::Face.define(:help, '0.0.1') do
+  copyright "Puppet Inc., Vox Pupuli", 2011
+  license   _("Apache 2 license; see COPYING")
+
+  summary _("Display OpenVox help.")
+
+  action(:help) do
+    summary _("Display help about OpenVox subcommands and their actions.")
+    arguments _("[<subcommand>] [<action>]")
+    returns _("Short help text for the specified subcommand or action.")
+    examples _(<<-'EOT')
+      Get help for an action:
+
+      $ puppet help
+    EOT
+
+    option "--version " + _("VERSION") do
+      summary _("The version of the subcommand for which to show help.")
+    end
+
+    option "--ronn" do
+      summary _("Whether to render the help text in ronn format.")
+      default_to { false }
+    end
+
+    default
+    when_invoked do |*args|
+      options = args.pop
+
+      unless options[:ronn]
+        if default_case?(args) || help_for_help?(args)
+          return erb('global.erb').result(binding)
+        end
+      end
+
+      if args.length > 2
+        # TRANSLATORS 'puppet help' is a command line and should not be translated
+        raise ArgumentError, _("The 'puppet help' command takes two (optional) arguments: a subcommand and an action")
+      end
+
+      version = :current
+      if options.has_key? :version
+        if options[:version].to_s !~ /^current$/i
+          version = options[:version]
+        elsif args.length == 0
+          raise ArgumentError, _("Supplying a '--version' only makes sense when a Faces subcommand is given")
+          # TRANSLATORS '--version' is a command line option and should not be translated
+        end
+      end
+
+      facename, actionname = args
+      if legacy_applications.include? facename
+        if actionname
+          raise ArgumentError, _("The legacy subcommand '%{sub_command}' does not support supplying an action") % { sub_command: facename }
+        end
+
+        # legacy apps already emit ronn output
+        return render_application_help(facename)
+      elsif options[:ronn]
+        render_face_man(facename || :help)
+      # Calling `puppet help <app> --ronn` normally calls this action with
+      # <app> as the first argument in the `args` array. However, if <app>
+      # happens to match the name of an action, like `puppet help help
+      # --ronn`, then face_base "eats" the argument and `args` will be
+      # empty. Rather than force users to type `puppet help help help
+      # --ronn`, default the facename to `:help`
+      else
+        render_face_help(facename, actionname, version)
+      end
+    end
+  end
+
+  def default_case?(args)
+    args.empty?
+  end
+
+  def help_for_help?(args)
+    args.length == 1 && args.first == 'help'
+  end
+
+  def render_face_man(facename)
+    # set 'face' as it's used in the erb processing.
+    face = Puppet::Face[facename.to_sym, :current]
+    # avoid unused variable warning
+    _face = face
+    erb('man.erb').result(binding)
+  end
+
+  def render_application_help(applicationname)
+    Puppet::Application[applicationname].help
+  rescue StandardError, LoadError => detail
+    message = []
+    message << _('Could not load help for the application %{application_name}.') % { application_name: applicationname }
+    message << _('Please check the error logs for more information.')
+    message << ''
+    message << _('Detail: "%{detail}"') % { detail: detail.message }
+    fail ArgumentError, message.join("\n"), detail.backtrace
+  end
+
+  def render_face_help(facename, actionname, version)
+    face, action = load_face_help(facename, actionname, version)
+    template_for(face, action).result(binding)
+  rescue StandardError, LoadError => detail
+    message = []
+    message << _('Could not load help for the face %{face_name}.') % { face_name: facename }
+    message << _('Please check the error logs for more information.')
+    message << ''
+    message << _('Detail: "%{detail}"') % { detail: detail.message }
+    fail ArgumentError, message.join("\n"), detail.backtrace
+  end
+
+  def load_face_help(facename, actionname, version)
+    face = Puppet::Face[facename.to_sym, version]
+    if actionname
+      action = face.get_action(actionname.to_sym)
+      unless action
+        fail ArgumentError, _("Unable to load action %{actionname} from %{face}") % { actionname: actionname, face: face }
+      end
+    end
+
+    [face, action]
+  end
+
+  def template_for(face, action)
+    if action.nil?
+      erb('face.erb')
+    else
+      erb('action.erb')
+    end
+  end
+
+  def erb(name)
+    template = (Pathname(__FILE__).dirname + "help" + name)
+    erb = Puppet::Util.create_erb(template.read)
+    erb.filename = template.to_s
+    erb
+  end
+
+  # Return a list of applications that are not simply just stubs for Faces.
+  def legacy_applications
+    Puppet::Application.available_application_names.reject do |appname|
+      is_face_app?(appname) or exclude_from_docs?(appname)
+    end.sort
+  end
+
+  def generate_summary(appname)
+    if is_face_app?(appname)
+      begin
+        face = Puppet::Face[appname, :current]
+        # Add deprecation message to summary if the face is deprecated
+        summary = face.deprecated? ? face.summary + ' ' + _("(Deprecated)") : face.summary
+        [appname, summary, '  ']
+      rescue StandardError, LoadError
+        error_message = _("!%{sub_command}! Subcommand unavailable due to error.") % { sub_command: appname }
+        error_message += ' ' + _("Check error logs.")
+        [error_message, '', '  ']
+      end
+    else
+      begin
+        summary = Puppet::Application[appname].summary
+        if summary.empty?
+          summary = horribly_extract_summary_from(appname)
+        end
+        [appname, summary, '  ']
+      rescue StandardError, LoadError
+        error_message = _("!%{sub_command}! Subcommand unavailable due to error.") % { sub_command: appname }
+        error_message += ' ' + _("Check error logs.")
+        [error_message, '', '  ']
+      end
+    end
+  end
+
+  # Return a list of all applications (both legacy and Face applications), along with a summary
+  #  of their functionality.
+  # @return [Array] An Array of Arrays.  The outer array contains one entry per application; each
+  #  element in the outer array is a pair whose first element is a String containing the application
+  #  name, and whose second element is a String containing the summary for that application.
+  def all_application_summaries
+    available_application_names_special_sort().inject([]) do |result, appname|
+      next result if exclude_from_docs?(appname)
+
+      if appname == COMMON || appname == SPECIALIZED || appname == BLANK
+        result << appname
+      else
+        result << generate_summary(appname)
+      end
+    end
+  end
+
+  COMMON = 'Common:'
+  SPECIALIZED = 'Specialized:'
+  BLANK = "\n"
+  COMMON_APPS = %w[apply agent config help lookup module resource]
+  def available_application_names_special_sort
+    full_list = Puppet::Application.available_application_names
+    a_list = full_list & COMMON_APPS
+    a_list = a_list.sort
+    also_ran = full_list - a_list
+    also_ran = also_ran.sort
+    [[COMMON], a_list, [BLANK], [SPECIALIZED], also_ran].flatten(1)
+  end
+
+  def common_app_summaries
+    COMMON_APPS.map do |appname|
+      generate_summary(appname)
+    end
+  end
+
+  def specialized_app_summaries
+    specialized_apps = Puppet::Application.available_application_names - COMMON_APPS
+    specialized_apps.filter_map do |appname|
+      generate_summary(appname) unless exclude_from_docs?(appname)
+    end
+  end
+
+  def horribly_extract_summary_from(appname)
+    help = Puppet::Application[appname].help.split("\n")
+    # Now we find the line with our summary, extract it, and return it.  This
+    # depends on the implementation coincidence of how our pages are
+    # formatted.  If we can't match the pattern we expect we return the empty
+    # string to ensure we don't blow up in the summary. --daniel 2011-04-11
+    while line = help.shift # rubocop:disable Lint/AssignmentInCondition
+      md = /^puppet-#{appname}\([^)]+\) -- (.*)$/.match(line)
+      if md
+        return md[1]
+      end
+    end
+    ''
+  end
+  # This should absolutely be a private method, but for some reason it appears
+  #  that you can't use the 'private' keyword inside of a Face definition.
+  #  See #14205.
+  # private :horribly_extract_summary_from
+
+  def exclude_from_docs?(appname)
+    %w[face_base indirection_base report status].include? appname
+  end
+  # This should absolutely be a private method, but for some reason it appears
+  #  that you can't use the 'private' keyword inside of a Face definition.
+  #  See #14205.
+  # private :exclude_from_docs?
+
+  def is_face_app?(appname)
+    clazz = Puppet::Application.find(appname)
+
+    clazz.ancestors.include?(Puppet::Application::FaceBase)
+  end
+  # This should probably be a private method, but for some reason it appears
+  #  that you can't use the 'private' keyword inside of a Face definition.
+  #  See #14205.
+  # private :is_face_app?
+end

data/lib/puppet/face/module/changes.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+Puppet::Face.define(:module, '1.0.0') do
+  action(:changes) do
+    summary _("Show modified files of an installed module.")
+    description <<-EOT
+      Shows any files in a module that have been modified since it was
+      installed. This action compares the files on disk to the md5 checksums
+      included in the module's checksums.json or, if that is missing, in
+      metadata.json.
+    EOT
+
+    returns _("Array of strings representing paths of modified files.")
+
+    examples <<-EOT
+      Show modified files of an installed module:
+
+      $ puppet module changes /etc/puppetlabs/code/modules/vcsrepo/
+      warning: 1 files modified
+      lib/puppet/provider/vcsrepo.rb
+    EOT
+
+    arguments _("<path>")
+
+    when_invoked do |path, options|
+      Puppet::ModuleTool.set_option_defaults options
+      root_path = Puppet::ModuleTool.find_module_root(path)
+      unless root_path
+        raise ArgumentError, _("Could not find a valid module at %{path}") % { path: path.inspect }
+      end
+
+      Puppet::ModuleTool::Applications::Checksummer.run(root_path, options)
+    end
+
+    when_rendering :console do |return_value|
+      if return_value.empty?
+        Puppet.notice _("No modified files")
+      else
+        Puppet.warning _("%{count} files modified") % { count: return_value.size }
+      end
+      return_value.map(&:to_s).join("\n")
+    end
+  end
+end

data/lib/puppet/face/module/install.rb

@@ -0,0 +1,149 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative '../../../puppet/forge'
+require_relative '../../../puppet/module_tool/install_directory'
+require 'pathname'
+
+Puppet::Face.define(:module, '1.0.0') do
+  action(:install) do
+    summary _("Install a module from the Puppet Forge or a release archive.")
+    description <<-EOT
+      Installs a module from the Puppet Forge or from a release archive file.
+      Note: Module install uses MD5 checksums, which are prohibited on FIPS enabled systems.
+
+      The specified module will be installed into the directory
+      specified with the `--target-dir` option, which defaults to the first
+      directory in the modulepath.
+    EOT
+
+    returns _("Pathname object representing the path to the installed module.")
+
+    examples <<-'EOT'
+      Install a module:
+
+      $ puppet module install puppetlabs-vcsrepo
+      Preparing to install into /etc/puppetlabs/code/modules ...
+      Downloading from https://forgeapi.puppet.com ...
+      Installing -- do not interrupt ...
+      /etc/puppetlabs/code/modules
+      └── puppetlabs-vcsrepo (v0.0.4)
+
+      Install a module to a specific environment:
+
+      $ puppet module install puppetlabs-vcsrepo --environment development
+      Preparing to install into /etc/puppetlabs/code/environments/development/modules ...
+      Downloading from https://forgeapi.puppet.com ...
+      Installing -- do not interrupt ...
+      /etc/puppetlabs/code/environments/development/modules
+      └── puppetlabs-vcsrepo (v0.0.4)
+
+      Install a specific module version:
+
+      $ puppet module install puppetlabs-vcsrepo -v 0.0.4
+      Preparing to install into /etc/puppetlabs/modules ...
+      Downloading from https://forgeapi.puppet.com ...
+      Installing -- do not interrupt ...
+      /etc/puppetlabs/code/modules
+      └── puppetlabs-vcsrepo (v0.0.4)
+
+      Install a module into a specific directory:
+
+      $ puppet module install puppetlabs-vcsrepo --target-dir=/opt/puppetlabs/puppet/modules
+      Preparing to install into /opt/puppetlabs/puppet/modules ...
+      Downloading from https://forgeapi.puppet.com ...
+      Installing -- do not interrupt ...
+      /opt/puppetlabs/puppet/modules
+      └── puppetlabs-vcsrepo (v0.0.4)
+
+      Install a module into a specific directory and check for dependencies in other directories:
+
+      $ puppet module install puppetlabs-vcsrepo --target-dir=/opt/puppetlabs/puppet/modules --modulepath /etc/puppetlabs/code/modules
+      Preparing to install into /opt/puppetlabs/puppet/modules ...
+      Downloading from https://forgeapi.puppet.com ...
+      Installing -- do not interrupt ...
+      /opt/puppetlabs/puppet/modules
+      └── puppetlabs-vcsrepo (v0.0.4)
+
+      Install a module from a release archive:
+
+      $ puppet module install puppetlabs-vcsrepo-0.0.4.tar.gz
+      Preparing to install into /etc/puppetlabs/code/modules ...
+      Downloading from https://forgeapi.puppet.com ...
+      Installing -- do not interrupt ...
+      /etc/puppetlabs/code/modules
+      └── puppetlabs-vcsrepo (v0.0.4)
+
+      Install a module from a release archive and ignore dependencies:
+
+      $ puppet module install puppetlabs-vcsrepo-0.0.4.tar.gz --ignore-dependencies
+      Preparing to install into /etc/puppetlabs/code/modules ...
+      Installing -- do not interrupt ...
+      /etc/puppetlabs/code/modules
+      └── puppetlabs-vcsrepo (v0.0.4)
+
+    EOT
+
+    arguments _("<name>")
+
+    option "--force", "-f" do
+      summary _("Force overwrite of existing module, if any. (Implies --ignore-dependencies.)")
+      description <<-EOT
+        Force overwrite of existing module, if any.
+        Implies --ignore-dependencies.
+      EOT
+    end
+
+    option "--target-dir DIR", "-i DIR" do
+      summary _("The directory into which modules are installed.")
+      description <<-EOT
+        The directory into which modules are installed; defaults to the first
+        directory in the modulepath.
+
+        Specifying this option will change the installation directory, and
+        will use the existing modulepath when checking for dependencies. If
+        you wish to check a different set of directories for dependencies, you
+        must also use the `--environment` or `--modulepath` options.
+      EOT
+    end
+
+    option "--ignore-dependencies" do
+      summary _("Do not attempt to install dependencies. (Implied by --force.)")
+      description <<-EOT
+        Do not attempt to install dependencies. Implied by --force.
+      EOT
+    end
+
+    option "--version VER", "-v VER" do
+      summary _("Module version to install.")
+      description <<-EOT
+        Module version to install; can be an exact version or a requirement string,
+        eg '>= 1.0.3'. Defaults to latest version.
+      EOT
+    end
+
+    when_invoked do |name, options|
+      Puppet::ModuleTool.set_option_defaults options
+      Puppet.notice _("Preparing to install into %{dir} ...") % { dir: options[:target_dir] }
+
+      install_dir = Puppet::ModuleTool::InstallDirectory.new(Pathname.new(options[:target_dir]))
+      Puppet::ModuleTool::Applications::Installer.run(name, install_dir, options)
+    end
+
+    when_rendering :console do |return_value, name, _options|
+      case return_value[:result]
+      when :noop
+        Puppet.notice _("Module %{name} %{version} is already installed.") % { name: name, version: return_value[:version] }
+        exit 0
+      when :failure
+        Puppet.err(return_value[:error][:multiline])
+        exit 1
+      else
+        tree = Puppet::ModuleTool.build_tree(return_value[:graph], return_value[:install_dir])
+
+        "#{return_value[:install_dir]}\n" +
+          Puppet::ModuleTool.format_tree(tree)
+      end
+    end
+  end
+end