PLC (Property List Compiler) mode for Alpha.

Name:	PLC Mode
Version:	1.1
Last update:	2019-11-27 14:12:59

Introduction

The Property List Compiler (PLC) is both a syntax and a processor that lets you build property list files for Mac OS X software. The PLC language is used to write source files which are then converted dynamically into property list files (like the Info.plist files contained in application bundles).
The language was originally designed for the now defunct CodeWarrior IDE. It can now be interpreted and compiled with Xcode projects on Mac OS X using a command line tool like plcompile. This is much more flexible than maintaining property list files with hand-coded XML or using the Property List Editor. The compiler can also be used to generate files that store localized strings for different languages (like InfoPlist.strings, Localizable.strings, ServicesMenu.strings).
PLC source files usually have a .plc extension. Separate localization files usually have a .ploc extension. PLC mode makes it easy to create and edit .plc and .ploc files. It implements syntax colouring, file marking and completions.
The PLC mode in Alpha is automatically loaded when a file with a .plc or .ploc extension is opened. Have a look at the mode specific preferences: when a .plc source file is opened, choose Alpha ↣ Preferences ↣ Plc Mode Setup.
Note that this file only documents the PLC mode for Alpha. To learn more about the PLC language itself, see the documentation provided with the plistcompiler tool.

How it works

Most of the editing features offered by the PLC mode are available through completions. In particular you can insert a plist template by typing plist and hitting the completion key. Ditto for a localization template. There is also a complete mechanism for building key statements like:

    key "CFBundleDevelopmentRegion" value string "English"

For instance, type key then hit the completion key. It adds an opening quote. Hit the completion key again, a list proposes the possible keys. The chosen value is inserted and the line is completed further. Some values (like CFBundleDocumentTypes) lead, in one key stroke, to sophisticated templates. You can also type the first letters of the key, like in

    key "LS|

If you hit the completion key after LS, a partial list of choices is displayed.
The value keyword also has a specific completion proc which lets you cycle through all possible values. Type value, then hit the completion key several times to see how it works.
In order to test the PLC mode, you can open the Plc Example file: it is a tutorial with instructions that let you experiment with the completion mechanism.

Bundle Keys

For convenience, here is a list of the main bundle keys defined by Apple.

Standard Bundle Keys

CFBundleDevelopmentRegion: (String optional) The native region for the bundle. Usually corresponds to the native language of the author.
CFBundleDisplayName: (String optional) The localized display name of the bundle.
CFBundleDocumentTypes: (Array optional) An array of dictionaries describing the document types supported by the bundle.
CFBundleGetInfoHTML: (String optional) A string for displaying richer content in the Finder's Get Info panel.
CFBundleGetInfoString: (String optional) A string for display in the Finder's Get Info panel
CFBundleHelpBookFolder: (String optional) The name of the folder containing the bundle's help files.
CFBundleHelpBookName: (String optional) The name of the help file to display when help is launched for the bundle.
CFBundleURLTypes: (Array optional) An array of dictionaries describing the URL schemes supported by the bundle.
CFBundleExecutable: (String required) Name of the bundle executable file.
CFBundleIconFile: (String required) File name for icon image file.
CFBundleIdentifier: (String required) Unique identifier string for the bundle. This string should be in the form of a java package name, for example com.apple.myapp.
CFBundleInfoDictionaryVersion: (String required) Version information for the Info.plist format.
CFBundleName: (String required) The short display name of the bundle.
CFBundlePackageType: (String required) The four-letter code identifying the bundle type.
CFBundleShortVersionString: (String required) The marketing-style version string for the bundle.
CFBundleSignature: (String required) The four-letter code identifying the bundle creator
CFBundleVersion: (String required) Build number of the executable.

Keys for CFBundleURLTypes dictionaries

CFBundleTypeRole: (String) This key specifies the application's role with respect to the URL type. The value can be Editor, Viewer, Printer, Shell, or None. See “Document Configuration” for descriptions of these values. This key is required.
CFBundleURLIconFile: (String) This key contains a string entry with the name of the icon image file (minus the extension) to be used for this URL type.
CFBundleURLName: (String) This key contains a string entry with the abstract name for this URL type. This is the main way to refer to a particular type. To ensure uniqueness, it is recommended that you use a Java-package style identifier. This name is also used as a key in the Info.plist file.
CFBundleURLSchemes: (Array) This key contains an array of the URL schemes handled by this type. Examples of URL schemes include http, ftp, and so on.

Application-Specific Keys

CFAppleHelpAnchor: (String optional) The bundle's initial HTML help file.
NSAppleScriptEnabled: (String optional) Specifies whether AppleScript is enabled.
NSJavaNeeded: (Boolean/String optional) Specifies whether the program requires a running Java VM.
NSJavaPath: (Array optional) An array of paths to classes whose components are preceded by NSJavaRoot.
NSJavaRoot: (String optional) The root directory containing the java classes.
NSServices: (Array optional) An array of dictionaries specifying the services provided by an application.
NSHumanReadableCopyright: (String required) A copyright string used for display in dialog boxes.
NSMainNibFile: (String required) The name of an application's main nib file.
NSPrincipalClass: (String required) The name of the bundle's main class.

Keys for NSServices dictionaries

NSPortName: (String) This key specifies the name of the port your application monitors for incoming service requests.
NSMessage: (String) This key specifies the name of the instance method to invoke for the service. In Objective-C, the instance method must be of the form messageName:userData:error:. In Java, the instance method must be of the form messageName(NSPasteBoard,String).
NSSendTypes: (Array) This key specifies an array of data type names that can be read by the service. The NSPasteboard class description lists several common data types. You must include this key, the NSReturnTypes key, or both.
NSReturnTypes: (Array) This key specifies an array of data type names that can be returned by the service. The NSPasteboard class description lists several common data types. You must include this key, the NSSendTypes key, or both.
NSMenuItem: (Dictionary) This key contains a dictionary that specifies the text to add to the Services menu. The only key in the dictionary is called default and its value is the menu item text. This value must be unique. You can use a slash character “/” to specify a submenu.
NSKeyEquivalent: (Dictionary) This key is optional and contains a dictionary with the keyboard equivalent used to invoke the service menu command. Similar to NSMenuItem, the only key in the dictionary is called default and its value is a single character.
NSUserData: (String) This key is an optional string that contains a value of your choice.
NSTimeout: (String) This key is an optional numerical string that indicates the number of milliseconds Services should wait for a response from the application providing a service when a response is required.

Launch Services Keys

LSBackgroundOnly: (String optional) Specifies whether the application runs only in the background. (Mach-O applications only).
LSPrefersCarbon: (String optional) Specifies whether an application prefers running in the Carbon environment.
LSPrefersClassic: (String optional) Specifies whether an application prefers running in the Classic environment.
LSRequiresCarbon: (String optional) Specifies whether the application must run as a Carbon application.
LSRequiresClassic: (String optional) Specifies whether the application must run in the Classic environment.
LSUIElement: (String optional) Specifies whether the application is a user-interface element, that is, an application that should not appear n the Dock or Force Quit window.

Application Package Keys

APInstallerURL: (String required) A URL-based path to the files you want to install.
APFiles: An array of dictionaries describing the files or directories that can be installed.

Keys for APFiles dictionary

APFileDescriptionKey: (String) A short description of the item to display in the Finder's Info window.
APDisplayedAsContainer: (String) If Yes the item is shown with a folder icon in the Info panel; otherwise, it is shown with a document icon.
APFileDestinationPath: (String) Where to install the component as a path relative to the application bundle.
APFileName: (String) The name of the file or directory.
APFileSourcePath: (String) The path to the component in the application package relative to the APInstallerURL path.
APInstallAction: (String) The action to take with the component: Copy or Open.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 2003-2019, Bernard Desgraupes.
All rights reserved.
The PLC Mode package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Bernard Desgraupes nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BERNARD DESGRAUPES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.