Search

Easily launch scripts from Spotlight

I've been advertising AppleScript a lot here. Automating a task is something, but easy access to that automation is quite important too.

Since I try to stick to Apple solutions and free software* I prefer using Spotlight instead of all the smart launchers that we have for macOS.

What I do is that I call my script names that are easy to call first in Spotlight. A few screenshots speak louder than words so here we are:

The series that start with ">" usually is scripts that I use to open something.

See how just typing ">" suggests ">BB". That ">BB" is what I use to open the files selected in Finder with BBEdit.

The one below is ">Tedit", short for "TextEdit" and opens selected files in TextEdit, etc.



If I type "c" after ">", I get the following list of choices. ">command" is to launch an arbitrary command in Terminal, ">Capture" is to use org capture in Emacs (see here and here for more information) and ">cd" just opens a Terminal tab on the front Finder window, or selected Finder folder.


When I use "<" to initiate the search, I get a different list. That series is for scripts that usually act by themselves. "<text file" creates a text file in the front Finder window and proposes to open it in BBEdit for editing, "<facturation" is an invoicing script for the job selected in Finder, "<job" is a job managing script that creates a job hierarchy in Finder based on a mail, along with an event in calendar, and then "<xls2tmx" is a TMX converter for multicolumn Excel reference data (I'll publish it when it's more polished, but creating XML data with AppleScript is documented here).


I have a few more scripts (a dozen) that I routinely call with Spotlight, which I find totally sufficient for my needs.

As you know, hitting Command+Enter when you have a selection in Spotlight is a way to reveal that selection in the Finder if it is available. So when I want to edit a script, I start by calling it in Spotlight, I hit Command+Enter when it is selected and then I call ">SEditor" (Script Editor) or ">debugger" (Script Debugger) on the selection, to open it with the appropriate application...


Ok, I do have BBEdit, Microsoft Office and Illustrator... And maybe a few others...

Open a file in your editor of choice

[Update]
Chris Stone has a nice follow-up on the BBEdit user forum.


You know how it is. You double-click on a file thinking it will open in the application that you're working with at the moment and you forget that the file type was associated with a different application...

Back to Finder, right-click on the file, select "Open with..." and you're good. But mousing around macOS can be tedious at times so here is a simple script that I was pretty much given by an ASUL co-lister and that I barely had to adapt to my workflow to make it more general.


property targetApplication : "BBEdit"

tell application "Finder" to set mySelectionList to selection as alias list
if length of mySelectionList = 0 then error "No files were selected in the Finder!"

tell application targetApplication
repeat with myFile in mySelectionList
open myFile
end repeat
activate

end tell

You notice right away that the only reference to the opening application is in the first line. You can change the application name to anything you want and have multiple copies of the script, one for each application, with an appropriate name so that you can open any file with any supporting application you want.


Here is the exact same code for TextEdit:


property targetApplication : "TextEdit"

tell application "Finder" to set mySelectionList to selection as alias list
if length of mySelectionList = 0 then error "No files were selected in the Finder!"

tell application targetApplication
repeat with myFile in mySelectionList
open myFile
end repeat
activate

end tell


The same for Script Editor:


property targetApplication : "Script Editor"

tell application "Finder" to set mySelectionList to selection as alias list
if length of mySelectionList = 0 then error "No files were selected in the Finder!"

tell application targetApplication
repeat with myFile in mySelectionList
open myFile
end repeat
activate

end tell


The same for Script Debugger:

property targetApplication : "Script Debugger"

tell application "Finder" to set mySelectionList to selection as alias list
if length of mySelectionList = 0 then error "No files were selected in the Finder!"

tell application targetApplication
repeat with myFile in mySelectionList
open myFile
end repeat
activate
end tell


The same for Word:


property targetApplication : "Microsoft Word"

tell application "Finder" to set mySelectionList to selection as alias list
if length of mySelectionList = 0 then error "No files were selected in the Finder!"

tell application targetApplication
repeat with myFile in mySelectionList
open myFile
end repeat
activate

end tell


You get the drift.

Some applications don't work that way, so here is the code for Emacs.app:


use AppleScript version "2.4" -- Yosemite (10.10) or later
use scripting additions

tell application "Finder" to set fileSelection to selection as alias list

try
tell application "System Events" to tell process "Emacs" to set frontmost to true
on error
tell application "/Users/suzume/Documents/Code/emacs/nextstep/Emacs.app"
activate
delay 1
end tell
end try

# return

repeat with selectedFile in fileSelection
set the clipboard to (POSIX path of selectedFile)
tell application "/Users/suzume/Documents/Code/emacs/nextstep/Emacs.app"
tell application "System Events"
delay 0.5
keystroke "x" using {control down}
keystroke "f" using {control down}
keystroke "a" using {control down}
keystroke "v" using {command down}
keystroke "k" using {control down}
key code 36 # Escape
delay 0.1
end tell
end tell

end repeat

The code makes use of UI scripting because Emacs does not support Applescript, but it works just as well.

What you do now, is create one script for each application you want to open your files with, save the script with a name that Spotlight will easily call first (something like ">BB" for opening in BBedit) and you're done!

Thank you Chris Stone on ASUL (and all the others) for your help !

Wordpress site translation (1) install a local copy

I'm currently working on 2 WP sites. One is the sub-site of a world-wide IT organization, the other one is the main site of a local business. I had forgotten how site localization can be a pain, so here is a summary of the solutions I'm using for the 2 sites.

The main issue with any kind of site (be it WP or any other system) is access rights. If you don't have full access rights (or only limited access), you can only do what the client allows you to do. Depending of the l10n savviness of the client, that can be a lot or very little.

So let's say that you work directly for the client and you have full access rights to the site.

First you don't want to work directly on the site. You want to install the site on your machine and have it run locally to be able to see all your changes and validate them before you reproduce them online.

Also, you want to be able to manage your changes and know exactly what was that change your made for. You want to have granular control of all the modifications and for that you'll need a version control system. That way you can revert any modification any time you want.

  1. Follow the instructions here to install a "blank" WP site locally and to be able to run it: https://codex.wordpress.org/Installing_WordPress_Locally_on_Your_Mac_With_MAMP
  2. (Install and) Use the "All-in-One WP Migration" plugin on the online site to export all the data (an FTP download only won't work, there are databases, etc. that you can't access from FTP)
  3. Use that same plugin on the local site to import the site
  4. Now you have a copy of your online site running locally. Changes that you'll do locally will be live right away so that you can test them. They will not affect the online site.
  5. To have granular control of your modifications, use git to create a version control repository for your site: enter the root of your site and run "git init", add all the files to the repository.
  6. You need a robust backup system. Something that does everything automatically so that you don't loose too much data (or any data at all) in case of problem. Time Machine is good but don't hesitate to use something more sophisticated.
  7. You can now start working on the site localization.

WP is a mess when it comes to translating a whole site. There are no integrated mechanisms to access all the localizable parts: you have to use plugins to create the l10n infrastructure, then plugins to export the theme strings, then whateverelse to actually access the textual contents of the site.

I'll write more later about the second phase of the l10n: the actual translation process.

From Finder to Terminal: cd anywhere

At a point in a Mac user life, the Terminal utility and all the command line applications that it brings to the game become a daily necessity. Typically, you work in a Finder window and want to work on the window items from the command line. For that, you can go up to the parent window, select the folder that you just exited and copy it, move to terminal, hit "cd", add a space, paste the folder and hit "Enter". That's a lot of fiddling around.


I just checked and found that I needed about 10 seconds to complete the task. 10 seconds, 4 times a day, 5 times a week, 40 times a year and you've lost 8,000 seconds = more than 2 hours. Eventually you'll notice that you're wasting time on this particular task and you end up either cursing yourself that you can't go faster, or start looking for a solution.
Here is my take on the problem.
On a side note, I spent way more than 2 hours to find that solution (and all the solutions that I write about here). Namely, I had to learn enough AppleScript, then I applied that knowledge to Finder and Terminal, then I found all the issues that made this a non trivial task, then I asked around (eternal thanks to the members of the AppleScript Users list hosted by Apple), then I tried a new implementation, then I was not satisfied with it, rewrote the whole thing and that's where I stand today. But the time spent on learning AppleScript and the workings of the various applications translates into knowledge (along with its own lot of frustration) that I can apply to other issues, while not spending that time only translates in frustration and a sense that you can't do much with computers...




use AppleScript version "2.4" -- Yosemite (10.10) or later
use scripting additions

tell application "Finder"
activate
try # if what is selected in Finder is a folder, then use that folder
if class of item 1 of (selection as list) is folder then
set myFolder to item 1 of (selection as alias list)
else # if nothing is selected or if the selection is not a folder, use the parent folder
set myFolder to insertion location as alias
end if
on error # if nothing works, default to using the Desktop
set myFolder to desktop as alias
end try
set myPath to quoted form of (POSIX path of myFolder)
set myCommand to "cd " & myPath
end tell

# I use a separate "handler" to launch the command.
# That handler can be saved in a script library so as to be able to call it from other scripts

my launchMyCommand(myCommand)

# A handler is useful because what matters is what it outputs, not how it works.
# So, if at one point in the future I decide that this way of launching a command in Terminal is not efficient anymore, I can change the way the handler works but I won't have to change the scripts that call it.

on launchMyCommand(myCommand)
# First I use GUI scripting to create a new Terminal window
tell application "Terminal" to activate
tell application "System Events" to tell application process "Terminal"
set frontmost to true
delay 0.1
keystroke "n" using {command down}
end tell
# Then I ask the newly created window to run the command
tell application "Terminal"'s front window
delay 0.1
do script myCommand in its last tab
activate
end tell
# And I eventually merge that window to the other so as to keep everything tidy
tell application "System Events" to tell application process "Terminal"
set frontmost to true
delay 0.1
keystroke "m" using {control down, command down}
end tell
return

end launchMyCommand

I save this script as an AppleScript application and I call it ">cd". Now when I am working in Finder, I just call Spotlight with a system shortcut, I start hitting >c and Spotlight autocompletion proposes >cd.app, I hit Enter and I'm in Terminal with a window opened on the item I wanted.

Searching for empty translations in OmegaT

OmegaT searches are very powerful. One feature OmegaT does not have (yet?) is the ability to register common searches for later use.
There are at least 2 RFEs for that on the OmegaT development site, one registered in 2006 (by me) and one in 2014.

In the meanwhile, there are at least 2 searches that you want to remember:


  1. searches for non translated segments
  2. searches for segments that have been set to <EMPTY> (they are translated but the translation being empty, the source won't appear in the target document).

Searches for non translated segments

The logic is straightforward:

You want to search for any one character in source that is untranslated.


In a search, "any one character" can be expressed by the regular expression "." (period). So you put a period in the search field and you make sure you have selected "Regular expressions" below it. That "any one character" is to be found in "source", so you uncheck anything else but "source" in the line below that. Then you specify "Untranslated", since that's exactly what your looking for, and you can eventually select "all matching segments" to make sure non unique segments are all displayed.


The search scope will be "Project" and only "Memory".





Searches for <EMPTY> segments

In OmegaT, when a segment is left untranslated, the source text appears in the target document. An easy way to get around this is to translate the segment with a space. The problem is that sometimes you really want to not use anything in target. For this, OmegaT allows you to "Set [an] empty translation" in the Edit menu. Once you do that, the segment will be empty but translated (it appears in the same color as the other translated segments when you select "Mark translated segments" in the View menu), and OmegaT will display it with the <EMPTY> string when you've left it.

To search for such segments, the logic is a bit different:


You want to search for an empty string in target that is translated.


In a search, "an empty string" can be expressed by the regular expression "^$" (caret, followed by dollar). The ^ stands for the beginning of the line and the $ for its end, with nothing in between the string is empty. So you put a caret followed by a dollar sign in the search field and you make sure you have selected "Regular expressions" below it. That "empty string" is to be found in "target", so you uncheck anything else but "target" in the line below that. Then you specify "Translated", since that's exactly what your looking for, and you can eventually select "all matching segments" to make sure non unique segments are all displayed.


The search scope will be "Project" and only "Memory".




Selecting stuff with AppleScript

There was a tweet about Numbers the other day:

#applescript can be such a pain sometimes to use. Simple things, like getting the selection of the current cell in #numbers is not easy info to come by.

I totally understand the author's feeling and my first take was based on a misunderstanding: in the tweet where my reply is (that you can see below his) I took his request as looking for the value of the selected cell, but now that I think of it, he meant "the selected thing within the current cell". So let's take a minute to see how hard it is to find that information in Number's dictionary (hint: it's not there, as far as I can tell):

We have 2 items to base our investigation on: "selection" and "cell".

Looking for "selection" does not bring anything interesting, we only get "selection range" which is a property of table and returns the "cells currently selected in the table." So let's check "cell". We end up with 1 class and 2 elements (one of table and one of range). So let's check the class:

celln [inh. range] : A cell in a table

We get a number of properties for cell, including value that return various objects (number, date, text, boolean, or missing value) but further investigation does not help us finding something that returns the textual selection.

In fact, checking the dictionaries of the main applications delivered by Apple, only 2 seem to have a way to get a textual selection: Script Editor and Xcode. Page, Keynotes, Numbers, Notes, Preview, TextEdit, Contacts, Calendar, Reminders, Safari, etc. don't have anything. Finder, Mail, Terminal have a "selection" mechanism but only to select objects specific to their models and not to select a textual range.

Now, that doesn't mean it is not possible to get the textual selection in the above applications, just that a reasonable investigation into the various dictionaries did not provide us with that information.

So, now that we're stuck, the only path I'd think of to access that textual selection is to use GUI scripting to copy the selection, put it in the clipboard and access it from there.

tell application "Numbers"
activate
delay 0.1
tell application "System Events"
keystroke "c" using {command down}
end tell
end tell

set mySelection to the clipboard

Ok, it's ugly. But we got it.

Last but not least, I'd like to go back to that "selection" thing.

In Script Editor it's very easy to use:

tell application "Script Editor"
tell document "Untitled 3"
selection's properties
end tell
end tell

--> {class:selection-object, character range:{35, 60}, contents:"tell document \"Untitled 3\""}

We get textual information but only the actual text contents, nothing like what the clipboard tells us (with clipboard info for ex).

In Xcode we seem to be able to get the "selected character range" only of source files. RTF files return errors.

tell application "Xcode"
selected character range of document 4
end tell
--> {1, 5}

and it's easy to get mixed up since for each independent document opened, Xcode will create a "workspace document" that includes it. So if we just create a single source file outside of any project, we still need to refer to it as document 2 because document 1 will be the enclosing workspace...


Some applications I use frequently have good selection support: BBEdit works a bit like Script Editor where a simple "selection" in the application tell block will return the user visible selection. Word needs "selection's content" to return the textual value of the selection but selection itself offers plenty of properties including style, etc.

Finding one's way in an application's AppleScript dictionary...

The other day I wanted to find a way to accelerate the process of zooming a Word window so that it fits the width of the document. It's something I've done manually thousands of times over the years. Just go to Display, then Zoom, select the option and hit Enter.

I know that Word is scriptable but everything looked so complex that I never really tried. When I script in uncharted territory I usually go the top-bottom way: I get a document, check it's properties and go deeper and deeper until I find what I need. The issue with this approach is that there are so many different classes and sub-classes and properties all over that you easily get lost and frustrated.

I just tried the bottom-up approach with this Word feature and it worked pretty well: start from what you thing is the end property and go up the ladder to the highest level object.

In the case at hand, I suppose the element I'm looking for has "fit" in its description. That's my only assumption.

So, here we go. Open Script Editor, open the Microsoft Word dictionary and search for "fit".

In the "Microsoft Word Suite" we find 2 properties and 1 command:

fit text width is a property of "selection object"

fit text width (real) : Returns or sets the width in the current measurement units in which Microsoft Word fits the text in the current selection.

page fit is a property of "zoom"

page fit (page fit none/page fit full page/page fit best fit) : Returns or sets the view magnification of a window so that either the entire page is visible or the entire width of the page is visible.

fit to pagesv : Decreases the font size of text just enough so that the document will fit on one fewer pages. An error occurs if Word is unable to reduce the page count by one.

A cursory reading tells us that we'd like to try "page fit" first. We know it is a property of "zoom", which is defined as:

zoomn [inh. base object] : Contains magnification options, for example, the zoom percentage for a window or pane.

Now we're getting closer to bridging our "bottom" (fit) to some "up" (which would be a document, or a window). Since we do have a reference to a window zoom percentage in the definition let's check "window" and see what we come up with.

The first thing we get is "active window", and the first item is:

active window (window, r/o) : Returns the currently active window object.

which is a property of application. active window returns a window object, so let's check what window objects are made of.

A glance at the list of properties of a window does not give us any hints at how to link a window to a zoom... There are no zoom properties so we have to go back to zoom and find hints there.

There is a second item for zoom, it is a property of a view:

zoom (zoom, r/o) : Returns the zoom object associated with this view object.

We're one step higher now, and since the definition of view is:

viewn [inh. base object] : Contains the view attributes, show all, field shading, table gridlines, and so on, for a window or pane.

we have a connection to the window that we found earlier.

If we check window again, we see that it indeeds has a view property:

view (view, r/o) : Returns a view object that represents the view for the window.

So let's put this together:

active window is a window and has a view property that has a zoom property that has a page fit property which can hold one of the following 3 values: page fit none/page fit full page/page fit best fit

To make sure that we're not missing anything let's check the code item by item, I assume that you have a Word document open, otherwise the result will be "missing value".

tell application "Microsoft Word"
get active window
end tell
--> active window

so far, so good.

tell application "Microsoft Word"
get view of active window
end tell
--> view of active window

no issue with that

tell application "Microsoft Word"
get zoom of view of active window
end tell
--> zoom of view of active window

we're progressing

tell application "Microsoft Word"
get page fit of zoom of view of active window
end tell
--> page fit full page

Boom ! We made it. Our document is in full page view.

So, let's set it to "page fit best fit":

tell application "Microsoft Word"
set page fit of zoom of view of active window to page fit best fit
end tell

Et voilĂ ! The window is now in page width fit.

I'm not sure which is the fastest: checking the web for a "zoom my document to page width in AppleScript" answer or finding your way into the dictionary to find the answer yourself, but I know which will help you be proficient with AppleScript faster...

Simple XML creation with AppleScriptObjectiveC

(*
This article is an attempt at putting together a practical introduction to using AppleScriptObjectiveC from all the information I gathered when creating a stand-alone application that required XML generation. Including the code, it is 3000 words. It's trivial for most of you, but it took me quite some time to put all the parts together and then to document them. Everything is still not super clear, so go ahead and tear it apart. :) I first give the code without any comments and then I add block comments to explain what needs explanations.

The code generates an omegat.project file that is equivalent to what OmegaT generates when creating a new project. I'm using that generation code in a bigger script that creates full fledged OmegaT projects without going through the OmegaT interface. The code can be applied to any kind of generic XML generation with a few tweaks. I use something similar in an Excel to TMX conversion script as well. I'll eventually publish both here.
*)

use AppleScript version "2.4" -- Yosemite (10.10) or later
use framework "Foundation"
use scripting additions

on CreateOmegaTProjectFile(ProjectSettings)
set project_tags to {"source_dir", "source_dir_excludes", "target_dir", "tm_dir", "glossary_dir", "glossary_file", "dictionary_dir", "source_lang", "target_lang", "source_tok", "target_tok", "sentence_seg", "support_default_translations", "remove_tags", "external_command"}
set masks to {"**/.svn/**", "**/CVS/**", "**/.cvs/**", "**/desktop.ini", "**/Thumbs.db", "**/.DS_Store"}
set valueindex to 0
set projectRoot to current application's NSXMLNode's elementWithName:"omegat"
set theProject to current application's NSXMLNode's documentWithRootElement:projectRoot
theProject's setCharacterEncoding:"UTF-8"
theProject's setStandalone:true
set project to current application's NSXMLNode's elementWithName:"project"
set projectVersion to current application's NSXMLNode's attributeWithName:"version" stringValue:"1.0"
project's addAttribute:projectVersion
projectRoot's addChild:project
repeat with child in project_tags
set valueindex to valueindex + 1
if contents of child is not "source_dir_excludes" then
set child to (current application's NSXMLNode's elementWithName:child stringValue:(item valueindex of ProjectSettings))
(project's addChild:child)
else
set child to (current application's NSXMLNode's elementWithName:"source_dir_excludes")
(project's addChild:child)
set source_dir_excludes to (project's elementsForName:"source_dir_excludes")'s firstObject()
repeat with mask in masks
set mask to (current application's NSXMLNode's elementWithName:"mask" stringValue:mask)
(source_dir_excludes's addChild:mask)
end repeat
end if
end repeat
set theData to theProject's XMLDataWithOptions:((get current application's NSXMLNodePrettyPrint) + (get current application's NSXMLDocumentTidyXML))
theData's writeToFile:(item 16 of ParametersList) options:(current application's NSDataWritingAtomic) |error|:(missing value)
end CreateOmegaTProjectFile


set ProjectSettings to {"PATH_1", "MASKS", "PATH_2", "PATH_3", "PATH_4", "FILE_5", "PATH_6", "LANG_7", "LANG_8", "TOKENIZER_9", "TOKENIZER_10", "SEGMENTATION_11", "DEFAULT_TRANSLATION_12", "REMOVE_TAGS_13", "EXTERNAL_COMMAND_14", ((POSIX path of (path to desktop folder)) & "omegat.project")}

my CreateOmegaTProjectFile(ProjectSettings)


(*
There are a number of solutions in AppleScript to create XML but nothing out of the box to generate generic data. System Events cannot create generic XML, it can only modify existing files. The only format it can natively produce is the "property list" format, used to store application preferences, etc. There are solutions that involve concatenating strings and doing a lot of checks on the data to make sure the output is valid (in XML a number of characters are forbidden, so all strings that are concatenated need to be thoroughly checked for those) but they are neither elegant nor robust. There are libraries available, but they do a lot more than what casual users need.

I thought that offering a simple solution for a simple problem that would provide the reader with a step-by-step introduction to reading the Foundation documentation and understanding how to use it with vanilla AppleScript was a better approach, at least for me, since short of having scriptable applications that do what you want, the only way to do really complex things in AppleScript is to use Foundation.

My problem, which is common to all amateur AppleScript users, is a problem of discoverability and of fluency. AppleScript is not a trivial language, a systematic description of its features is non-existent, and when you want to go beyond the "tell Finder to sort the mess on my Desktop" you end up needing to check a lot of references that either consider that you know a lot, or that you don't know much. There is no middle ground and no easy way to find what you need without actually asking. In fact, I still wonder how I could have written this code without the help of people who just seem to "know". There is no clear discoverability path to the information I gathered here.
AppleScriptObjC is not described in the AppleScript Language Guide issued by Apple. The 3rd edition of "Learn AppleScript" by Hamish Sanderson and Hanaan Rosenthal from Apress (2010) discusses some aspects of AppleScriptObjC but the document that best describes it is "Everyday AppleScriptObjC" by Shane Stanley (2015). The Foundation framework, along with other frameworks that can be accessed by AppleScriptObjC are described in the developer documentation (either in Xcode or online) with Objective-C use in mind (syntax, etc.) so we'll use the 3 references to go through the code.

Becoming fluent in a language is a problem both for the linguist and for the programmer. Fluency only comes with regular practice based on sound references, and regular contact with "natives". As far as AppleScript (and AppleScriptObjC) is concerned, "natives" can be found in a number of very interesting places on the internet. The first is the official AppleScript User List (ASUL) hosted by Apple. Apple has been a bad host in recent years so fear of losing this resource has motivated some of its users to create an independent list, hosted on groups.io. There also is the Macscripter web forum. I'm not super fond of web forums. Their user interface is clumsy more often than not and this one is no exception. But it's been around for ever and a number of world-class experts are there to comment on code and generally manage the community. Then, there is the ScriptDebugger's user forum. Conversations there generally revolve around higher level topics, the web forum is a modern one and the user experience is of extremely high quality.

Links:

Ok, so, you're all set, no more chatting, let's check the code.
*)

use AppleScript version "2.4" -- Yosemite (10.10) or later
use framework "Foundation"
use scripting additions

(*
As seen in the script headers above, we'll be using the "Foundation" framework which allows us to directly work on the XML tools that macOS offers. Without this declaration we can't access what we need.

This code will generate an XML file that will reproduce the following typical omegat.project file, with default values for the project folders, English as source language, Japanese as target language, sentence segmentation and default translations enabled, and no external command to process when creating the target files.

In XML, the order of tags as well as the white space used to present them is irrelevant, so the appearance of the data will change depending on how the code was produced. It may not be exactly like a "genuine" OmegaT file, but as far as the meaning of the data and OmegaT proper are concerned that is not relevant.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<omegat>
    <project version="1.0">
        <source_dir>__DEFAULT__</source_dir>
        <source_dir_excludes>
            <mask>**/.svn/**</mask>
            <mask>**/CVS/**</mask>
            <mask>**/.cvs/**</mask>
            <mask>**/desktop.ini</mask>
            <mask>**/Thumbs.db</mask>
            <mask>**/.DS_Store</mask>
        </source_dir_excludes>
        <target_dir>__DEFAULT__</target_dir>
        <tm_dir>__DEFAULT__</tm_dir>
        <glossary_dir>__DEFAULT__</glossary_dir>
        <glossary_file>glossary.txt</glossary_file>
        <dictionary_dir>__DEFAULT__</dictionary_dir>
        <source_lang>EN</source_lang>
        <target_lang>JA</target_lang>
        <source_tok>org.omegat.tokenizer.LuceneEnglishTokenizer</source_tok>
        <target_tok>org.omegat.tokenizer.LuceneJapaneseTokenizer</target_tok>
        <sentence_seg>true</sentence_seg>
        <support_default_translations>true</support_default_translations>
        <remove_tags>true</remove_tags>
        <external_command></external_command>
    </project>
</omegat>

The tokenizers are generally not set by the user because OmegaT would automatically select them based on the corresponding language codes.
Anything else is user settable, even the "excludes" files, even though that is an advanced setting that most users should not have to consider.

So, we're going to create a handler that takes as input the following values:

• source_dir_value: path to directory
• source_dir_excludes_masks: list of mask tags
• target_dir_value: path to directory
• tm_dir_value: path to directory
• glossary_dir_value: path to directory
• glossary_file_value:  path to text file
• dictionary_dir_value: path to directory
• source_lang_value: string language code (we do need to check the validity of the code based on the appropriate ISO standard, but we consider here that the check has been made upstream, if only to keep the XML generation code free of such external checks)
• target_lang_value: string language code (see above)
• source_tok_value: string automatically proposed by the script, based on language code (here again, the tokenizers corresponding to the source language should be a valid tokenizer but we let the upstream code select and validate it to stick to the core XML generation code)
• target_tok_value: string automatically proposed by the script, based on language code (see above)
• sentence_seg_value: boolean
• support_default_translations_value: boolean
• remove_tags_value: boolean
• external_command_value: string to be sent to exec when the target files are created, can be empty if no action is requested.

We'll make this code a handler so that we can call it without having to copy it every time we need it. This is better because it allows to logically separate portions of the code.
*)

on CreateOmegaTProjectFile(ProjectSettings)
(*
The first few lines below are necessary to initialize the XML tags. First comes "project_tags", a list of tags that are used in the file. There are 15 tags, of which 14 tags only take a simple value, either a path, or a text string, etc. As we can see above, "source_dir_excludes" takes a list of "masks" tags which we'll create with "masks", which contains the patterns that describe the type of files to be ignored by OmegaT. Last, we initialize "valueindex", an index that will be used to associate the tag to its value found in the list that we feed the handler.
  Then comes the beginning of the XML structure creation.
*)
set project_tags to {"source_dir", "source_dir_excludes", "target_dir", "tm_dir", "glossary_dir", "glossary_file", "dictionary_dir", "source_lang", "target_lang", "source_tok", "target_tok", "sentence_seg", "support_default_translations", "remove_tags", "external_command"}
set masks to {"**/.svn/**", "**/CVS/**", "**/.cvs/**", "**/desktop.ini", "**/Thumbs.db", "**/.DS_Store"}
set valueindex to 0
(*
We're first going to create an XML element that we'll then use as the XML document root. We'll create the other elements once that is done.
*)
set projectRoot to current application's NSXMLNode's elementWithName:"omegat"
(*
This is our first line of AppleScriptObjC. First question: how do we call the Foundation items that we need to work with?
"Everyday AppleScriptObjC":
"Class names are effectively properties of the current application (which is, in turn, the parent of AppleScript in your script)."

"Learn Applesccript":
"AppleScriptObjC presents Cocoa classes as class elements of the current application object."

So, everything we'll call from Cocoa will be called from "current application", hence the use of "current application's NSXMLNode".

In the Xcode documentation, NSXMLNode is described as, well, an XML node.
 
As the documentation says, an XML node can be anything from: an element, an attribute, text, a processing instruction, a namespace, or a comment.
 
Here we use the "elementWithName" method to create the element. Clicking on its description in the Xcode documentation browser shows that the method is a "type method" and returns "an NSXMLElement object with a given tag identifier, or name".
 
"Type methods" apply to classes, they are generally used to create objects which are specific instances of a given class. When we'll work on the objects themselves we'll need "instance methods". In the documentation, "type methods" have a "+" prefixed to their name and "instance methods" have a "-" prefixed instead.
 
The syntax for such method calls is methodName:parameter, so here we have: elementWithName:"omegat"  This syntax will be used for all the other elements that we create.
 
It is important to note that we are using a shortcut here. As Shane wrote on ASUL:
"(elementWithName is) what's known as a convenience method. You're actually making a particular subclass of NSXMLNode, an NSXMLElement.
You could have used:
set projectRoot to current application's NSXMLElement's alloc()'s initWithName:"omegat"
But convenience methods are common, if not following any particular logic of when and where they're provided. Something like "stringWithString:" instead of "alloc()'s initWithString:" is a common example."
 
To make sense of that we need to know how Objective-C/Cocoa works:
"Everyday AppleScriptObjC":
"The equivalent (of AppleScript's make) in Cocoa is actually a two-stage process: first the object is created by allocating memory for it, and then it is initialized.  The first stage is done using the +alloc method. You will not see it listed (in the documentation) because it is a method all classes inherit from the NSObject class."
If we check the NSObject description, we see "+ alloc" which is described as "Returns a new instance of the receiving class" and later "You must use an init... method to complete the initialization process." Then we see "- init", which is described as "Implemented by subclasses to initialize a new object (the receiver) immediately after memory for it has been allocated." In the method description we also see that it only exists for Objective-C and not for Swift which only has "init()" to cover allocation and initialization in one fell swoop.
So, instead of using that longer process, we prefer to use that "convenience method" and make the code slightly shorter.
Foundation reference:
*)
set theProject to current application's NSXMLNode's documentWithRootElement:projectRoot
(*
Here again, we'll use a convenience method that does not require us to go through the alloc-init process. Now we have a XML document and its root element. We'll need a few more things to make our output look like what OmegaT needs.
Foundation reference:
*)
theProject's setCharacterEncoding:"UTF-8"
(*
"setCharacterEncoding" is not documented in the Foundation documentation. The closest thing related to an NSXMLDocument that we have is "characterEncoding" (notice the case for "Character": lower case in the documentation, upper case here), which is described as an "instance property", which seems to correspond since theProject is indeed an instance of NSXMLDocument.
The "set" prefix is explained in "Everyday AppleScriptObjC":
"To set a new value for a Cocoa property, assuming it is not read-only, you use the word set, followed by the property name with the  first letter in uppercase, followed by a colon or underscore and parentheses, depending on the syntax.  The single argument is then the proposed new value."
Now we understand why "set" is prefixed and why characterEncoding is changed to CharacterEncoding when prefixed with set. If we need to get the characterEncoding property of the document, let's not forget about the letter case...
Setting characterEncoding happens to be enough to create the <?xml version="1.0" encoding="UTF-8"?> line in our example and to actually encode the data in UTF-8.
Foundation reference:
*)
theProject's setStandalone:true
(*
setStandalone works like setCharacterEncoding and adds the standalone="yes" part to our xml declaration.
I had the following line in a previous version of this code:
theProject's setDocumentContentKind:(current application's NSXMLDocumentXMLKind)

but we can dispense with it since XML is the default kind of XML document (other kinds include HTML, XHTML and text). Still there is something in this line that we ought to remember for other occasions. "documentContentKind" is an instance property, like "standalone". To set it we must thus use "setDocumentContentKind". The possible values for a documentContentKind are documented as "enumerations", of which NSXMLDocumentXMLKind is the default value in the case of an XML document. To use NSXMLDocumentXMLKind as a value, we must do as we've done for other Cocoa items: call them from the current application, hence the (current application's NSXMLDocumentXMLKind).

Foundation reference:
*)
set project to current application's NSXMLNode's elementWithName:"project"
set projectVersion to current application's NSXMLNode's attributeWithName:"version" stringValue:"1.0"
project's addAttribute:projectVersion
projectRoot's addChild:project
(*
We're still in NSXMLNode territory here. Now we're creating the "project" element with a "version" attribute that has a "1.0" value.
To do this, we first create the element and we then separately create an attribute node by using the "attributeWithName:stringValue:" method (see the Xcode description) that actually comes in two parts: the attributeWithName part and the stringValue part.

Once created, the 2 nodes have no relation to each other or to anything we've created so far. We need to "link" everything together now and we do that with the 2 lines that follow:
"addAttribute" is documented as an instance method, which is good because "project" is an instance of "NSXMLNode" and "adds an attribute node to the receiver", which is exactly what we're trying to do. The parameter is "projectVersion", the attribute node that we created 1 line before that.

Now we have an element that looks like <project version="1.0"></project> and we need to add it as a child of the document root element. That's what "addChild" does: an instance method that "adds a child node after the last of the receiver’s existing children". The receiver is projectRoot and the child is project.
Foundation reference:
*)
repeat with child in project_tags
set valueindex to valueindex + 1
if contents of child is not "source_dir_excludes" then
set child to (current application's NSXMLNode's elementWithName:child stringValue:(item valueindex of ProjectSettings))
(project's addChild:child)
else
set child to (current application's NSXMLNode's elementWithName:"source_dir_excludes")
(project's addChild:child)
set source_dir_excludes to (project's elementsForName:"source_dir_excludes")'s firstObject()
repeat with mask in masks
set mask to (current application's NSXMLNode's elementWithName:"mask" stringValue:mask)
(source_dir_excludes's addChild:mask)
end repeat
end if
end repeat
(*
Now that we've been through the basics of using Foundation to create a basic XML structure, the rest of the code is very straightforward. We're running a loop on the tag list that was created at the beginning of the script and for each "child" we'll set a "stringValue" that corresponds to the item at the same position in the ProjectSettings that has been sent to this handler.
Once the element and its string value are created, we add the whole as a child to the "project" element that we created just above.
The only exception to that process is when we bump into "source_dir_excludes". Here, what happens is that we do not use stringValue  to set the element value since it is going to be made of a list of <mask> tags. Instead of that, we first create the tags and add them one by one as children to "source_dir_excludes". When we're done with that special content, we resume the loop and deal with the other tags.
How we identify "source_dir_excludes" within the list of existing tags is interesting. We use elementsForName, an instance method for project that returns an array of all the elements with the name given as the parameter (here "source_dir_excludes"), and since we only have one here, we specify that we want to work with that array's "firstObject". That way we create a reference to the NSXMLElement "source_dir_excludes" that we can later use to add children to it. It took me a while to figure that out. Thank you Shane :)
The creation of the list of <mask> tags is straightforward and does introduce any new concept.
Foundation reference:
*)
set theData to theProject's XMLDataWithOptions:((get current application's NSXMLNodePrettyPrint) + (get current application's NSXMLDocumentTidyXML))
theData's writeToFile:(item 16 of ParametersList) options:(current application's NSDataWritingAtomic) |error|:(missing value)
(*
We're reaching the end of this XML generation code. Now we need to output the data, in readable form.

"XMLDataWithOptions" is a method that returns an NSData object and the options are listed under "NSXMLNodeOptions". The description says, "One or more options (bit-OR'd if multiple) to affect the output of the document..." where "bit-OR'd if multiple" means "added". Another thing to notice is that the second and following options (if any) seem to need a "get". Adding the "get" to the first option does not seem to be necessary.

The options we use here are: "NSXMLNodePrettyPrint" and "NSXMLDocumentTidyXML". The first "prints this node with extra space for readability", the second "changes malformed XML into valid XML during processing of the document."
"writeToFile:options:error:" is a three part instance method of NSData, which theData is. writeToFile requires a Unix absolute path, options work the same way as defined the line before: "NSDataWritingAtomic" is "A hint to write data to an auxiliary file first and then exchange the files." And error gives us information about errors while using the method. To avoid naming conflicts with AppleScript's "error", it is put between vertical bars: |error|. The description of "error" says we can use a "NULL" value, for which the AppleScript equivalent is missing value (Everyday AppleScriptObjC, p. 52 "The terms nil and its close relative NULL are used commonly in Cocoa.  They are essentially the equivalent of AppleScript’s missing value, and the scripting bridge converts between them.")
Foundation reference:
*)
end CreateOmegaTProjectFile

(*
Let's now test the code with the following values:
*)

set ProjectSettings to {"PATH_1", "MASKS", "PATH_2", "PATH_3", "PATH_4", "FILE_5", "PATH_6", "LANG_7", "LANG_8", "TOKENIZER_9", "TOKENIZER_10", "SEGMENTATION_11", "DEFAULT_TRANSLATION_12", "REMOVE_TAGS_13", "EXTERNAL_COMMAND_14", ((POSIX path of (path to desktop folder)) & "omegat.project")}


my CreateOmegaTProjectFile(ProjectSettings)