Add withDefaultOption() to replace defaultOption()

Passing the same mutable options instance around all over the place,
with various parts of the code adding different defaults to it, is a
recipe for confusion and bugs. Discourage it by introducing a new method
that has cloning built into its interface.

README.md

@@ -36,6 +36,12 @@ via Github Actions.
 
 ## Release notes
 
+### 1.1.0 (dev)
+
+* Introduced `ParserOptions::withDefaultOption()` and `FormatterOptions::withDefaultOption()`,
+  which return a copy of the options with the default applied;
+  the `defaultOption()` methods, which modify the options in place, are deprecated.
+
 ### 1.0.0 (2021-01-20)
 
 * Updated minimum required PHP version from 5.5.9 to 7.2

src/ValueFormatters/FormatterOptions.php

@@ -32,6 +32,30 @@ public function __construct( array $options = [] ) {
 		$this->options = $options;
 	}
 
+	/**
+	 * Create and return a copy of these options,
+	 * where the value of an option was set to the provided default
+	 * if it had not been set already.
+	 *
+	 * Example usage:
+	 * ```php
+	 * public function __construct( FormatterOptions $options ) {
+	 *     $this->options = $options
+	 *         ->withDefaultOption( self::OPT_A, 'A' )
+	 *         ->withDefaultOption( self::OPT_B, 'B' );
+	 * }
+	 * ```
+	 *
+	 * @param string $option
+	 * @param mixed $default
+	 * @return self
+	 */
+	public function withDefaultOption( string $option, $default ): self {
+		$options = new self( $this->options );
+		$options->defaultOption( $option, $default );
+		return $options;
+	}
+
 	/**
 	 * Sets the value of the specified option.
 	 *
@@ -75,6 +99,7 @@ public function hasOption( string $option ): bool {
 	/**
 	 * Sets the value of an option to the provided default in case the option is not set yet.
 	 *
+	 * @deprecated Use {@link withDefaultOption()} instead.
 	 * @param string $option
 	 * @param mixed $default
 	 */

src/ValueParsers/ParserOptions.php

@@ -33,6 +33,30 @@ public function __construct( array $options = [] ) {
 		$this->options = $options;
 	}
 
+	/**
+	 * Create and return a copy of these options,
+	 * where the value of an option was set to the provided default
+	 * if it had not been set already.
+	 *
+	 * Example usage:
+	 * ```php
+	 * public function __construct( ParserOptions $options ) {
+	 *     $this->options = $options
+	 *         ->withDefaultOption( self::OPT_A, 'A' )
+	 *         ->withDefaultOption( self::OPT_B, 'B' );
+	 * }
+	 * ```
+	 *
+	 * @param string $option
+	 * @param mixed $default
+	 * @return self
+	 */
+	public function withDefaultOption( string $option, $default ): self {
+		$options = new self( $this->options );
+		$options->defaultOption( $option, $default );
+		return $options;
+	}
+
 	/**
 	 * Sets the value of the specified option.
 	 *
@@ -76,6 +100,7 @@ public function hasOption( string $option ): bool {
 	/**
 	 * Sets the value of an option to the provided default in case the option is not set yet.
 	 *
+	 * @deprecated Use {@link withDefaultOption()} instead.
 	 * @param string $option
 	 * @param mixed $default
 	 */

tests/ValueFormatters/FormatterOptionsTest.php

@@ -191,4 +191,23 @@ public function testDefaultOption() {
 		}
 	}
 
+	public function testWithDefaultOption() {
+		$originalOptions = new FormatterOptions( [ 'foo' => 'foo' ] );
+
+		$newOptions = $originalOptions
+			->withDefaultOption( 'foo', 'FOO' )
+			->withDefaultOption( 'bar', 'BAR' );
+
+		$this->assertNotSame( $originalOptions, $newOptions,
+			'should be a fresh instance' );
+		$this->assertSame( 'foo', $originalOptions->getOption( 'foo' ),
+			'original options should have same non-default option' );
+		$this->assertFalse( $originalOptions->hasOption( 'bar' ),
+			'original options should not have default option' );
+		$this->assertSame( 'foo', $newOptions->getOption( 'foo' ),
+			'new options should have same non-default option' );
+		$this->assertSame( 'BAR', $newOptions->getOption( 'bar' ),
+			'new options should have default option' );
+	}
+
 }

tests/ValueParsers/ParserOptionsTest.php

@@ -191,4 +191,23 @@ public function testDefaultOption() {
 		}
 	}
 
+	public function testWithDefaultOption() {
+		$originalOptions = new ParserOptions( [ 'foo' => 'foo' ] );
+
+		$newOptions = $originalOptions
+			->withDefaultOption( 'foo', 'FOO' )
+			->withDefaultOption( 'bar', 'BAR' );
+
+		$this->assertNotSame( $originalOptions, $newOptions,
+			'should be a fresh instance' );
+		$this->assertSame( 'foo', $originalOptions->getOption( 'foo' ),
+			'original options should have same non-default option' );
+		$this->assertFalse( $originalOptions->hasOption( 'bar' ),
+			'original options should not have default option' );
+		$this->assertSame( 'foo', $newOptions->getOption( 'foo' ),
+			'new options should have same non-default option' );
+		$this->assertSame( 'BAR', $newOptions->getOption( 'bar' ),
+			'new options should have default option' );
+	}
+
 }