ruby-terraform 0.65.0.pre.15 → 1.0.0.pre.1

data/lib/ruby_terraform/commands/validate.rb

@@ -1,17 +1,65 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform validate+ command which checks whether a
+    # configuration is valid.
+    #
+    # Validates the configuration files in a directory, referring only to the
+    # configuration and not accessing any remote services such as remote state,
+    # provider APIs, etc.
+    #
+    # Validate runs checks that verify whether a configuration is syntactically
+    # valid and internally consistent, regardless of any provided variables or
+    # existing state. It is thus primarily useful for general verification of
+    # reusable modules, including correctness of attribute names and value
+    # types.
+    #
+    # It is safe to run this command automatically, for example as a post-save
+    # check in a text editor or as a test step for a re-usable module in a CI
+    # system.
+    #
+    # Validation requires an initialized working directory with any referenced
+    # plugins and modules installed. To initialize a working directory for
+    # validation without accessing any configured remote backend, use the {Init}
+    # command passing +:backend+ as +false+.
+    #
+    # To verify configuration in the context of a particular run (a particular
+    # target workspace, input variable values, etc), use the {Plan} command
+    # instead, which includes an implied validation check.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {Validate} via {#execute}, the following
+    # options are supported:
+    #
+    # * +:directory+: the path to a directory containing terraform configuration
+    #   (deprecated in terraform 0.14, removed in terraform 0.15, use +:chdir+
+    #   instead).
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:json+: whether or not to produce output in a machine-readable JSON
+    #   format, suitable for use in text editor integrations and other automated
+    #   systems; always disables color; defaults to +false+.
+    # * +:no_color+: whether or not the output from the command should be in
+    #   color; defaults to +false+.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::Validate.new.execute(
+    #     directory: 'infra/networking')
+    #
     class Validate < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[validate]
       end
 
+      # @!visibility private
       def options
         %w[
           -json
@@ -19,13 +67,10 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:directory]]
       end
-
-      def parameter_defaults(_parameters)
-        { vars: {}, var_files: [] }
-      end
     end
   end
 end

data/lib/ruby_terraform/commands/workspace_delete.rb

@@ -1,17 +1,42 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform workspace delete+ command which deletes a workspace.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {WorkspaceDelete} via {#execute}, the
+    # following options are supported:
+    #
+    # * +:name+: the name of the workspace to delete; required.
+    # * +:directory+: the path to a directory containing terraform configuration
+    #   (deprecated in terraform 0.14, removed in terraform 0.15, use +:chdir+
+    #   instead).
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:force+: whether or not to remove a non-empty workspace; defaults to
+    #   +false+.
+    # * +:lock+: when +true+, locks the state file when locking is supported;
+    #   when +false+, does not lock the state file; defaults to +true+.
+    # * +:lock_timeout+: the duration to retry a state lock; defaults to +"0s"+.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::WorkspaceDelete.new.execute(
+    #     name: 'example')
+    #
     class WorkspaceDelete < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[workspace delete]
       end
 
+      # @!visibility private
       def options
         %w[
           -force
@@ -20,12 +45,9 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
-        [parameters[:workspace], parameters[:directory]]
-      end
-
-      def parameter_defaults(_parameters)
-        { directory: nil }
+        [parameters[:name], parameters[:directory]]
       end
     end
   end

data/lib/ruby_terraform/commands/workspace_list.rb

@@ -1,24 +1,39 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform workspace list+ command which lists workspaces.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {WorkspaceList} via {#execute}, the
+    # following options are supported:
+    #
+    # * +:directory+: the path to a directory containing terraform configuration
+    #   (deprecated in terraform 0.14, removed in terraform 0.15, use +:chdir+
+    #   instead).
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::WorkspaceList.new.execute(
+    #     directory: 'infra/networking')
+    #
     class WorkspaceList < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[workspace list]
       end
 
+      # @!visibility private
       def arguments(parameters)
         [parameters[:directory]]
       end
-
-      def parameter_defaults(_parameters)
-        { directory: nil }
-      end
     end
   end
 end

data/lib/ruby_terraform/commands/workspace_new.rb

@@ -1,17 +1,41 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform workspace new+ command which creates a new workspace.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {WorkspaceNew} via {#execute}, the
+    # following options are supported:
+    #
+    # * +:name+: the name of the workspace to create; required.
+    # * +:directory+: the path to a directory containing terraform configuration
+    #   (deprecated in terraform 0.14, removed in terraform 0.15, use +:chdir+
+    #   instead).
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    # * +:lock+: when +true+, locks the state file when locking is supported;
+    #   when +false+, does not lock the state file; defaults to +true+.
+    # * +:lock_timeout+: the duration to retry a state lock; defaults to +"0s"+.
+    # * +:state+: the path to a state file to copy into the new workspace.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::WorkspaceNew.new.execute(
+    #     name: 'example')
+    #
     class WorkspaceNew < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[workspace new]
       end
 
+      # @!visibility private
       def options
         %w[
           -lock
@@ -20,12 +44,9 @@ module RubyTerraform
         ] + super
       end
 
+      # @!visibility private
       def arguments(parameters)
-        [parameters[:workspace], parameters[:directory]]
-      end
-
-      def parameter_defaults(_parameters)
-        { directory: nil }
+        [parameters[:name], parameters[:directory]]
       end
     end
   end

data/lib/ruby_terraform/commands/workspace_select.rb

@@ -1,23 +1,39 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform workspace select+ command which selects a workspace.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {WorkspaceSelect} via {#execute}, the
+    # following options are supported:
+    #
+    # * +:name+: the name of the workspace to select; required.
+    # * +:directory+: the path to a directory containing terraform configuration
+    #   (deprecated in terraform 0.14, removed in terraform 0.15, use +:chdir+
+    #   instead).
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    #
+    # @example BasicInvocation
+    #   RubyTerraform::Commands::WorkspaceSelect.new.execute(
+    #     name: 'example')
+    #
     class WorkspaceSelect < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[workspace select]
       end
 
+      # @!visibility private
       def arguments(parameters)
-        [parameters[:workspace], parameters[:directory]]
-      end
-
-      def parameter_defaults(_parameters)
-        { directory: nil }
+        [parameters[:name], parameters[:directory]]
       end
     end
   end

data/lib/ruby_terraform/commands/workspace_show.rb

@@ -1,13 +1,28 @@
 # frozen_string_literal: true
 
 require_relative 'base'
-require_relative '../options/common'
+require_relative '../options/global'
 
 module RubyTerraform
   module Commands
+    # Wraps the +terraform workspace show+ command which shows the name of the
+    # current workspace.
+    #
+    # For options accepted on construction, see {#initialize}.
+    #
+    # When executing an instance of {WorkspaceSelect} via {#execute}, the
+    # following options are supported:
+    #
+    # * +:chdir+: the path of a working directory to switch to before executing
+    #   the given subcommand.
+    #
+    # @example Basic Invocation
+    #   RubyTerraform::Commands::WorkspaceShow.new.execute
+    #
     class WorkspaceShow < Base
-      include RubyTerraform::Options::Common
+      include RubyTerraform::Options::Global
 
+      # @!visibility private
       def subcommands
         %w[workspace show]
       end

data/lib/ruby_terraform/options.rb

@@ -5,7 +5,7 @@ require_relative 'options/types'
 require_relative 'options/values'
 require_relative 'options/definition'
 require_relative 'options/factory'
-require_relative 'options/common'
+require_relative 'options/global'
 
 module RubyTerraform
   module Options

data/lib/ruby_terraform/options/definition.rb

@@ -16,6 +16,7 @@ module RubyTerraform
       :override_keys,
       :extra_keys,
       :separator,
+      :placement,
       :repeatable?
     )
       # rubocop:disable Metrics/MethodLength
@@ -28,6 +29,7 @@ module RubyTerraform
           value_type: Values.resolve(opts[:value_type]) || Values::String,
           repeatable: opts[:repeatable] || false,
           separator: opts[:separator],
+          placement: opts[:placement],
           extra_keys:
             { singular: [], plural: [] }
               .merge(opts[:extra_keys] || {}),
@@ -97,7 +99,7 @@ module RubyTerraform
       end
 
       def build_option(value)
-        option_type.new(name, value, separator: separator)
+        option_type.new(name, value, separator: separator, placement: placement)
       end
 
       def build_value(value)

data/lib/ruby_terraform/options/definitions.rb

@@ -22,7 +22,7 @@ module RubyTerraform
         end,
 
         # string repeatable options
-        %w[-var-file -target -platform].map do |o|
+        %w[-var-file -target -platform -plugin-dir].map do |o|
           definition(
             name: o, option_type: :standard, value_type: :string,
             repeatable: true
@@ -56,6 +56,7 @@ module RubyTerraform
           -detailed-exitcode
           -diff
           -draw-cycles
+          -dry-run
           -force
           -force-copy
           -ignore-remote-version
@@ -73,14 +74,15 @@ module RubyTerraform
         %w[
           -backup
           -backup-out
-          -chdir
           -from-module
           -fs-mirror
+          -id
           -lock-timeout
+          -lockfile
           -module-depth
           -net-mirror
           -parallelism
-          -plugin-dir
+          -plan
           -provider
           -state
           -state-out
@@ -97,6 +99,13 @@ module RubyTerraform
         definition(
           name: '-out', option_type: :standard, value_type: :string,
           extra_keys: { singular: %i[plan] }
+        ),
+
+        # global options
+        definition(
+          name: '-chdir', option_type: :standard, value_type: :string,
+          placement: :after_command,
+          extra_keys: { singular: %i[working_directory] }
         )
       ].flatten.freeze
   end

data/lib/ruby_terraform/options/{common.rb → global.rb}

@@ -2,7 +2,7 @@
 
 module RubyTerraform
   module Options
-    module Common
+    module Global
       # @!visibility private
       def options
         %w[-chdir]

data/lib/ruby_terraform/options/types.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'types/base'
 require_relative 'types/standard'
 require_relative 'types/flag'
 

data/lib/ruby_terraform/options/types/flag.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
-require_relative 'base'
-require_relative '../values/boolean'
-
 module RubyTerraform
   module Options
     module Types
-      class Flag < Base
+      class Flag < ImmutableStruct.new(
+        :name,
+        :value
+      )
+        def initialize(name, value, **_opts)
+          super(name: name, value: value)
+        end
+
         def apply(builder)
           value.resolve ? builder.with_flag(name) : builder
         end