From 837c6bd1c2924162dac96913ff28edd3f554f813 Mon Sep 17 00:00:00 2001 From: Snarling <84951833+Snarling@users.noreply.github.com> Date: Mon, 28 Nov 2022 09:15:09 -0500 Subject: [PATCH] CONTRACT: codingcontract.attempt always returns a string (#231) * ns.codingcontract always returns a string (reward on success, empty on fail), simplifying usage and documentation of function. * Because of the above, return value still works when used as a boolean, as long as no direct equality comparison to true/false. * Documentation expanded and examples added. Co-authored by @quacksouls --- dist/bitburner.d.ts | 43 ++++++++++--------- markdown/bitburner.codingattemptoptions.md | 20 --------- ...urner.codingattemptoptions.returnreward.md | 13 ------ markdown/bitburner.codingcontract.attempt.md | 38 +++++++++++----- markdown/bitburner.codingcontract.md | 2 +- markdown/bitburner.md | 1 - src/NetscriptFunctions/CodingContract.ts | 14 +++--- src/ScriptEditor/NetscriptDefinitions.d.ts | 43 ++++++++++--------- 8 files changed, 80 insertions(+), 94 deletions(-) delete mode 100644 markdown/bitburner.codingattemptoptions.md delete mode 100644 markdown/bitburner.codingattemptoptions.returnreward.md diff --git a/dist/bitburner.d.ts b/dist/bitburner.d.ts index a367eec97..a65fbd25b 100644 --- a/dist/bitburner.d.ts +++ b/dist/bitburner.d.ts @@ -651,39 +651,42 @@ export declare interface BladeburnerCurAction { name: string; } -/** - * Options to affect the behavior of {@link CodingContract} attempt. - * @public - */ -export declare interface CodingAttemptOptions { - /** If truthy, then the function will return a string that states the contract’s reward when it is successfully solved. */ - returnReward: boolean; -} - /** * Coding Contract API * @public */ export declare interface CodingContract { /** - * Attempts a coding contract. + * Attempts a coding contract, returning a reward string on success or empty string on failure. * @remarks * RAM cost: 10 GB * * Attempts to solve the Coding Contract with the provided solution. * - * @param answer - Solution for the contract. + * @example + * ```js + * // NS1 + * var reward = codingcontract.attempt(yourSolution, filename, hostname); + * if (reward) { + * tprint("Contract solved successfully! Reward: " + reward) + * } else tprint("Failed to solve contract.") + * ``` + * @example + * ```js + * // NS2 + * const reward = codingcontract.attempt(yourSolution, filename, hostname); + * if (reward) { + * ns.tprint(`Contract solved successfully! Reward: ${reward}`) + * } else ns.tprint("Failed to solve contract.") + * ``` + * + * @param answer - Attempted solution for the contract. * @param filename - Filename of the contract. - * @param host - Hostname of the server containing the contract. Optional. Defaults to current server if not provided. - * @param opts - Optional parameters for configuring function behavior. - * @returns True if the solution was correct, false otherwise. If the returnReward option is configured, then the function will instead return a string. If the contract is successfully solved, the string will contain a description of the contract’s reward. Otherwise, it will be an empty string. + * @param host - Hostname of the server containing the contract. Optional. Defaults to current server if not + * provided. + * @returns A reward description string on success, or an empty string on failure. */ - attempt( - answer: string | number | any[], - filename: string, - host?: string, - opts?: CodingAttemptOptions, - ): boolean | string; + attempt(answer: string | number | any[], filename: string, host?: string): string; /** * Get the type of a coding contract. diff --git a/markdown/bitburner.codingattemptoptions.md b/markdown/bitburner.codingattemptoptions.md deleted file mode 100644 index f8b5bca22..000000000 --- a/markdown/bitburner.codingattemptoptions.md +++ /dev/null @@ -1,20 +0,0 @@ - - -[Home](./index.md) > [bitburner](./bitburner.md) > [CodingAttemptOptions](./bitburner.codingattemptoptions.md) - -## CodingAttemptOptions interface - -Options to affect the behavior of [CodingContract](./bitburner.codingcontract.md) attempt. - -Signature: - -```typescript -interface CodingAttemptOptions -``` - -## Properties - -| Property | Type | Description | -| --- | --- | --- | -| [returnReward](./bitburner.codingattemptoptions.returnreward.md) | boolean | If truthy, then the function will return a string that states the contract’s reward when it is successfully solved. | - diff --git a/markdown/bitburner.codingattemptoptions.returnreward.md b/markdown/bitburner.codingattemptoptions.returnreward.md deleted file mode 100644 index f97ed6959..000000000 --- a/markdown/bitburner.codingattemptoptions.returnreward.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [bitburner](./bitburner.md) > [CodingAttemptOptions](./bitburner.codingattemptoptions.md) > [returnReward](./bitburner.codingattemptoptions.returnreward.md) - -## CodingAttemptOptions.returnReward property - -If truthy, then the function will return a string that states the contract’s reward when it is successfully solved. - -Signature: - -```typescript -returnReward: boolean; -``` diff --git a/markdown/bitburner.codingcontract.attempt.md b/markdown/bitburner.codingcontract.attempt.md index 7737da8fa..8372562f2 100644 --- a/markdown/bitburner.codingcontract.attempt.md +++ b/markdown/bitburner.codingcontract.attempt.md @@ -4,33 +4,27 @@ ## CodingContract.attempt() method -Attempts a coding contract. +Attempts a coding contract, returning a reward string on success or empty string on failure. Signature: ```typescript -attempt( - answer: string | number | any[], - filename: string, - host?: string, - opts?: CodingAttemptOptions, - ): boolean | string; +attempt(answer: string | number | any[], filename: string, host?: string): string; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| answer | string \| number \| any\[\] | Solution for the contract. | +| answer | string \| number \| any\[\] | Attempted solution for the contract. | | filename | string | Filename of the contract. | | host | string | Hostname of the server containing the contract. Optional. Defaults to current server if not provided. | -| opts | [CodingAttemptOptions](./bitburner.codingattemptoptions.md) | Optional parameters for configuring function behavior. | Returns: -boolean \| string +string -True if the solution was correct, false otherwise. If the returnReward option is configured, then the function will instead return a string. If the contract is successfully solved, the string will contain a description of the contract’s reward. Otherwise, it will be an empty string. +A reward description string on success, or an empty string on failure. ## Remarks @@ -38,3 +32,25 @@ RAM cost: 10 GB Attempts to solve the Coding Contract with the provided solution. +## Example 1 + + +```js +// NS1 +var reward = codingcontract.attempt(yourSolution, filename, hostname); +if (reward) { + tprint("Contract solved successfully! Reward: " + reward) +} else tprint("Failed to solve contract.") +``` + +## Example 2 + + +```js +// NS2 +const reward = codingcontract.attempt(yourSolution, filename, hostname); +if (reward) { + ns.tprint(`Contract solved successfully! Reward: ${reward}`) +} else ns.tprint("Failed to solve contract.") +``` + diff --git a/markdown/bitburner.codingcontract.md b/markdown/bitburner.codingcontract.md index 1f1bf1ed3..ed16e523f 100644 --- a/markdown/bitburner.codingcontract.md +++ b/markdown/bitburner.codingcontract.md @@ -16,7 +16,7 @@ export interface CodingContract | Method | Description | | --- | --- | -| [attempt(answer, filename, host, opts)](./bitburner.codingcontract.attempt.md) | Attempts a coding contract. | +| [attempt(answer, filename, host)](./bitburner.codingcontract.attempt.md) | Attempts a coding contract, returning a reward string on success or empty string on failure. | | [createDummyContract(type)](./bitburner.codingcontract.createdummycontract.md) | Generate a dummy contract. | | [getContractType(filename, host)](./bitburner.codingcontract.getcontracttype.md) | Get the type of a coding contract. | | [getContractTypes()](./bitburner.codingcontract.getcontracttypes.md) | List all contract types. | diff --git a/markdown/bitburner.md b/markdown/bitburner.md index e1ace781c..6f3c0c0e3 100644 --- a/markdown/bitburner.md +++ b/markdown/bitburner.md @@ -31,7 +31,6 @@ | [BitNodeMultipliers](./bitburner.bitnodemultipliers.md) | All multipliers affecting the difficulty of the current challenge. | | [Bladeburner](./bitburner.bladeburner.md) | Bladeburner API | | [BladeburnerCurAction](./bitburner.bladeburnercuraction.md) | Bladeburner current action. | -| [CodingAttemptOptions](./bitburner.codingattemptoptions.md) | Options to affect the behavior of [CodingContract](./bitburner.codingcontract.md) attempt. | | [CodingContract](./bitburner.codingcontract.md) | Coding Contract API | | [Corporation](./bitburner.corporation.md) | Corporation API | | [CorporationInfo](./bitburner.corporationinfo.md) | General info about a corporation | diff --git a/src/NetscriptFunctions/CodingContract.ts b/src/NetscriptFunctions/CodingContract.ts index 3336fa7bc..cbd91a712 100644 --- a/src/NetscriptFunctions/CodingContract.ts +++ b/src/NetscriptFunctions/CodingContract.ts @@ -1,8 +1,8 @@ import { Player as player } from "../Player"; import { CodingContract } from "../CodingContracts"; -import { CodingAttemptOptions, CodingContract as ICodingContract } from "../ScriptEditor/NetscriptDefinitions"; +import { CodingContract as ICodingContract } from "../ScriptEditor/NetscriptDefinitions"; import { InternalAPI, NetscriptContext } from "../Netscript/APIWrapper"; -import { helpers, assertObjectType } from "../Netscript/NetscriptHelpers"; +import { helpers } from "../Netscript/NetscriptHelpers"; import { codingContractTypesMetadata } from "../data/codingcontracttypes"; import { generateDummyContract } from "../CodingContractGenerator"; @@ -18,18 +18,16 @@ export function NetscriptCodingContract(): InternalAPI { }; return { - attempt: (ctx) => (answer, _filename, _hostname?, opts?) => { + attempt: (ctx) => (answer, _filename, _hostname?) => { const filename = helpers.string(ctx, "filename", _filename); const hostname = _hostname ? helpers.string(ctx, "hostname", _hostname) : ctx.workerScript.hostname; const contract = getCodingContract(ctx, hostname, filename); - const optsValidator: CodingAttemptOptions = { returnReward: true }; - opts ??= optsValidator; - assertObjectType(ctx, "opts", opts, optsValidator); if (typeof answer !== "number" && typeof answer !== "string" && !Array.isArray(answer)) throw new Error("The answer provided was not a number, string, or array"); // Convert answer to string. + // Todo: better typing for contracts, don't do this weird string conversion of the player answer const answerStr = typeof answer === "string" ? answer : JSON.stringify(answer); const creward = contract.reward; @@ -38,7 +36,7 @@ export function NetscriptCodingContract(): InternalAPI { const reward = player.gainCodingContractReward(creward, contract.getDifficulty()); helpers.log(ctx, () => `Successfully completed Coding Contract '${filename}'. Reward: ${reward}`); serv.removeContract(filename); - return opts.returnReward ? reward : true; + return reward; } else { ++contract.tries; if (contract.tries >= contract.getMaxNumTries()) { @@ -54,7 +52,7 @@ export function NetscriptCodingContract(): InternalAPI { ); } - return opts.returnReward ? "" : false; + return ""; } }, getContractType: (ctx) => (_filename, _hostname?) => { diff --git a/src/ScriptEditor/NetscriptDefinitions.d.ts b/src/ScriptEditor/NetscriptDefinitions.d.ts index e42295e10..ad78cd053 100644 --- a/src/ScriptEditor/NetscriptDefinitions.d.ts +++ b/src/ScriptEditor/NetscriptDefinitions.d.ts @@ -250,15 +250,6 @@ interface BasicHGWOptions { stock?: boolean; } -/** - * Options to affect the behavior of {@link CodingContract} attempt. - * @public - */ -interface CodingAttemptOptions { - /** If truthy, then the function will return a string that states the contract’s reward when it is successfully solved. */ - returnReward: boolean; -} - /** * Return value of {@link Sleeve.getSleevePurchasableAugs | getSleevePurchasableAugs} * @public @@ -3149,24 +3140,36 @@ export interface Bladeburner { */ export interface CodingContract { /** - * Attempts a coding contract. + * Attempts a coding contract, returning a reward string on success or empty string on failure. * @remarks * RAM cost: 10 GB * * Attempts to solve the Coding Contract with the provided solution. * - * @param answer - Solution for the contract. + * @example + * ```js + * // NS1 + * var reward = codingcontract.attempt(yourSolution, filename, hostname); + * if (reward) { + * tprint("Contract solved successfully! Reward: " + reward) + * } else tprint("Failed to solve contract.") + * ``` + * @example + * ```js + * // NS2 + * const reward = codingcontract.attempt(yourSolution, filename, hostname); + * if (reward) { + * ns.tprint(`Contract solved successfully! Reward: ${reward}`) + * } else ns.tprint("Failed to solve contract.") + * ``` + * + * @param answer - Attempted solution for the contract. * @param filename - Filename of the contract. - * @param host - Hostname of the server containing the contract. Optional. Defaults to current server if not provided. - * @param opts - Optional parameters for configuring function behavior. - * @returns True if the solution was correct, false otherwise. If the returnReward option is configured, then the function will instead return a string. If the contract is successfully solved, the string will contain a description of the contract’s reward. Otherwise, it will be an empty string. + * @param host - Hostname of the server containing the contract. Optional. Defaults to current server if not + * provided. + * @returns A reward description string on success, or an empty string on failure. */ - attempt( - answer: string | number | any[], - filename: string, - host?: string, - opts?: CodingAttemptOptions, - ): boolean | string; + attempt(answer: string | number | any[], filename: string, host?: string): string; /** * Get the type of a coding contract.