pharo-spec / commander2

Flexible implementation of the command design pattern.

Commander 2

Implementation of the command design pattern with the following objectives:

• Simple model of commands
• Ease reusability of commands accross multiple tools / framework
• Instance of commands can be modified (e.g., name, description, etc...)
• Pluging custom user-command made easy

Install

Metacello new
	repository: 'github://pharo-spec/Commander2/src';
	baseline: 'Commander2';
	load

Example

Note: This example is now shipped with the Spec2 integration which is managed by Spec2 project. The code is thus no longer available in this repository.

Commander2-ContactBook package contains an example of Commander2 usage in the context of a Spec application.

The following code should be checked when learning how to use the framework:

• CmContactBookCommand and subclasses are the definition of commands required by the example application.
• CmContactBookPresenter class>>#buildCommandsGroupWith:forRoot: This method is the entry point to describe commands available to your Spec presenter. One can learn how to build group of commands from this method.
• CmContactBookPresenter>>#initializeWidgets This method shows how to inject a Spec's MenuPresenter built from a command group in your presenter.
• CmContactBookPresenter>>#initializeWindow: This method shows how to bind the shortcuts defined by your command group to your Spec presenter.

commander2's Issues

Sometimes we need an icon for register, how to implement that?

Spec related methods on class-side of CmCommand and CmCommandGroup need to be extension methods

Of the spec project's package.

SpCommand>>iconNamed:

should be categorised as internal.
As a user I should use

icon
iconName:
and
iconProvider

Is it correct?

I would remove iconName:from: because I do not see the advantage of
iconProvider:
iconName:

SpBlockCommand>>#canBeRunBlock should be renamed #canBeExecutedBlock

To match the other renamings.

Rename #displayIn:do: to #displayInMenu:do:

To be more explicit.

Should commands be able to change their name dynamically according to context?

Tag integrated version in Pharo

I think we agreed on tagging the versions integrated in Pharo.

I am doing an integration now.

Commit: 3fef319

Changelog since previous integration:

# Commander 2 integration of the 13 of September 2019

## Features 

* Add `#register:after:` and `#register:before:`. ([ad5041c](https://github.com/pharo-spec/Commander2/commit/ad5041cccdd34a7b021ca505323ce6d9a5912480))
* Implemented part of the missing API and implemented corresponding tests. ([5c91fac](https://github.com/pharo-spec/Commander2/commit/5c91facd019e952b993750725bd187f2346db6d9))

## Bug fixes

* Added missing deprecation methods to make transition from v1 to v2 smoother. ([3fef319](https://github.com/pharo-spec/Commander2/commit/3fef31976b6daa4aeef0dcab9f3fcde6a860a484))
* Changed string returned by #defaultDescription to be 'Not described command.' ([71ad574](https://github.com/pharo-spec/Commander2/commit/71ad574eb3af5a88ba2aca47b45f8e7caffc0192))


## Cleanings 

* Preparing for major release, removing deprecated methods we do not want in next major version: - #canBeRun - #canBeRunBlock - #canBeRunBlock: - #defaultCommandName - #runWith: ([3dbd6b1](https://github.com/pharo-spec/Commander2/commit/3dbd6b184d76d1cdd94683b7dc611d5aa531103e))
* Updated baseline to be more flexible. - Do not provide migrator in default group. - Provide core,test and migrator groups. ([7a7491b](https://github.com/pharo-spec/Commander2/commit/7a7491b8ed4a6925d836922e0b84d683caa4799e))
* Enhanced comment. ([8379fb3](https://github.com/pharo-spec/Commander2/commit/8379fb34a40826e8b3681bf2ede30696a656b9f8))
* Did migration with the following renamings (order is important): #name -> #dynamicName. #description -> #dynamicDescription. #basicName -> #name. #basicDescription -> #description. ([1a8f4e8](https://github.com/pharo-spec/Commander2/commit/1a8f4e8a1b7da5bdcc44c2a1d952557a71b6f351))
* wrap environment into RBNamespace. ([723cddd](https://github.com/pharo-spec/Commander2/commit/723cdddb42780305a6366660d0fc40ad8bec6623))
* Put #runWith: in deprecations package. ([cc9025d](https://github.com/pharo-spec/Commander2/commit/cc9025d89b168ba2159b4db610ff00c2dff707f8))
* Removed #runWith: ([c78dd09](https://github.com/pharo-spec/Commander2/commit/c78dd0977727ad2dc103c36ac326d18520f247e4))
* Renamed #defaultCommandName as #defaultName. Used deprecation. ([c1bad44](https://github.com/pharo-spec/Commander2/commit/c1bad4407a55e654b0183005c885289177dc0b04))
* Renamed #canBeRunBlock as #canBeExecutedBlock via a deprecation. ([5a87a11](https://github.com/pharo-spec/Commander2/commit/5a87a1185e071990dd2c684444e7931faa25b67d))
* Moved spec related methods in class-side of CmCommandGroup to spec package. ([4ae2f84](https://github.com/pharo-spec/Commander2/commit/4ae2f8478b2b59d9051bdb1a65ca2b4a0d8eee18))
* Moved spec-specific methods on class side of CmCommand to Spec integration package. ([11d7997](https://github.com/pharo-spec/Commander2/commit/11d799799ec055d5113ccf589f42cf58822ab322))
* Renamed #canBeRun as #canBeExecuted to be more consistent. Created a deprecation to ease migration of users. ([152e6a7](https://github.com/pharo-spec/Commander2/commit/152e6a72261a8f1f6fb4e9ad579a199b73dba036))
* Reclassified all #canBeRun methods in 'testing' protocol. ([813cda2](https://github.com/pharo-spec/Commander2/commit/813cda255f8a0cc6df592bbe22d5f26850fbcb31))
* Reclassified #execute methods in 'executing' protocol. Brings consistence and solves issue #9 ([19c1ee0](https://github.com/pharo-spec/Commander2/commit/19c1ee0db83830abe3ee68ea0a11581765e90df6))
* Renaming of CmCommandGroupTest to CmCommandsGroupTest. ([5f20942](https://github.com/pharo-spec/Commander2/commit/5f20942c03cbb529b285883d9d1c9db2c870c942))
* Renamed test class to match class under test. ([8ab2c3b](https://github.com/pharo-spec/Commander2/commit/8ab2c3bb15b664b2cfa46ade33d1e4d656f40741))

#canBeRun is not consistent with #execute

Should be renamed as #canBeExecuted.

Overriding #asSpecCommand to define default shortcut and icon is good practice?

shortcutKey: what is the type of the argument?

I see

shortcutKey: aString
shortcutKey := aString

and users use

asSpecCommand
"Here we define the additional information the command will need to know
when used in the Spec framework.
"
^ super asSpecCommand
shortcutKey: $n meta;
yourself

weird to use basic** to set command properties

In a command, you need to use #basicName: and #basicDescription: to set the static (as opposed to dynamic) properties of a command.
It looks strange that users have to often use a method looking as a low level method (starts with basic). I would rather use #name: and #description: and find a new name for the dynamic part.

add convenience method to instantiate a command on a given context

It could be useful in tests to avoid:

(MyCommand new
   context: aTestContext;
  yourself)

It would become:

MyCommand on: aTestContext

add asMenuBarPresenter

We need a menu bar presenter to decorate windows.

Use special notification to inform user from command

could be a InformNotification subclass of Notification that would be caught by the decorator.

Implement a library of generic commands that can be reused everywhere

• Inspect
• Browse
• Copy
• Cut
• Past
  etc.

add asToolBarPresenter

we need it to decorate windows with toolbars ;)

Rename CmAbstractCommandsGroup as CmAbstractCommandGroup

use better categorie for #execute

In a command, #execute should be classified in a protocol like executing / running

Rename SpToolBarPresenterBuilder into SpToolbarPresenterBuilder?

Since we use everywhere toolbar?
Let me know because I will have to redo the code and graffle.

Implement possibility to revert command

It can be via creating a #revert method on CmCommand.

By default, this method would return a CanNotBeReverted exception.

If we have this feature, we can implement an history manager.

Provide possibility to create sequence of commands

Let's say you have:

• Connect command
• Inspect command

which take the same context

it would be handy to be able to create a composite command which is a sequence of these two commands "Connect and Inspect".

If the DSL to create sequence is nice, it could be super elegant:

group
    register: (Connect , Inspect) forSpec