- Calypso is an underhood navigation environment for Pharo and RMod built around first class scopes, queries, and query results. - It uses cursors to access query results, which cache portions of the result and load more on demand. Cursors also provide a subsequent query API. - Navigation views in the browser are based on fast tables with a custom data source using the cursor. This allows only the visible portion of the result to be requested from the cursor.

1. Calypso underhood
http://pharo.org
http://rmod.inria.fr
Denis Kudriashov dionisiydk@gmail.com https://github.com/dionisiydk/Calypso

2. Navigation model
• First class scopes
• PackageScope
• ClassScope
• MethodScope

3. First class scopes
• Select scope from navigation environment
scope := ClySystemNavigationEnvironment currentImage
selectScope: ClyClassScope of: {Collection. Set}
• SystemScope represents global environment space
ClySystemNavigationEnvironment currentImageScope

4. Navigation model
• First class scopes
• First class queries
• MessageSenders
• ClassReferences

5. First class queries
• Evaluate query in scope
scope query: (ClyMessageSenders of: #(do:))
scope query: (ClyMessageImplementors of: #(do:))

6. Navigation model
• First class scopes
• First class queries
• First class query results
• SortedClasses
• HierarchicallySortedClasses

7. First class query results
• Specify what kind of result should be built by query
scope query: (ClyMessageSenders of: #(do:) as: ClyHierarchicallySortedMethods)
• Retrieve all available items with simple query
scope query: ClySortedMethods
scope query: ClyHierarchicallySortedMethods

8. Navigation model
• First class scopes
• First class queries
• First class query results
• Query result is accessed by cursor instance

9. Any query returns cursor
• Cursor provides stream access to underlying query
result
• caches portion of result items
• loads new portion on demand
• only cached items compute properties
• In remote scenario only cursor with cached items is
transferred to client

10. Cursor provides subsequent
query API
packageCursor := ClySystemNavigationEnvironment
queryCurrentImageFor: ClySortedPackages.
classCursor := packageCursor query: ClySortedClasses from: {#Kernel asPackage}.
classCursor := classesCursor query: ClyHierarchicallySortedClasses.
classCursor := classesCursor queryContentInScopeWith: 'AST-Core' asPackage.
classCursor := classesCursor queryContentInScopeWithout: 'Kernel' asPackage.
methodCursor := classCursor query: ClySortedMethods from: {Point. Array}.
methodCursor := methodCursor queryContentInNewScope: ClyClassSideScope.

11. Browser navigation state
• Cursors incapsulate main navigation state of the browser:
• what kind of query it represents
• method group mode or variable mode
• in what scope result is shown
• instance side or class side
• inherited method visibility
• what kind of result is used
• flat methods or hierarchical methods

12. Browser navigation state
• No special flags like in old browser

13. Navigation model
• First class scopes
• First class queries
• First class query results
• Query result is accessed by cursor instance
• Result items wrap and extend actual objects
(classes, methods) with properties

14. Actual query result is
collection of environment items
• Environment item wraps actual object and extends it with properties:
• position in query result
• depth in query result
• domain specific properties
• ClyAbstractClassTag
• ClyOverridenMethodTag
• Environment plugins can extend properties of particular items
• ClyInheritanceAnalyzerEnvironmentPlugin marks abstract classes with
ClyAbstractClassTag
• Properties are computed lazily for portion of requested items
• it can be slow to retrieve them

15. Navigation model
• First class scopes
• First class queries
• First class query results
• Query result is accessed by cursor instance
• Result items wrap and extend actual objects
(classes, methods) with properties

16. Browser navigation views
• All navigation views are based on fast table
• Special data source based on cursor
• Only visible part of table is requested from cursor
• which is covered by cursor cache
• Data source describes tree structure
• what query to use to expand each kind of item

17. Browser navigation views
cursor := ClySystemNavigationEnvironment
queryCurrentImageFor: ClySortedPackages.
dataSource := ClyCollapsedDataSource on: cursor.
dataSource childrenStructure: {
ClyPackageScope -> ClySortedClassGroups.
ClyClassGroupScope -> ClyHierarchicallySortedClasses}.
table := FTTableMorph new.
table
extent: 200 @ 400;
dataSource: dataSource;
openInWindow.

18. Browser navigation views
cursor := ClySystemNavigationEnvironment
queryCurrentImageFor: ClySortedPackages.
dataSource := ClyCollapsedDataSource on: cursor.
dataSource childrenStructure: {
ClyPackageScope -> ClySortedClassGroups.
ClyClassGroupScope -> ClyHierarchicallySortedClasses}.
table := FTTableMorph new.
table
extent: 200 @ 400;
dataSource: dataSource;
openInWindow.
Demo

19. Browser item selection
• First class selection represents selected objects
• ClyDataSourceSelection represents manually selected items
• ClyDataSourceHighlighting represents highlighted items
• to highlight groups of selected methods
• ClyDesiredSelection responsible to restore selected items
when data source is changed
• automatic selection of same method when new class
selected
• Selections maintain correct visible state after any changes

20. Navigation history
• Collection of browser states
• state of all navigation views
• data source detached from model
• selection
• active tabs
• window to support across window navigation
• Specific browser state
• list of scopes in method browser

21. How extend browser?
• Commands

22. Commander
• Calypso commands are based on Commander
• Every command is first class object subclass of CmdCommand with execute method
• Multiple activators can be attached to command class to declare specific way to
access command from particular application context
• CmdContextMenuCommandActivator
• CmdShortcutCommandActivator
• CmdDragAndDropCommandActivator
• ClyToolbarCommandActivator (for elements from browser toolbar)
• ClyTableIconCommandActivator (to support method icons of Nautilus)
• More http://dionisiydk.blogspot.fr/2017/04/commander-command-pattern-library.html

23. Command example
RenamePackageCommand>>execute
package renameTo: newName
RenamePackageCommand class>>systemBrowserShortcutActivator
<commandActivator>
^CmdShortcutCommandActivator by: $r meta for: ClyPackageSystemBrowserContext
RenamePackageCommand class>>systemBrowserMenuActivator
<commandActivator>
^CmdContextMenuCommandActivator byRootGroupItemFor: ClyPackageSystemBrowserContext
RenamePackageCommand>>defaultMenuItemName
^'Rename'

24. Command example
RenamePackageCommand>>prepareFullExecutionInContext: aToolContext
super prepareFullExecutionInContext: aToolContext.
package := aToolContext lastSelectedPackage.
newName := UIManager default
request: 'New name of the package'
initialAnswer: package name
title: 'Rename a package'.
newName isEmptyOrNil | (newName = package name)
ifTrue: [ ^ CmdCommandAborted signal ]
RenamePackageCommand>>canBeExecutedInContext: aToolContext
^aToolContext isPackageSelected

25. Drag and drop example
MoveClassToPackageCommand>>execute
classes do: [:each | package addClass: each]
MoveClassToPackageCommand class>>systemBrowserDragAndDropActivator
<commandActivator>
^CmdDragAndDropCommandActivator
for: ClyClassSystemBrowserContext toDropIn: ClyPackageSystemBrowserContext
MoveClassToPackageCommand>>prepareExecutionInDragContext: aToolContext
super prepareExecutionInDragContext: aToolContext.
classes := aToolContext selectedClasses
MoveClassToPackageCommand>>prepareExecutionInDropContext: aToolContext
super prepareExecutionInDropContext: aToolContext.
package := aToolContext lastSelectedPackage

26. How extend browser?
• Commands
• Table decoration

27. Table decoration
• ClyTableDecorator subclasses with class side methods
ClyAbstractClassTableDecorator class>>browserContextClass
^ClyClassSystemBrowserContext
ClyAbstractClassTableDecorator class>>wantsDecorateTableCellOf: aDataSourceItem
^aDataSourceItem isMarkedWith: ClyAbstractClassTag
ClyAbstractClassTableDecorator class>>decorateTableCell: anItemCellMorph of: aDataSourceItem
| nameMorph |
nameMorph := anItemCellMorph nameMorph.
nameMorph emphasis: TextEmphasis italic emphasisCode.
nameMorph color: nameMorph color contrastingColorAdjustment contrastingColorAdjustment

28. Table decoration
• Commands with ClyTableIconCommandActivator
RunTestMethodCommand class>>systemBrowserTableIconActivator
<commandActivator>
^ClyTableIconCommandActivator for: ClyMethodSystemBrowserContext
RunTestMethodCommand >>buildTableCellIconFor: anItemCellMorph
testMethod isPassedTest ifTrue: [^anItemCellMorph iconNamed: #testGreenIcon].
testMethod isErrorTest ifTrue: [^anItemCellMorph iconNamed: #testRedIcon].
testMethod isFailedTest ifTrue: [^anItemCellMorph iconNamed: #testYellowIcon].
^anItemCellMorph iconNamed: #testNotRunIcon

29. How extend browser?
• Commands
• Table decoration
• Browser tabs

30. Browser tabs
• Calypso provides multiple tools instead of single source code view
• ClyClassCreationTool
• ClyClassCommentEditorTool
• ClyClassDefinitionEditorTool
• ClyMethodCreationTool
• ClyMethodCodeEditorTool
• Tools are managed by tabs
• Tools are built in background due to nice TabsManager package

31. Browser tabs
• Tools are subclasses of ClyBrowserTool with #build method and
activation context where they should be applied
ClyMethodDiffTool>>build
diffMorph := DiffMorph from: self leftMethod sourceCode to: self rightMethod sourceCode.
diffMorph
contextClass: self rightMethod sourceCode;
hResizing: #spaceFill;
vResizing: #spaceFill;
showOptions: false.
self addMorph: diffMorph fullFrame: LayoutFrame identity
ClyMethodDiffTool class>>activationContextClass
^ClyMethodSystemBrowserContext
ClyMethodDiffTool class>>shouldBeActivatedInContext: aBrowserContext
^aBrowserContext selectedMethods size > 1

32. How extend browser?
• Commands
• Table decoration
• Browser tabs
• Method groups

33. Method groups
• Third panel in browser shows method groups
• TaggedMethodGroups based on method tags (protocols)
• NoTagMethodGroup for unclassified methods
• ExtendedMethodGroup for all class extensions
• InheritedMethodGroup to toggle all inherited methods visibility
• SuperclassMethodGroup to toggle concrete superclass methods visibility
• ExternalPackageGroup for concrete package extending class
• VariableMethodGroup for variables mode of browser
• more

34. Method groups
• Method groups are built by method group providers
• Group providers are extended by environment plugins
ClyInheritanceAnalyzerEnvironmentPlugin>>collectMethodGroupProvidersFor: classes
^{ClyAbstractMethodGroupProvider. ClyOverrideMethodGroupProvider.
ClyOverriddenMethodGroupProvider. ClyRequiredMethodGroupProvider}
collect: [ :each | each classes: classes]
ClyAbstractMethodGroupProvider>>buildGroupItemsOn: items
(classes anySatisfy: [ :each | each hasAbstractMethods ])
ifFalse: [ ^self ].
items add: (ClyAbstractMethodGroup classes: classes) asEnvironmentItem
ClyAbstractMethodGroup>>includesMethod: aMethod
^aMethod sendsSelector: #subclassResponsibility

35. How extend browser?
• Commands
• Table decoration
• Browser tabs
• Method groups
• Class groups

36. Class groups
• First panel in browser shows packages expanded
to class groups
• TaggedClassGroup based of class tags
(RPackageTag)
• NoTagClassGroup for unclassified classes
• ExtendedClassGroup for classes extended by
current package

37. Class groups
• Class groups are built by class group providers
• Group providers are extended by environment
plugins
ClySystemEnvironmentPlugin>>collectClassGroupProvidersFor: aPackage
^{ClyExtendedClassGroupProvider. ClyTaggedClassGroupProvider}
collect: [ :each | each package: aPackage ]
ClyExtendedClassGroupProvider>>buildGroupItemsOn: items
package extendedClassNames ifEmpty: [ ^self ].
items add: (ClyExtendedClassGroup in: package) asEnvironmentItem

38. The end