You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Loads modules used by an automation script, pulls missing requirements from the internet and informs the user about missing and outdated modules that could not be updated automatically.
8
+
* A lightweight package manager lets users conveniently install scripts right from inside Aegisub
9
+
* Loads modules used by an automation script, pulls missing requirements from the internet and informs the user about missing and outdated modules that could not be updated automatically
9
10
* Checks scripts and modules for updates and automatically installs them
10
11
* Offers convenient macro registration with user-customizable submenus
11
-
* Provides configuration and logging servicesfor your script
12
+
* Provides configuration, logging services, file operations and a unit test framework for your scripts
12
13
* Supports optional modules and private module copies for cases where an older or custom version of a module is required
4.[The Anatomy of an Updater Feed](#the-anatomy-of-an-updater-feed)
30
32
5.[Reference](#reference)
31
-
6.[Ancillary Components: Logger and ConfigHandler](#FIXME) (tbd)
33
+
1.[DependencyControl](#FIXME)
34
+
2.[Updater](#FIXME)
35
+
3.[Logger](#FIXME)
36
+
4.[ConfigHandler](#FIXME)
37
+
5.[FileOps](#FIXME)
32
38
33
39
----------------------------------
34
40
@@ -38,6 +44,7 @@ As an end-user you don't get to decide whether your scripts use DependencyContro
38
44
39
45
#### Install Instructions ####
40
46
1. Download the latest DependencyControl release for your platform and unpack its contents to your Aegisub **user** automation directory.
47
+
Alternatively use one of the [provided Aegisub builds](http://files.line0.eu/builds/Aegisub/) with built-in DependencyControl.
41
48
42
49
_It is essential DependencyControl and all scripts it's used reside in the **user** automation directory, **NOT** the the automation directory in the Aegisub application folder._
43
50
@@ -115,7 +122,8 @@ local version = DependencyControl{
115
122
localutil, LineCollection, Line, Log, ASS, Common, YUtils=version:requireModules()
116
123
```
117
124
118
-
Specifying a feed in your own version record provides DepedencyControl with a source to download updates to your script from. Specifying feeds for required modules managed by DependencyControl allows the Updater to discover those modules and fetch them when they're missing from the user's computer.
125
+
Specifying a feed in your own version record provides DepedencyControl with a source to download updates to your script from.
126
+
Specifying feeds for required modules managed by DependencyControl allows the Updater to discover those modules and fetch them when they're missing from the user's computer. However, you can omit the feed URLs for required modules when your own feed already has references to them.
119
127
120
128
121
129
To __register your macros__ use the following code snippets instead of the usual *aegisub.register_macro()* calls:
@@ -208,12 +216,15 @@ Examples:
208
216
* l0.ASSWipe.lua
209
217
* l0.ASSWipe.Addon.moon
210
218
211
-
__Modules__ use the `?user/automation/include` folder, which has a nested file structure. To determine your _subdirectory/file base name_, the dots in your namespace are replaced with `/` (`\` in Windows terms).
219
+
__Modules__ use the `?user/automation/include` folder, which has a nested file structure. To determine your _subdirectory/file base name_, the dots in your namespace are replaced with `/` (`\` in Windows terms).
220
+
221
+
__Tests__ use the `?user/automation/tests/DepUnit/modules` or `?user/automation/tests/DepUnit/macros` folder depending on whether a macro or automation is being tested and mirror the directory structure of the respective `include` and `autoload` folders.
212
222
213
223
Our example module ASSFoundation with namespace __l0.ASSFoundation__ writes (among others) the following files:
@@ -225,12 +236,17 @@ If you want DepedencyControl auto-update your script on the user's system, you'l
225
236
226
237
`````javascript
227
238
{
228
-
"dependencyControlFeedFormatVersion":"0.1.0",
229
-
// The version of the feed format. The current version is 0.1.0, don't touch this until further notice.
239
+
"dependencyControlFeedFormatVersion":"0.3.0",
240
+
// The version of the feed format. The current version is 0.3.0, don't touch this until further notice.
230
241
"name":"line0's Aegisub Scripts",
231
242
"description":"Main repository for all of line0's automation macros.",
232
243
"maintainer":"line0",
233
244
// The title and description of your repository as well as the name of the maintainer. May be used by GUI-driven management tools, package managers, etc...
// A hashtable of known feed URLs. Can be referenced with @{feed:name} and will be used to discover other repositories the user can install automation scripts and modules from. At the very least this should contain the repo URLs for the required modules in your repo, but may be used to adverise other unrelated repos you trust.
// baseUrl is a template variable that can be referenced in other string fields of the template. It's useful when you have several scripts which all have their documentation hosted on the same site (so they start with the same URL). For more Information about templates, see the section below.
236
252
"url":"@{baseUrl}",
@@ -295,6 +311,14 @@ An automation script or module object looks like this:
295
311
// against the downloaded file, so it must always be present and valid or the update process
296
312
// will fail on the user's end.
297
313
},
314
+
{
315
+
"name": ".lua",
316
+
"type": "test",
317
+
// Optional, defaults to "script". Specify "test" to denote a unit test.
318
+
// Currently only "script" and "test" are available, unknown script types will be skipped.
The constructor for a DepedencyControl record. Uses the table-based signature.
@@ -401,23 +431,15 @@ __Arguments:__
401
431
* _feed_: The update feed for your script.
402
432
* _configFile_: Configuration file base name used by the script. Defaults to the namespace. Used for configuration services and script management purposes.
Returns true if the version number of the record is greater than or equal to __version__. If the version can't be parsed it returns nil and and error message.
437
+
Returns true if the version number of the record is greater than or equal to __version__. Reduce the __precision__ to `minor` or `major` to also return true for lower patch or minor versions respecitively. If the version can't be parsed it returns nil and and error message.
Returns true if the optional __modules__ have been loaded, where __modules__ is a list of module names. If one or more of the modules are missing it returns false and an error message.
Creates a directory. Returns _true_ on success or if the directory already exists or _false_ and an error message on failure. Use __isFile__ to indicate the __path__ points to a file, in which case its parent will be created.
416
-
417
-
__:expandFeed(*tbl* feed) --> *tbl* feed__
418
-
419
-
Expands template variables in downloaded update feeds **in-place** and returns the expanded feed. _Intended for internal use._
420
-
421
443
__:getConfigFileName() --> *str* fileName__
422
444
423
445
Returns a full path to the config file proposed for this script by DependencyControl. Uses the configFile argument passed to the constructor which defaults to the script namespace. The path is subject to user configuration and defaults to "?user\config". The file ending is always .json, because why would you use any other format?
Returns a Logger (see [Logger Documentation](#FIXME)) preconfigured for this script. Trace level and config file preference default to user-configurable values. Log file name and prefix are based on namespace and script name.
Used to turn an updater return __code__ into a human-readable error message. The __name__ of the updated component and other format string parameters are passed into the function.
438
-
439
-
VarArgs:
440
-
441
-
1. __*bool* isModule__: True when component is a module, false when it is an automation script/macro
442
-
2. __*bool* isFetch__: True when we are fetching a missing module, false when updating
443
-
3. __extError__: Extended error information as returned by the _:update()_ method
Locks the updater to the current macro/environment. Since all automation scripts load in parallel we have to make sure multiple automation scripts don't all update/fetch the same depedencies at once multiple times. The solution is to only let one updater operate at a time. The others will wait their turn and recheck if their required modules were fetched in the meantime.
448
-
449
-
If __doWait__ is true, the function will wait until the updater is unlocked or __waitTimeout__ has passed. It will then get the lock and return true. If __doWait__ is false, the function will return immediately (true on success, false if another updater has the lock). _Intendend for internal use_.
Replaces dummy reference written to the global LOADED_MODULES table at DependencyControl object creation time with a reference to this module.
487
+
Also automatically registers unit tests for this module, passing in any __extraUnitTestArgs__
482
488
483
489
The purpose of this construct is to allow circular references between modules. Limitations apply: the modules in question may not use each other during construction/setup of each module (for obvious reasons).
Registers multiple macros, where __macros__ is a list of tables containing the arguments to a __:registerMacro()__ call for each automation menu entry. a single macro using script name and description by default.
503
509
If __useSubmenuDefault__ is set to true, the macros will be placed in a submenu using the script name unless overriden by per-macro settings.
504
510
505
-
__:releaseUpdaterLock()__
511
+
__:registerTests(unitTestArgs...)__
506
512
507
-
Makes an updater host (macro) release its lock on the Updater if it has one. See _:getUpdaterLock_ for more information
513
+
Registers unit tests for automation modules, passing in any of specified __unitTestArgs__. Registration of modules is done automatically upon calling __:register__
Writes __global__ and per-module __local__ configuration. If __concert__ is true, concerted writing will be used to update the configuration of all DependencyControl hosted by any given macro/environment at once. See ConfigHandler documentation for more information. _Intended for internal use._
Used to turn an updater return __code__ into a human-readable error message. The __name__ of the updated component and other format string parameters are passed into the function.
534
+
535
+
VarArgs:
536
+
537
+
1. __*bool* isModule__: True when component is a module, false when it is an automation script/macro
538
+
2. __*bool* isFetch__: True when we are fetching a missing module, false when updating
539
+
3. __extError__: Extended error information as returned by the _:update()_ method
Locks the updater to the current macro/environment. Since all automation scripts load in parallel we have to make sure multiple automation scripts don't all update/fetch the same depedencies at once multiple times. The solution is to only let one updater operate at a time. The others will wait their turn and recheck if their required modules were fetched in the meantime.
544
+
545
+
If __doWait__ is true, the function will wait until the updater is unlocked or __waitTimeout__ has passed. It will then get the lock and return true. If __doWait__ is false, the function will return immediately (true on success, false if another updater has the lock). _Intendend for internal use_.
546
+
547
+
__:releaseUpdaterLock()__
548
+
549
+
Makes an updater host (macro) release its lock on the Updater if it has one. See _:getUpdaterLock_ for more information
Runs the updater on this automation script or module. This includes recursicely updating all required modules. When __force__ is true, required modules will skip their update interval check.
@@ -522,6 +556,22 @@ By default, the updater will process all suitable feeds until one feed confirms
522
556
523
557
Returns a result code (0: up-to-date, 1: update performed, <=-1: error) and extendend error information which can be fed into _:getUpdaterErrorMsg()_ to get a descriptive error message.
Writes __global__ and per-module __local__ configuration. If __concert__ is true, concerted writing will be used to update the configuration of all DependencyControl hosted by any given macro/environment at once. See ConfigHandler documentation for more information. _Intended for internal use._
561
+
tbd
562
+
563
+
#### ConfigHandler ####
564
+
565
+
tbd
566
+
567
+
#### FileOps ####
568
+
569
+
tbd
570
+
571
+
#### UnitTestSuite ####
572
+
573
+
Reference documentation for the UnitTestSuite module is available in the [source code](https://github.com/TypesettingTools/DependencyControl/blob/master/modules/DependencyControl/UnitTestSuite.moon#L760)
0 commit comments