Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Factory routine to create a new unattached argument #1497

Merged
merged 6 commits into from
Apr 12, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion esm.mjs
Original file line number Diff line number Diff line change
@@ -1,4 +1,15 @@
import commander from './index.js';

// wrapper to provide named exports for ESM.
export const { program, Option, Command, Argument, CommanderError, InvalidOptionArgumentError, Help, createCommand, createOption } = commander;
export const {
program,
createCommand,
createArgument,
createOption,
CommanderError,
InvalidOptionArgumentError,
Command,
Argument,
Option,
Help
} = commander;
17 changes: 16 additions & 1 deletion index.js
Original file line number Diff line number Diff line change
Expand Up @@ -836,6 +836,21 @@ class Command extends EventEmitter {
return this;
};

/**
* Factory routine to create a new unattached argument.
*
* See .argument() for creating an attached argument, which uses this routine to
* create the argument. You can override createArgument to return a custom argument.
*
* @param {string} name
* @param {string} [description]
* @return {Argument} new argument
*/

createArgument(name, description) {
return new Argument(name, description);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are the benefits of adding this factory when you can use new Argument() directly?

Copy link
Collaborator

@shadowspawn shadowspawn Apr 12, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The main purpose is so you can override the method and return a custom subclass of Argument, which will be used to create the arguments added by Command methods .argument() and .arguments() and .command('sub <file>').

This factory pattern was first offered with .createCommand() where it is more likely to be used, but offering the same pattern for Option and now Argument.

Copy link
Contributor

@Niryo Niryo Apr 12, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But why will you want to override the createArgument method when you can just pass any custom Argument class to addArgument?
Also, in order to create custom argument, you need to somewhat know the internals of the Argument class (in both the factory solution and the direct solution), so it sounds like a bad practice and a doc bloater, for probably a really rare use case. Instead of adding this factory to keep the the api aligned, I would consider removing all other factories...

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.createCommand() was the first one added in #1191 to make Command more subclass friendly. .createHelp() was added in major help refactor in #1365.

.createOption() was added in #1380 to follow the pattern. We had established a tidy pattern for Command which also worked for Help, so following through and offering same support for Option.

in order to create custom argument, you need to somewhat know the internals of the Argument class

Yes, that is implicit in writing a subclass.

I did consider whether to directly support subclassing at all for Command, but it a useful approach for extending functionality especially in custom cases which are not common use cases and would not be integrated into Commander itself.

};

/**
* Define argument syntax for command.
*
Expand All @@ -852,7 +867,7 @@ class Command extends EventEmitter {
* @return {Command} `this` command for chaining
*/
argument(name, description) {
const argument = new Argument(name, description);
const argument = this.createArgument(name, description);
this.addArgument(argument);
return this;
}
Expand Down
40 changes: 40 additions & 0 deletions tests/command.createArgument.test.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
const commander = require('../');

class MyArgument extends commander.Argument {
constructor(name, description) {
super(name, description);
this.myProperty = 'MyArgument';
};
}

class MyCommand extends commander.Command {
createArgument(name, description) {
return new MyArgument(name, description);
};

// createCommand for testing .command('sub <file>')
createCommand(name) {
return new MyCommand(name);
}
}

test('when override createArgument then used for argument()', () => {
const program = new MyCommand();
program.argument('<file>');
expect(program._args.length).toEqual(1);
expect(program._args[0].myProperty).toEqual('MyArgument');
});

test('when override createArgument then used for arguments()', () => {
const program = new MyCommand();
program.arguments('<file>');
expect(program._args.length).toEqual(1);
expect(program._args[0].myProperty).toEqual('MyArgument');
});

test('when override createArgument and createCommand then used for argument of command()', () => {
const program = new MyCommand();
const sub = program.command('sub <file>');
expect(sub._args.length).toEqual(1);
expect(sub._args[0].myProperty).toEqual('MyArgument');
});
4 changes: 3 additions & 1 deletion tests/esm-imports-test.mjs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { program, Command, Option, Argument, CommanderError, InvalidOptionArgumentError, Help, createCommand, createOption } from '../esm.mjs';
import { program, Command, Option, Argument, CommanderError, InvalidOptionArgumentError, Help, createCommand, createArgument, createOption } from '../esm.mjs';

// Do some simple checks that expected imports are available at runtime.
// Run using `npm run test-esm`.
Expand Down Expand Up @@ -30,6 +30,8 @@ checkClass(new Argument('<file>'), 'Argument');

console.log('Checking createCommand');
check(typeof createCommand === 'function', 'createCommand is function');
console.log('Checking createArgument');
check(typeof createArgument === 'function', 'createArgument is function');
console.log('Checking createOption');
check(typeof createOption === 'function', 'createOption is function');

Expand Down
8 changes: 8 additions & 0 deletions typings/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,14 @@ declare namespace commander {
*/
addCommand(cmd: Command, opts?: CommandOptions): this;

/**
* Factory routine to create a new unattached argument.
*
* See .argument() for creating an attached argument, which uses this routine to
* create the argument. You can override createArgument to return a custom argument.
*/
createArgument(name: string, description?: string): Argument;

/**
* Define argument syntax for command.
*
Expand Down
4 changes: 4 additions & 0 deletions typings/index.test-d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -345,3 +345,7 @@ expectType<boolean>(baseArgument.variadic);
// Argument methods
// name
expectType<string>(baseArgument.name());

// createArgument
expectType<commander.Argument>(program.createArgument('<name>'));
expectType<commander.Argument>(program.createArgument('<name>', 'description'));