feat(core): add getBooleanInput function (#725)

* feat(core): add getBooleanInput function

* docs(core): update readme

* test(core): update the core.test.ts

packages/core/README.md

@@ -16,11 +16,13 @@ import * as core from '@actions/core';
 
 #### Inputs/Outputs
 
-Action inputs can be read with `getInput`.  Outputs can be set with `setOutput` which makes them available to be mapped into inputs of other actions to ensure they are decoupled.
+Action inputs can be read with `getInput` which returns a `string` or `getBooleanInput` which parses a boolean based on the [yaml 1.2 specification](https://yaml.org/spec/1.2/spec.html#id2804923). If `required` set to be false, the input should have a default value in `action.yml`.
+
+Outputs can be set with `setOutput` which makes them available to be mapped into inputs of other actions to ensure they are decoupled.
 
 ```js
 const myInput = core.getInput('inputName', { required: true });
-
+const myBooleanInput = core.getBooleanInput('booleanInputName', { required: true });
 core.setOutput('outputKey', 'outputVal');
 ```
 
@@ -66,7 +68,6 @@ catch (err) {
 
 Note that `setNeutral` is not yet implemented in actions V2 but equivalent functionality is being planned.
 
-
 #### Logging
 
 Finally, this library provides some utilities for logging. Note that debug logging is hidden from the logs by default. This behavior can be toggled by enabling the [Step Debug Logs](../../docs/action-debugging.md#step-debug-logs).
@@ -118,6 +119,7 @@ const result = await core.group('Do something async', async () => {
 Colored output is supported in the Action logs via standard [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code). 3/4 bit, 8 bit and 24 bit colors are all supported.
 
 Foreground colors:
+
 ```js
 // 3/4 bit
 core.info('\u001b[35mThis foreground will be magenta')
@@ -130,6 +132,7 @@ core.info('\u001b[38;2;255;0;0mThis foreground will be bright red')
 ```
 
 Background colors:
+
 ```js
 // 3/4 bit
 core.info('\u001b[43mThis background will be yellow');
@@ -156,6 +159,7 @@ core.info('\u001b[31;46mRed foreground with a cyan background and \u001b[1mbold
 ```
 
 > Note: Escape codes reset at the start of each line
+
 ```js
 core.info('\u001b[35mThis foreground will be magenta')
 core.info('This foreground will reset to the default')
@@ -170,9 +174,10 @@ core.info(style.color.ansi16m.hex('#abcdef') + 'Hello world!')
 
 #### Action state
 
-You can use this library to save state and get state for sharing information between a given wrapper action: 
+You can use this library to save state and get state for sharing information between a given wrapper action:
+
+**action.yml**:
 
-**action.yml**
 ```yaml
 name: 'Wrapper action sample'
 inputs:
@@ -193,6 +198,7 @@ core.saveState("pidToKill", 12345);
 ```
 
 In action's `cleanup.js`:
+
 ```js
 const core = require('@actions/core');
 

packages/core/__tests__/core.test.ts

@@ -19,6 +19,14 @@ const testEnvVars = {
   INPUT_MISSING: '',
   'INPUT_SPECIAL_CHARS_\'\t"\\': '\'\t"\\ response ',
   INPUT_MULTIPLE_SPACES_VARIABLE: 'I have multiple spaces',
+  INPUT_BOOLEAN_INPUT: 'true',
+  INPUT_BOOLEAN_INPUT_TRUE1: 'true',
+  INPUT_BOOLEAN_INPUT_TRUE2: 'True',
+  INPUT_BOOLEAN_INPUT_TRUE3: 'TRUE',
+  INPUT_BOOLEAN_INPUT_FALSE1: 'false',
+  INPUT_BOOLEAN_INPUT_FALSE2: 'False',
+  INPUT_BOOLEAN_INPUT_FALSE3: 'FALSE',
+  INPUT_WRONG_BOOLEAN_INPUT: 'wrong',
 
   // Save inputs
   STATE_TEST_1: 'state_val',
@@ -157,6 +165,30 @@ describe('@actions/core', () => {
     )
   })
 
+  it('getInput gets non-required boolean input', () => {
+    expect(core.getBooleanInput('boolean input')).toBe(true)
+  })
+
+  it('getInput gets required input', () => {
+    expect(core.getBooleanInput('boolean input', {required: true})).toBe(true)
+  })
+
+  it('getBooleanInput handles boolean input', () => {
+    expect(core.getBooleanInput('boolean input true1')).toBe(true)
+    expect(core.getBooleanInput('boolean input true2')).toBe(true)
+    expect(core.getBooleanInput('boolean input true3')).toBe(true)
+    expect(core.getBooleanInput('boolean input false1')).toBe(false)
+    expect(core.getBooleanInput('boolean input false2')).toBe(false)
+    expect(core.getBooleanInput('boolean input false3')).toBe(false)
+  })
+
+  it('getBooleanInput handles wrong boolean input', () => {
+    expect(() => core.getBooleanInput('wrong boolean input')).toThrow(
+      'Input does not meet YAML 1.2 "Core Schema" specification: wrong boolean input\n' +
+        `Support boolean input list: \`true | True | TRUE | false | False | FALSE\``
+    )
+  })
+
   it('setOutput produces the correct command', () => {
     core.setOutput('some output', 'some value')
     assertWriteCalls([

packages/core/src/core.ts

@@ -91,6 +91,28 @@ export function getInput(name: string, options?: InputOptions): string {
   return val.trim()
 }
 
+/**
+ * Gets the input value of the boolean type in the YAML 1.2 "core schema" specification.
+ * Support boolean input list: `true | True | TRUE | false | False | FALSE` .
+ * The return value is also in boolean type.
+ * ref: https://yaml.org/spec/1.2/spec.html#id2804923
+ *
+ * @param     name     name of the input to get
+ * @param     options  optional. See InputOptions.
+ * @returns   boolean
+ */
+export function getBooleanInput(name: string, options?: InputOptions): boolean {
+  const trueValue = ['true', 'True', 'TRUE']
+  const falseValue = ['false', 'False', 'FALSE']
+  const val = getInput(name, options)
+  if (trueValue.includes(val)) return true
+  if (falseValue.includes(val)) return false
+  throw new TypeError(
+    `Input does not meet YAML 1.2 "Core Schema" specification: ${name}\n` +
+      `Support boolean input list: \`true | True | TRUE | false | False | FALSE\``
+  )
+}
+
 /**
  * Sets the value of an output.
  *