In order to support different use cases like interactive loading during development, unattended loading for a continuous integration build, using a specific version name or getting it from the git repository the applications are saved, etc, the loader (a TonelLoader) will delegate some actions to, currently, three different strategies, all inheriting from the TonelLoaderStrategy class, each of them with an "interactive" and an "unattended" subclass.
- Prerequisites strategy
- Version strategy
- Base edition strategy
- Application naming strategy
- SubApplication mapping strategy
By "interactive" whe mean involving the GUI, so, it is opening a dialog, a prompt of some sort, etc. While by "unattended" we mean that if there is a decision to be taken, it will be programmed in the strategy without requiring the display of any GUI element.
The loader will instantiate a separate TonelApplicationLoader (aka application loader) to load each Application, but the strategies are shared among the all the application loaders in the loader.
There are some options in the loader and the writer that are not implemented as first class strategies, but are included in this document as well for the sake of reference.
When loading an Application the loader will read it's prerequisites from the vaPrerequisites metadata in the .package file, but there could be the case where you need to specify some other prerequisite at load time.
This strategy will display an EtPrerequisiteCollectingPrompter enabling the user to add/remove prerequisites before loading the application
This strategy uses the prequisites specified in the metadata plus the ones computed by the loader.
"Enable it by evaluating"
aTonelLoader useComputedPrerequisitesThe version strategy handles both the versioning, and also the creation of editions prior to versioning.
This will prompt the user to specify a version name for each application using the default version name prompter, leaving the option to not define any, and so only the edition will be created, but without versioning it.
"Enable it by evaluating"
aTonelLoader useInteractiveVersioningThis strategy will create an new edition but won't version it. It is useful when you are developing and want to control manually the versioning and/or don't want to version at all.
"Enable it by evaluating"
aTonelLoader doNotCreateVersionsThis strategy will use an specified version name when versioning, if you pass nil as the version name, it will behave like the TonelLoaderNoVersionStrategy.
"Enable it by evaluating"
aTonelLoader useSpecifiedVersion: 'DEMO 1.1'This strategy will read the commit hash, the branch name and the commit date from the HEAD of the git repository and use it as the commit.
This strategy can be used only if the folder containing the Tonel files is managed by a git repository and it doesn't need git executables or any shared library, since we directly read the files in the .git repository.
"Enable it by evaluating"
aTonelLoader useGitVersionBy default the version name will be something like e022f87-master (2019-12-30T14:30:00-03:00), but you can change the pattern specifing any other String that can be expanded using macros (expandMacrosWith:with:with:) where the first argument will be the commit hash string, the second the branch name and the third one the branch name.
"Change the pattern to just the commit hash evaluating"
aTonelLoader versionStrategy versionNamePattern: '<1s>'"Change the pattern to just the commit hash and branch evaluating"
aTonelLoader versionStrategy versionNamePattern: '<1s> (<2s>)'The loader won't create a new edition of a class or subapplication if there are no changes between what's loaded and what being loaded from Tonel.
To force the creation of new editions, you can set alwaysCreateEdition in the version strategy, or directly in the loader.
"Force the creation of editions"
aTonelLoader forceCreationOfEditionsWhen you're loading an Application or SubApplication from Tonel sources into your image, if no edition/version of it is loaded from the ENVY Library, and there is an existing version in it, you'll have to chose which version is used as "base" upon which changes will be applied. This is called a "base edition".
When loading the base edition, the application might need to load its prerequisites from the Library, and for that it will delegate the prerequisites loading to the prerequisites strategy defined in the loader.
You can also specify whether the lookup of base editions will lookup only for versioned editions, to avoid selecting an edition that might be a draft or broken but that it is more recent than the latest "valid" edition (usually a versioned one).
This is the default strategy, that will display a list of base editions to choose, and prompt the user to select one from the list.
This will automatically select the latest (newest) edition as the base edition for the App/Subapp being loaded.
"Enable it by evaluating"
aTonelLoader useLatestBaseEditionsIn git repositories, each commit has one or more parent commits, this strategy will try to find a base edition whose versionName matches the parent commit hash (only its first eight characters), and if no edition is found, it will choose the latest one, as in TonelLoaderlatestBaseEditionStrategy.
When setting useGitVersion in the TonelLoader, this base edition strategy will be set as well.
So if you're loading MyApplication from a git repository whose commit id is 8c3fa3d and parent commit is b78df32, when loading a base edition it will look for an edition of MyApplication in the EM Library whose versionName match b78df32.
You can specify a prefix for your apps, and a special suffix for applications and subapplications.
E.g.
aTonelLoader namingStrategy
appSuffix: 'App';
subAppSuffix: 'SubApp';
prefix: 'Et'.This will convert an application otherwise named Controller with a subapplication named Core into EtControllerApp and EtCoreSubApp.
NOTE: by default no prefix nor suffix is defined.
It is possible to create your own naming strategy by subclassing TonelLoaderNamingStrategy and redefining nameForApp: and nameForSubApp:.
When writing an Application hierarchy, the TonelWriter will map each application and subapplication to its own Tonel package, and add the relation between each SubApplication to its children via an specific metadata. This is a feature specific to VAST, since in the canonical version of Tonel there is no such a concept like "SubApplication" or packages hierarchy.
So when reading the applications and subapplications back with TonelLoader, the loader will rebuild such hierachy based on the above described metadata.
However, there is an abstraction used in other dialects, that is not present in the Tonel specification nor its implementation: the "package tag". The package tag or just tag, is a way to organize classes in the class browser based on some grouping criteria based on the class category, effectively working as "virtual sub packages".
So the tags introduce a semantic mismatch, because VAST's classes don't have a category at all. What usually is a Package/Tag relation in other dialects is defined as an Application/SubApplication relation in VAST. But VAST also supports Application/SubApplication/SubSubApplication/... organization.
To overcome that, we provide a strategies to map a Package/Tag to Application/SubApplication or simply load a Package in a single Application. And also provide an option to the TonelWriter to map Application/SubApplication to Package/Tag when exporting, or to export each SubApplication as a separate Package.
This is the default strategy configured in the TonelLoader that honors the 1:1 relation between a Package and an Application.
If you're loading code that was written with the TonelWriter (it is, written by VAST to be loaded into VAST), it is the recommended option, since it will also load code based on the conditions defined in each Application/SubApplication.
This strategy will create an Application for the package and one SubApplication for each tag found in the category of classes.
This is recommended if you're loading Tonel code generated from a dialect other than VAST, one that uses Package and tags to organize code.
E.g. For the package Grease-Core all classes categorized as Grease-Core-Utilities will end up in the GreaseCoreUtilities sub application inside the GreaseCoreApp application.
Note: This strategy will use the name of the Application (without the App suffix) concatenated with the name of the tag to define the name of the sub application. This is so because if used only Utilities as the name of the sub application it might collide with other package that also has a Utilities tag (i.e. Grease-Core / Utilities with Seaside-Core / Utilities).
If you need a more specific naming you can subclassify this strategy.
After the load or unload of an Application or SubApplication into/from the image, there are a few class side methods that are invoked by the ENVY framework to ensure proper initialization or cleanup. The most know and used method is #loaded.
The loader provides an option to create such methods for each application and subapplication loaded from source.
(TonelLoader readFromPath: (CfsPath named: "..."))
createsHookMethods: true;
"..."The createHookMethods accessor (initialized to true by default) will create such methods. If you're migrating code from a dialect other than VAST you could disable this, and create them manually based on your own needs.
If the code in the repository already have such methods defined, they'll be treated as regular methods, and will be loaded after this hook methods are created, so it's safe to leave this option enabled, since the code from the repository will replace the definition in the image.
If when writing you want to perform the opposite step of the TonelLoaderSubapplicationsTagMappingStrategy, then you can configure the writer to flatten sub applications and map them as package tags.
writer := TonelWriter new.
writer flattenSubApplications: true.NOTES: Since there is no "class category" in VAST classes the package tag is going to be computed based on the root application #tonelPackageName and the SubApplication name.
E.g. For an Application named GreaseCoreApp with the GreaseCoreUtilities and GreaseCoreExceptions sub applications, it will attempt to find remove the application name from the subapplication name (with or without the App suffix), and the resulting string is going to be used as the package tag. In this case it will remove GreaseCore from GreaseCoreExceptions and produce Exceptions as the package tag.
Applications and SubApplication subclasses have a dual purpose: to work as a "package" that works as container to class definitions and extensions in ENVY, and as a regular class that manage the lifetime of the app/sub app loading, initialization, etc.
So when exporting your Application subclass (e.g. MyApplication) it will export a class definition for it, with Application as its superclass. If your plan is to load it back into VAST, then that's totally fine, and the desired behavior, but if your intention is to export to another dialect you either have to have Application and SubApplication defined in such dialect (as some dialect compatibility package) or to omit the writing of such classes alltogether.
So if you want to omit the write of ENVY app/subapp classes you can do:
writer := TonelWriter new.
writer writeENVYApps: false.By default the writer is configured to write the ENVY app/subapps, so if that's your intention you don't have to do anything special.
Below there is a small sample of "recipes" for the common use cases.
Load applications interactively without creating versions
(TonelLoader readFromPath: (CfsPath named: "..."))
beInteractive; "this is redundant, but serves as example"
doNotCreateVersions;
loadApplicationsForPackagesNamed: #('Package-Core' 'Package-Tests')Load applications unattended from a git repository
(TonelLoader readFromPath: (CfsPath named: "..."))
beUnattended;
useGitVersion;
loadApplicationsForPackagesNamed: #('Package-Core' 'Package-Tests')Load applications unattended with a specified version name.
(TonelLoader readFromPath: (CfsPath named: "..."))
beUnattended;
useSpecificVersion: 'vX.Y';
loadApplicationsForPackagesNamed: #('Package-Core' 'Package-Tests')(TonelLoader readFromPath: (CfsPath named: "..."))
mapTagsToSubapplications; "<-- convenience method"
loadApplicationsForPackagesNamed: #('Package-Core' 'Package-Tests')