MethodScript

Local Packages are a intermediate feature that allow you to break up your scripts and alias files into smaller, more manageable chunks; as the name suggests, packages. Unlike {{function|include}} and auto_include.ms, this allows you to break the alias files out into more files, as well as automatically including certain other ms files. Local Packages have limitations; They are meant as an intermediate feature before snap-ins are completed. These limitations will become clear if you are not careful in your design of packages. == Local Packages == For both Simple Directory Packages, and MSLP zips, the following functionality applies. Local Packages are placed in the plugins/CommandHelper/LocalPackages folder. Any number of nested folders may be placed inside, CommandHelper recursively scans the folders for relevant files. Unrecognized files are simply skipped, so you can have extra things in the folder, such as ReadMe files, or some such. For the sake of forward compatibility, only .txt files are guaranteed to never be used, so you should avoid adding other file types, in the event they are used in the future. == Simple Directory Packages == This is the easiest and most straightforward use of Local Packages. Files that end in .ms or .msa and are simple ascii files on the file system are read in and compiled. .ms files are pure mscript; no aliases may be defined here, and these files should work the same as any other file you might {{function|include}}. .msa files are the equivalent of the (by default) aliases.msa file. They must follow the exact same format as the aliases.msa file. One special exception is auto_include.ms files in the LocalPackages directory. These work exactly like the main auto_include.ms file, in that they are compiled, cached, and included before every script run. This means this is the perfect place to define procs or other variables that you need to be in scope for your scripts. All auto_includes are essentially run at the same time, and there is no guarantee of run order. Folders may be indefinitely nested, and CH will recurse into them as deep as necessary. The one exception is if the folder name ends in .disabled, in which case the entire folder is ignored. This gives you a handy way to "remove" scripts from your system, temporarily. == MSLP Zips == A .mslp file may also be placed anywhere in the directory structure. A MSLP file is simply a zip file, with the file extension changed. Within the MSLP file, the exact same rules apply as with the Simple Directory Package structure. .ms and .msa files. This mechanism allows for easier distribution of a self-contained script, but has the disadvantage of not being easily edited, however, a simple unzip operation will take care of that. There is a packager built in. You may create a mslp by simply running java -jar CommandHelper.jar --mslp path/to/toplevel/folder. In addition to creating the mslp, it will attempt to compile it first, failing to create the mslp if compilation errors are present. The name of the mslp is decided by the name of the folder; i.e. myScripts/ will become myScripts.mslp. == Disadvantages == The order in which files load is undefined. This means that dependencies among seperate "projects" is not usually a good idea. You may be able to game the system by naming files one thing or another, but in general that method will not be reliable. However, you ''can'' reliably handle dependencies ''within'' a package by putting includes in your auto_include.ms file, and using the .library mechanism. == Inter-Package Interaction == Usually programs have a "main" file, which is the thing that is guaranteed to run first. This is the starting point of a program usually. Local Packages can emulate this behavior, but within different "projects", the load order is completely undefined, and there is currently no mechanism for defining this. The one exception to this rule is that the main auto_include.ms will always run first. However, using the .library mechanism, along with careful file layouts will allow you to move pure ms files around, yet still guarantee their load order. A folder that ends in .library works the exact same way as a .disabled folder, the name is just a convention that hints at that folder's purpose. Files that are included inside of the .library folder are not directly loaded by the Package mechanism, but can still be loaded by your code using an {{function|include}}. .msa files are not really affected by this, since all aliases are global anyways, and even if one depends on another, they will all get loaded before any are used. .ms files may get affected by this, since they are executed as soon as they are run, and one file may define a proc that another file needs to use, and if the load order is incorrect, it would fail. Typical package structure may look like this then:

plugins/CommandHelper/LocalPackages/
--MyPackage/
----main.msa #Defines the commands used by this package
----main.ms #Initializes events, first running include('includes.library/file.ms')
----includes.library/
------file.ms #Defines several procs used in main.ms, and also possibly main.msa
--AnotherPackage/
----main.msa #More commands
----main.ms #More events and an include
----folder.library/
------name.ms

Since the Local Package mechanism is really just a way to organize your own personal scripts, if you try and distribute packages, you may run into namespace conflicts. This is again a limitation of Local Packages that will be addressed with Snap-Ins. {{LearningTrail}}

Find a bug in this page? Edit this page yourself, then submit a pull request.