BigW Consortium Gitlab

dsl.rb 4.72 KB
Newer Older
1
module Gitlab
2
  module QuickActions
3 4 5 6
    module Dsl
      extend ActiveSupport::Concern

      included do
7 8
        cattr_accessor :command_definitions, instance_accessor: false do
          []
9 10
        end

11 12
        cattr_accessor :command_definitions_by_name, instance_accessor: false do
          {}
13 14 15 16
        end
      end

      class_methods do
17
        # Allows to give a description to the next quick action.
18 19
        # This description is shown in the autocomplete menu.
        # It accepts a block that will be evaluated with the context given to
20
        # `CommandDefintion#to_h`.
21 22 23 24 25 26 27 28 29 30 31
        #
        # Example:
        #
        #   desc do
        #     "This is a dynamic description for #{noteable.to_ability_name}"
        #   end
        #   command :command_key do |arguments|
        #     # Awesome code block
        #   end
        def desc(text = '', &block)
          @description = block_given? ? block : text
32 33
        end

34
        # Allows to define params for the next quick action.
35 36 37 38 39 40 41 42
        # These params are shown in the autocomplete menu.
        #
        # Example:
        #
        #   params "~label ~label2"
        #   command :command_key do |arguments|
        #     # Awesome code block
        #   end
43 44
        def params(*params, &block)
          @params = block_given? ? block : params
45 46
        end

47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
        # Allows to give an explanation of what the command will do when
        # executed. This explanation is shown when rendering the Markdown
        # preview.
        #
        # Example:
        #
        #   explanation do |arguments|
        #     "Adds label(s) #{arguments.join(' ')}"
        #   end
        #   command :command_key do |arguments|
        #     # Awesome code block
        #   end
        def explanation(text = '', &block)
          @explanation = block_given? ? block : text
        end

63 64 65
        # Allows to define conditions that must be met in order for the command
        # to be returned by `.command_names` & `.command_definitions`.
        # It accepts a block that will be evaluated with the context given to
66
        # `CommandDefintion#to_h`.
67
        #
68 69
        # Example:
        #
70 71 72
        #   condition do
        #     project.public?
        #   end
73 74 75
        #   command :command_key do |arguments|
        #     # Awesome code block
        #   end
76
        def condition(&block)
77
          @condition_block = block
78 79
        end

80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
        # Allows to perform initial parsing of parameters. The result is passed
        # both to `command` and `explanation` blocks, instead of the raw
        # parameters.
        # It accepts a block that will be evaluated with the context given to
        # `CommandDefintion#to_h`.
        #
        # Example:
        #
        #   parse_params do |raw|
        #     raw.strip
        #   end
        #   command :command_key do |parsed|
        #     # Awesome code block
        #   end
        def parse_params(&block)
          @parse_params_block = block
        end

98 99 100
        # Registers a new command which is recognizeable from body of email or
        # comment.
        # It accepts aliases and takes a block.
101
        #
102 103 104 105 106
        # Example:
        #
        #   command :my_command, :alias_for_my_command do |arguments|
        #     # Awesome code block
        #   end
107
        def command(*command_names, &block)
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130
          define_command(CommandDefinition, *command_names, &block)
        end

        # Registers a new substitution which is recognizable from body of email or
        # comment.
        # It accepts aliases and takes a block with the formatted content.
        #
        # Example:
        #
        #   command :my_substitution, :alias_for_my_substitution do |text|
        #     "#{text} MY AWESOME SUBSTITUTION"
        #   end
        def substitution(*substitution_names, &block)
          define_command(SubstitutionDefinition, *substitution_names, &block)
        end

        def definition_by_name(name)
          command_definitions_by_name[name.to_sym]
        end

        private

        def define_command(klass, *command_names, &block)
131
          name, *aliases = command_names
132

133
          definition = klass.new(
134
            name,
135 136 137 138 139 140 141
            aliases: aliases,
            description: @description,
            explanation: @explanation,
            params: @params,
            condition_block: @condition_block,
            parse_params_block: @parse_params_block,
            action_block: block
142
          )
143 144 145 146 147 148

          self.command_definitions << definition

          definition.all_names.each do |name|
            self.command_definitions_by_name[name] = definition
          end
149 150

          @description = nil
151
          @explanation = nil
152
          @params = nil
153
          @condition_block = nil
154 155
          @parse_params_block = nil
        end
156 157 158 159
      end
    end
  end
end