# A class containing helper methods to aid in the extraction of relevant data
# from comments and YARD tags
class TemplateHelper

  # Extracts data from comments which include the supported YARD tags
  def extract_tag_data(object)
    examples = Hash.new
    example_tags = object.tags.find_all { |tag| tag.tag_name == "example" }
    example_tags.each do |example|
      examples["#{example.name}"] = example.text
    end

    return_tag = object.tags.find { |tag| tag.tag_name == "return"}
    return_text = return_tag.nil? ? nil : return_tag.text
    return_types = return_tag.nil? ? nil : return_tag.types
    return_details = (return_text.nil? && return_types.nil?) ? nil : [return_text, return_types]

    since_tag = object.tags.find { |tag| tag.tag_name == "since"}
    since_text = since_tag.nil? ? nil : since_tag.text

    {:name => object.name, :desc => object.docstring, :examples => examples, :since => since_text, :return => return_details}
  end

  # Given the parameter information and YARD param tags, extracts the
  # useful information and returns it as an array of hashes which can
  # be printed and formatted as HTML
  #
  # @param parameters [Array] parameter details obtained programmatically
  # @param tags_hash [Array] parameter details obtained from comments
  # @param fq_name [Boolean] does this parameter have a fully qualified name?
  #
  # @return [Hash] The relevant information about each parameter with the following keys/values:
  #   {:name    => [String] The name of the parameter
  #    :fq_name => [String] The fully qualified parameter name
  #    :desc    => [String] The description provided in the comment
  #    :types   => [Array] The parameter type(s) specified in the comment
  #    :exists  => [Boolean] True only if the parameter exists in the documented logic and not just in a comment}
  def extract_param_details(parameters, tags_hash, fq_name = false)
    parameter_info = []

    # Extract the information for parameters that actually exist
    # as opposed to parameters that are defined only in the comments
    parameters.each do |param|

      if fq_name
        param_name = param[0]
        fully_qualified_name = param[1]
      else
        param_name = param
      end

      param_tag = tags_hash.find { |tag| tag.name == param_name }

      description = param_tag.nil? ? nil : param_tag.text
      param_types = param_tag.nil? ? nil : param_tag.types

      param_details = {:name => param_name, :desc => description, :types => param_types, :exists? => true}

      if fq_name
        param_details[:fq_name] = fully_qualified_name
      end

      parameter_info.push(param_details)
    end

    # Check if there were any comments for parameters that do not exist
    tags_hash.each do |tag|
      param_exists = false
      parameter_info.each do |parameter|
        if parameter[:name] == tag.name
          param_exists = true
        end
      end
      if !param_exists
        parameter_info.push({:name => tag.name, :desc => tag.text, :types => tag.types, :exists? => false})
      end
    end

    parameter_info
  end

  # Generates parameter information in situations where the information can only
  # come from YARD tags in the comments, not from the code itself. For now the only
  # use for this is 3x functions. In this case exists? will always be true since we
  # cannot verify if the parameter exists in the code itself. We must trust the user
  # to provide information in the comments that is accurate.
  #
  # @param param_tags [Array] parameter details obtained from comments
  #
  # @return [Hash] The relevant information about each parameter with the following keys/values:
  #   {:name          => [String] The name of the parameter
  #    :desc          => [String] The description provided in the comment
  #    :types         => [Array] The parameter type(s) specified in the comment
  #    :exists        => [Boolean] True only if the parameter exists in the documented logic and not just in a comment
  #    :puppet_3_func => [Boolean] Are these parameters for a puppet 3 function? (relevant in HTML generation)}
  def comment_only_param_details(param_tags)
    return if param_tags.empty?

    parameter_info = []

    param_tags.each do |tag|
      parameter_info.push({:name => tag.name, :desc => tag.text, :types => tag.types, :exists? => true, :puppet_3_func => true})
    end

    parameter_info
  end
end