tclOSAScript -- OSA

## TclAppleScript Extension Command

### NAME

AppleScript - Communicate with the AppleScript OSA component to run AppleScripts from Tcl.

### SYNOPSIS

AppleScript compile ?-flag value? scriptData1 ?ScriptData2 ...?componentName
AppleScript decompile scriptName
AppleScript delete scriptName
AppleScript execute ?flags value? scriptData1 ?scriptData2 ...?
AppleScript info what
AppleScript load ?flag value? fileName
AppleScript run ?flag value? scriptName
AppleScript store ?flag value? scriptName fileName

### DESCRIPTION

This command is used to communicate with the AppleScript OSA component. You can compile scripts, run compiled scripts, execute script data (i.e. compile and run at a blow). You can get script data from a compiled script (decompile it), and you can load a compiled script from the scpt resource of a file, or store one to a scpt resource. You can also get info on the currently available scripts and contexts. It has the general form

AppleScript option ?arg arg ...?

The possible sub-commands are:

AppleScript compile ?-flag value? scriptData1 ?ScriptData2 ...?
  The scriptData elements are concatenated (with a space between each), and sent to AppleScript for compilation. There is no limitation on the size of the scriptData, beyond the available memory of the Wish interpreter.

  If the compilation is successful, then the command will return a token that you can pass to the "run" subcommand. If the compilation fails, then the return value will be the error message from AppleScript, and the pertinent line of code, with an "_" to indicate the place where it thinks the error occured.

  The compilation is controlled by flag value pairs. The available flags are:

  -augment Boolean
    To be used in concert with the -context flag. If augment is yes, then the scriptData augments the handlers and data already in the script context. If augment is no, then the scriptData replaces the data and handlers already in the context. The default is yes.

  -context Boolean
    This flag causes the code given in the scriptData to be compiled into a "context". In AppleScript, this is the equivalent of creating an Tcl Namespace. The command in this case returns the name of the context as the its result, rather than a compiled script name.

    You can store data and procedures (aka handlers) in a script context. Then later, you can run other scripts in this context, and they will see all the data and handlers that were set up with this command. You do this by passing the name of this context to the -context flag of the run or execute subcommands.

    Unlike the straight compile command, the code compiled into a script context is run immediatly, when it is compiled, to set up the context.

  -name string

    Use string as the name of the script or script context. If there is already a script of this name, it will be discarded. The same is true with script contexts, unless the -augment flag is true. If no name is provided, then a unique name will be created for you.

  -parent contextName

    This flag is also to be used in conjunction with the -context flag. contextName must be the name of a compiled script context. Then the new script context will inherit the data and handlers from the parent context.

AppleScript decompile scriptName
  This decompiles the script data compiled into the script scriptName, and returns the source code.

AppleScript delete scriptName
  This deletes the script data compiled into the script scriptName, and frees up all the resources associated with it.

AppleScript execute ?flags value? scriptData1 ?scriptData2 ...?
  This compiles and runs the script in scriptData (concatenating first), and returns the results of the script execution. It is the same as doing compile and then run, except that the compiled script is immediately discarded.

AppleScript info what
  This gives info on the connection. The allowed values for "what" are:

  contexts ?pattern?

    This gives the list of the script contexts that have been. If pattern is given, it only reports the contexts that match this pattern.

  scripts ?pattern?

    This returns a list of the scripts that have been compiled in the current connection. If pattern is given, it only reports the script names that match this pattern.

AppleScript load ?flag value? fileName
  This loads compiled script data from a resource of type 'scpt' in the file fileName, and returns a token for the script data. As with the compile command, the script is not actually executed. Note that all scripts compiled with Apple's "Script Editor" are stored as script contexts. However, unlike with the "compile -context" command, the load command does not run these scripts automatically. If you want to set up the handlers contained in the loaded script, you must run it manually.

  load takes the following flags:

  -rsrcname string
    load a named resource of type 'scpt' using the rsrcname flag.

  -rsrcid integer

    load a resource by number with the rsrcid flag.

  If neither the rsrcname nor the rsrcid flag is provided, then the load command defaults to -rsrcid = 128. This is the resource in which Apple's Script Editor puts the script data when it writes out a compiled script.

AppleScript run ?flag value? scriptName
  This runs the script which was previously compiled into scriptName. If the script runs successfully, the command returns the return value for this command, coerced to a text string. If there is an error in the script execution, then it returns the error result from the scripting component. It accepts the following flag:

  -context contextName

    contextName must be a context created by a previous call to compile with the -context flag set. This flag causes the code given in the scriptData to be run in this "context". It will see all the data and handlers that were set up previously.

AppleScript store ?flag value? scriptName fileName
  This stores a compiled script or script context into a resource of type 'scpt' in the file fileName.

  store takes the following flags:

  -rsrcname string
    store to a named resource of type 'scpt' using the rsrcname flag.

  -rsrcid integer

    store to a numbered resource with the rsrcid flag.

  If neither the rsrcname nor the rsrcid flag is provided, then the load command defaults to -rsrcid = 128. Apple's Script Editor can read in files written by tclOSAScript with this setting of the -rsrcid flag.

## Notes:

The AppleScript command is a stopgap command to fill the place of exec on the Mac. It is not a supported command, and will likely change as we broaden it to allow communication with other OSA languages.

## See Also: