|
1.0 ABOUT MODS and LIBRARIES
| 1.1 About appleMods Site |
| What is the appleMods website? |
| | appleMods is the community-managed archive of Open Source, ready-to-use AppleScript libraries and also the official source code repository for Loader and all of the current Loader-compatible libraries.
Loader was developed over the several years by Hamish Sanderson, who turned over all of his code and work on the Loader system to Gary Wood in November of 2003. In January of 2004 a formal Steering Committee was formed to aid Gary in the development of the this Open Source website and to offer professional advice on the community stewardship of the Loader and in the adoption of a standard library loading mechanism (currently called Loader, and formerly called ASLoader).
There are other sites on the Internet which offer code fragments and scripts. appleMods is not a duplicate of these resources.
The appleMods Open Source site and the current Steering Committee have as their goal the continued development of the only standard method of distributing and using Libraries ("mods") for AppleScript.
The libraries released here are Certified Loader-Compatible. However, for historical reasons, there is reference to earlier Library content that was developed prior to the Loader standardization scheme. These libraries are not available in the Loader-Compatible source tree, but they are available as text files culled from Archive.org and stored here in that frozen state.
(It should be noted that some of this historical content is not mirrored here at the request of the original authors. That content may still be available from other sources, for which appleMods has no control. We have contacted the authors of this material, but not every author has replied.) |
|
| 1.2 About libraries in AppleScript |
| Why haven't we heard more about libraries in AppleScript? |
| | Unfortunately for AppleScript users, Apple has never added a built-in library loading mechanism to AppleScript, nor do they include any AppleScript libraries in MacOS. As a result, AppleScript users haven't benefited from the power and convenience of AppleScript libraries nearly as much as they should have done. In consequence, a grassroots movement has now begun within the AppleScript community to rectify this problem, and bring the many benefits of AppleScript libraries to all AppleScript users. This task takes two forms:
- Creating a standard system for loading libraries into scripts. This is provided by Loader, a powerful tool for loading AppleScript libraries and binding them to your scripts. Loader also defines a set of standards for library authors to follow when writing Loader-compatible libraries, as well as a standard system for endusers to install and use libraries.
- Setting up an online archive of ready-to-use libraries as part of the popular MacScripter community site, . This archive is named appleMods, , and includes a range of libraries for working with strings, numbers, lists, dates, files, and HTML, as well as a library FAQ and other useful information.
|
|
| 1.3 About libraries |
| What is a library? (for users) |
| | A library is a collection of general-purpose handlers stored in an ordinary script file that can be reused from script to script without any need to copy and paste those handlers directly into your own code. This keeps your own scripts' source code compact and tidy, and avoids lots of messy duplication of commonly used code.
A single library typically contains several handlers (commands) that other scripts can call to perform a number of common, related tasks. (For example, the String library contains handlers for manipulating strings, while the Math library provides useful mathematical functions.)
For example, scripters often require handlers to perform common operations such as finding and replacing text, rounding numbers to a certain number of decimal places, sorting lists, formatting dates as strings, reading and writing text files, and so on. While you could repeatedly copy and paste these handlers into every script that requires them, it is much more convenient to keep them in external libraries, then bind those libraries to your scripts as you need them. In many cases, you don't even need to write these libraries yourself, as existing third-party libraries are already freely available over the net: simply download and install them, and you're ready to roll.
Unlike code samples, handlers and code fragments you'll find on the net, libraries are intended for use as-is. Instead of cutting-and-pasting library handlers directly into your own scripts, you simply refer to the commands of installed libraries like other AppleScript commands. |
|
| 1.4 About libraries |
| What is a library? (for developers) |
| | A library is a script specifically designed for other scripts to use. It adds commands to AppleScript, in much the same way that a scripting addition (OSAX) does. The difference is that OSAX and Libraries are written in different languages. Libraries are AppleScript code, while OSAX are generally C-based programs.
For example, scripters often require handlers to perform common operations such as finding and replacing text, rounding numbers to a certain number of decimal places, sorting lists, formatting dates as strings, reading and writing text files, and so on. While you could repeatedly copy and paste these handlers into every script that requires them, it is much more convenient to keep them in external libraries, then bind those libraries to your scripts as you need them. In many cases, you don't even need to write these libraries yourself, as existing third-party libraries are already freely available over the net: simply download and install them, and you're ready to roll.
Below is a simple, albeit fictitious, example of using a library to perform a find-and-replace operation in a script without having to include the find-and-replace code within the script itself. As you can see, the code required to do this is very simple.
-- EXAMPLE 1: Loading and Using a Library in a Script
property _MyLibrary : load script (alias "Macintosh HD:Library:Scripts:MyLibrary")
_MyLibrary's findAndReplace("Hello World", "o", "?")
-- Result: "Hell? W?rld"
Because libraries are such an excellent time-and-labour-saving tool, their use is extremely popular in other languages such as Perl and Python, which both include a large bundled collection of 'standard' libraries and provide large online repositories (including CPAN and PyPI respectively) where users can download and share many additional libraries. |
|
| 1.5 About modules |
| What is a module? |
| | 'Module' is just another word for 'library'. For sake of consistency, we use the term 'library' when referring to AppleScript-based libraries/modules. |
|
| 1.6 About libraries |
| What is a 'dependency'? |
| | The word "dependency" simply refers to an application, scripting addition or library that a script is, quite literally, dependent on. Each library on appleMods lists all its dependencies so you can easily check that you have the relevant applications/additions/libraries installed before trying to use it. Most libraries on appleMods do not require third-party applications or additions to function, though quite a few do depend on other libraries. |
|
2.0 DOWNLOAD AND INSTALLATION
| 2.1 Installing Loader-compatible libraries |
| How do I install Loader-compatible libraries? |
| | Once downloaded, Loader-compatible libraries must be unstuffed and placed in one or more of the following locations (create the main ASLibraries folder if it does not exist). This folder, in turn, must be kept in one of the MacOS's standard Scripts folders:
So, for
- OS8/9:
:System Folder:Scripts:ASLibraries:
- OS X:
/Library/Scripts/ASLibraries/
~/Library/Scripts/ASLibraries/
(Note that OS X users can have either one or two ASLibraries folders; if both folders are provided, Loader will look in the latter one first when searching for a library.)
--
Important: Do not store anything other than Loader-compatible libraries in the ASLibraries folder. Storing non-Loader-compatible libraries or non-library files or folders in the ASLibraries folder may cause the Loader library and tools such as LoaderWizard to operate incorrectly.
|
|
| 2.2 Loading Libraries into your scripts with Loader |
| How do I load Libraries into my scripts using the Loader system? |
| | The most common use for Loader is to bind existing libraries to the scripts you write. To do this:
1. Double-click the LoaderWizard applet.
2. From the list of installed libraries, select the names of those to bind, then click the "OK" button. (Command-click to select multiple libraries.)
3. Paste the clipboard contents at the top of your script.
Now each your script is run, Loader will store the specified libraries in the properties provided. For example, a library named "String" will be stored in the property named "_String", allowing your script to call any of the handlers in that library.
--
Notice that you may have to make one or two minor changes to the generated code before you can use it:
- If your script contains an explicit 'run' handler, move the line:
__load__(_Loader's makeLoader())
to the top of this handler, otherwise your script won't compile.
- If your script is an applet containing an 'open' handler, copy the line:
__load__(_Loader's makeLoader())
and paste it at the top of of this handler so that the libraries are loaded each time your applet launches when files or folders dropped onto it.
--
Example 2, below, shows a very simple script that loads the 'String' library into a property named _String, then calls the library's replaceText handler to replace some text in a string. It requires a bit more boilerplate code than Example 1, but this isn't a problem as this code is automatically generated by the LoaderWizard.
-- EXAMPLE 2: Loading and Using a Loader-compatible Library in a Script
property _Loader : run application "LoaderServer"
----------------------------------------------------------------------
-- DEPENDENCIES
property _String : missing value
on __load__(loader)
set _String to loader's loadLib("String")
end __load__
----------------------------------------------------------------------
__load__(_Loader's makeLoader())
return _String's replaceText("Hello World", "o", "?")
-- Result: "Hell? W?rld"
|
|
3.0 USING LIBRARIES IN YOUR SCRIPTS
| 3.1 Using Loader-compatible libraries |
| How do I use Loader-compatible libraries? |
| | The most common use for Loader is to bind existing libraries to the scripts you write. To do this with the LoaderWizard:
1. Double-click the LoaderWizard applet.
2. From the list of installed libraries, select the names of those to bind, then click the "OK" button. (Command-click to select multiple libraries.)
3. Paste the clipboard contents at the top of your script.
Now each time your script is run, Loader will store the specified libraries in the properties provided. For example, a library named "String" will be stored in the property named "_String", allowing your script to call any of the handlers in that library.
--
Notice that you may have to make one or two minor changes to the generated code before you can use it:
- If your script contains an explicit 'run' handler, move the line:
__load__(_Loader's makeLoader())
to the top of this handler, otherwise your script won't compile.
- If your script is an applet containing an 'open' handler, copy the line:
__load__(_Loader's makeLoader())
and paste it at the top of of this handler so that the libraries are loaded each time your applet launches when files or folders dropped onto it.
For more information, see the Library QuickStart Guide file installed by Loader Installer.
You can also read this document in HTML format.
HOW-TO: Use Loader-compatible Libraries in Your Scripts |
|
| 3.2 About Loader |
| What is Loader? |
| | Loader is a special library that makes it extremely easy to load, or "bind", libraries [in]to other scripts. Most languages come with a built-in library-loading mechanism as standard; however, the AppleScript language does not. Loader has been created by experienced AppleScript users specifically to address this deficiency, making libraries [almost] as easy to use in AppleScript as they are in other languages.
Loader is a powerful and sophisticated tool that can locate libraries stored in several locations and manage even complex interdependencies between multiple libraries with ease, yet simple enough for beginners to use. All the libraries you'll find on appleMods are Loader-compatible, by the way. [Although some non-Loader-compatible libraries are still offered, for historical purposes, in the 'strange archive'.]
Loader automates the tedious process of locating and loading AppleScript libraries on any OS8/9/X system:
- It provides a standard location, the ASLibraries folder, in which to install all your Loader-compatible libraries.
- It allows you to install and use third-party Loader-compatible libraries without any fuss.
- You can safely move your scripts between different machines without modification: as long as the required libraries are also installed on the new machine (or bound into your scripts), Loader will find them automatically.
- Loader also looks after libraries that require other libraries to function - just install those additional libraries and leave the rest to Loader.
|
|
| 3.3 About Loader and Loader Installer |
| What is Loader Installer? |
| | Loader Installer installs everything you need to begin using appleMods libraries on your Mac: the Loader library, a small collection of "core" libraries, the LoaderWizard applet and the Library QuickStart Guide.
|
|
| 3.4 About Loader and LoaderWizard |
| What is LoaderWizard? |
| | LoaderWizard is a simple AppleScript applet for automatically generating the boilerplate code needed to bind libraries to your scripts. Just run it, select the names of those installed libraries you want to use in your script, and LoaderWizard will place the necessary code onto your clipboard, ready for pasting into your script.
|
|
| 3.5 About Loader and LoaderServer |
| What is LoaderServer? |
| | LoaderServer is a simple stay-open AppleScript applet responsible for attaching the Loader library to your scripts when you compile them. LoaderServer typically takes a second or two to launch the first time you compile a script that contains Loader header code. Once it's running, however, scripts will compile as fast as usual. |
|
| 3.6 About OS versions |
| What versions of MacOS are supported? |
| | Loader supports all versions of MacOS from 8.??? onwards. Most of the libraries available on appleMods are compatible with both classic MacOS and OS X, though some will require OS X to provide full functionality and a few are OS X-only. |
|
| 3.7 Using libraries |
| How can I run scripts that use Loader-compatible libraries on different machines? |
| | If your script loads libraries at runtime, simply make sure that Loader is installed on those machines along with all the libraries that your script uses. Don't forget to take care of any dependencies that those libraries may have themselves, of course.
|
|
| 3.8 Loading Components into a main script |
| Can I load other scripting components into my Libraries and scripts? |
| | Loader is powerful in locating and executing external components that a Library may use (or that your script may use, separate from any Library). These components can be any executable code that AppleScript can handle.
Loader can load both compiled AppleScript scripts and plain text files (typically Perl/Python/shell/etc. scripts) from a user-defined components folder.
The structure of "binding" (inserting) into your script is the same as for binding Libraries, as the following samples show.
- Declare properties for holding loaded components at the top of your script:
property _COMPONENTNAME : missing value
property _TEXTCOMPONENTNAME : missing value
- To specify the Components folder, add the following command to the __load__ handler, passing an alias to your components folder as parameter:
setComponentsFolder(alias "PATH TO COMPONENTS FOLDER")
- Finally, add statements to the __load__ handler that'll load component scripts and assign them to the above properties:
set _COMPONENTNAME to loader's loadComponent("COMPONENTNAME")
set _TEXTCOMPONENTNAME to loader's loadTextComponent("TEXTCOMPONENTNAME")
- Note that Loader ignores filename suffixes when loading text components. For example, a text component named "Foo" may have the filename "Foo.pl", "Foo.py", "Foo.applescript", etc.
|
|
4.0 DEVELOPING MODS and LIBRARIES
| 4.1 Developing libraries |
| Can I make other libraries Loader-compatible? |
| | Yes.
Currently, developer documentation for general use is crude and limited. It is not difficult to add the required information to your library scripts to make them Loader-compatible. However, since most library authors are "serious" scripters, there has been little need to write general-purpose documentation.
We are working on a basic "Loader Compatibility Guide".
If you are a library developer, we encourage you to join "moDev" (pronounced "mod dev" for the straight-laced, or "moe-dev" for the terminally hip ;)
The "moDev" community offers exchange with other library developers, and also provides ways for you to help shape 'appleMods' as we grow. |
|
| 4.2 Developing libraries |
| Can I write my own Loader-compatible libraries? |
| | Yes.
Please see 'Can I make other libraries Loader-compatible?' |
|
5.0 LOADER (appleMods) COMPATIBILITY SYSTEM
| 5.1 What are the benefits of using Loader? |
| What are the benefits of using Loader? |
| | Loader automates the tedious process of locating and loading AppleScript libraries on any OS8/9/X system:
- It provides a standard location, the ASLibraries folder, in which to install all your Loader-compatible libraries.
- It allows you to install and use third-party Loader-compatible libraries without any fuss.
- You can safely move your scripts between different machines without modification: as long as the required libraries are also installed on the new machine, Loader will find them automatically.
- Loader also looks after libraries that require other libraries to function - just install those additional libraries and leave the rest to Loader.
|
|
7.0 REPORTING BUGS
| 7.1 Bug reporting |
| I've found a bug in one of the libraries. What should I do? |
| | Report the bug to the library's maintainer.
Before you get irritated and angry at a library's author and go flaming her (or him) on a mailing list or forum, write a short email to the author at the address provided in the library's documentation. In almost all cases, you'll get a reply and either assistance or confirmation of the bug.
Please be sure to include, at a minimum:
a. your OS version
b. your AppleScript version
c. your Standard Additions version
d. any other _relevant_ information to the bug's appearance
Do not include full System Profiler reports unless you are asked by the library's author for more information -- or that much information.
At the moment, all 'HAS' libraries hosted on appleMods are being maintained by the appleMods maintainer, Gary Wood. |
|
8.0 UPDATES to LIBRARIES and SITE
| 8.1 About library versions |
| Some of these libraries have very low version numbers. Does this mean they're unfinished? |
| | All of the libraries hosted on appleMods are considered sufficiently well developed to be useful, even where incomplete. Some of these libraries may be considered complete in all but name; all that's required is some prerelease testing before an official 1.0.0 release is made. Others may lack some planned features or their documentation may be incomplete. Most library manuals include a TO DO section describing any planned work that's still to be done.
|
|
| 8.2 Site and library updates |
| Can I contribute to appleMods? |
| | Yes. Although the appleMods archive isn't yet ready to accept new submissions from the general public (we are accepting submissions from those with known library and scripting experience), there are several other ways in which you can help meantime:
1. Use these libraries! We want to make appleMods a success. And the more people use it, the more successful it is.
2. Spread the word! Help other AppleScripters become acquainted with libraries, what they do and how they're used.
3. Help us to finish the libraries we have at the moment. Report and bugs or typos you find while using them. Experienced coders and testers who'd like to take over development and maintenance of individual libraries may contact Gary Wood for more information. We could really use some help maintaining some of the present libraries, so don't be shy. Drop us an email and let us hear from you.
|
|
| 8.3 Site and library updates |
| When will we see new libraries on appleMods? |
| | Since we've just launched the site, we'd like to take a month or two to "work out the kinks" in distribution and site construction.
After that time, we plan to open the doors to new libraries and authors. There is also the need to form a team of "compatibility testers" so that we can "certify" (or something similar) libraries for Loader compatibility. This seems like an important step so that we can keep all of the appleMods distributed libraries to some standards -- the goal being ease of use for endusers.
Developers...we need you. Not only do we have the current libraries to maintain, but we'd like to form a kind of ad hoc group to do some "certification" work on existing libraries (that are not yet published here but are close to ready for prime time).
We also need maintainers of the powerful libraries presently offered. |
|
| 8.4 Old appleMods site |
| What happened to the old appleMods archive? |
| | The old site is long gone, but the archive of libraries remains available in our 'strange archive'. (See FAQ 9.1 for more on why this is called the 'strange archive'.)
It should be noted that the libraries contained in that archive are not Loader-compatible, per se. They were written by very strong scripters early on the appleMods effort, and can still be used. They may have been replaced by more modern functionality in either AppleScript or in a subsequent library, so you should definitely try to use the most recent libraries when possible.
The libraries are still available here for historical and community purposes. |
|
| 8.5 Little Page of AppleScripts |
| What is (or was) 'The Little Page of AppleScripts'? |
| | The LPoAS was a web site maintained by 'has' (a.k.a. Hamish Sanderson). The site contained a collection of libraries as they developed (all of these have now been contributed to appleMods and are available here in their current and most recent versions.)
HAS has devoted much of his time recently to other projects, and he no longer maintains that LPoAS.
We are looking for individuals who wish to take on the maintenance of one or more of these libraries. They are a great service to the AS community and we'd like to keep them as current as possible. |
|
9.0 MISCELLANEOUS
| 9.1 Site oddities |
| What is the 'strange archive' or gallery? |
| | A number of years ago, when there was a budding movement to create a standard library system for AppleScript, a scripter named Greg Strange built a site, and along with a few others, namely 'has' and Arthur Knapp, wrote a few libraries for distribution. That site has gone by the wayside, but the original collection of libraries is archived.
Of course, since the archive is a bit dated and not very organized (compared to the current archive), the 'strange' is a double entendre.
Some of the libraries in the 'strange gallery' are superseded by current libraries with the same function (and often the same author). When there is functionality in an updated library, the user should elect to download and install the more modern version. These have the benefit of being more compatible with current versions of scripting additions, AppleScript and the OS. |
|
| 9.2 More help |
| I'm stuck. Where can I get more help? |
| | If you are a library end-user, then you will want to check the documentation that came with the library you downloaded. Perhaps the author has included an email address or web URL where you can get more help.
If you are a developer, you can join the 'moDev' forum where you can exchange information, ideas and problems with other developers.
In the coming months, we will open the community forum, where users and developers can meet and ask and answer questions. |
|
|
