diff --git a/packages/core/README.md b/packages/core/README.md index 864d577e..cbb9cfcc 100644 --- a/packages/core/README.md +++ b/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'); diff --git a/packages/core/__tests__/core.test.ts b/packages/core/__tests__/core.test.ts index a069e89c..a1ebfd7b 100644 --- a/packages/core/__tests__/core.test.ts +++ b/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([ diff --git a/packages/core/src/core.ts b/packages/core/src/core.ts index 13f4dfa3..1822bf93 100644 --- a/packages/core/src/core.ts +++ b/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. *