Merge pull request #59 from DataValues/options

Add `withDefaultOption()` to replace `defaultOption()`
DataValues · Dec 6, 2022 · 7c54a89 · 7c54a89
2 parents d5cfcaf + 3cb96d5
commit 7c54a89
Show file tree

Hide file tree

Showing 5 changed files with 97 additions and 3 deletions.
diff --git a/README.md b/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

diff --git a/src/ValueFormatters/FormatterOptions.php b/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
 	 */

diff --git a/src/ValueParsers/ParserOptions.php b/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
 	 */

diff --git a/tests/ValueFormatters/FormatterOptionsTest.php b/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' );
+	}
+
 }
diff --git a/tests/ValueParsers/ParserOptionsTest.php b/tests/ValueParsers/ParserOptionsTest.php
@@ -45,7 +45,7 @@ public function testConstructorFail() {
 			42 => [ 'o_O', false, null, '42' => 42, [] ]
 		];
 
-		$this->expectException( 'Exception' );
+		$this->expectException( \Exception::class );
 
 		new ParserOptions( $options );
 	}
@@ -117,11 +117,11 @@ public function testSetOption() {
 	 */
 	public function testGetOption( $nonExistingOption ) {
 		$this->assertTrue( true );
-		$formatterOptions = new ParserOptions( [ 'foo' => 'bar' ] );
+		$parserOptions = new ParserOptions( [ 'foo' => 'bar' ] );
 
 		$this->expectException( 'InvalidArgumentException' );
 
-		$formatterOptions->getOption( $nonExistingOption );
+		$parserOptions->getOption( $nonExistingOption );
 	}
 
 	public function nonExistingOptionsProvider() {
@@ -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' );
+	}
+
 }