This is a help file for the Mac Menu in Alpha. This file should be located in the Help subfolder of Alpha's folder to show up automatically in the Help menu when Alpha is loaded.




Introduction

Mac Menu for Alpha allows you to achieve all kinds of files manipulations from Alpha and to interact with the MacOS file system with maximum flexibility.

You can act upon selections of files taken out of a folder or a hierarchy of folders and subfolders : the selection is made using a regular expression (regexp) and setting various additional conditions. You have thus full and extended control on which files you want to manipulate.

Actions executed on the selected files are : copying, moving, renaming, duplicating, trashing/untrashing, locking or unlocking, making aliases, selecting or unselecting, listing, changing creator type.

You can also get complete system information about all kinds of elements such as files, folders, disks, processes etc. and set new values for certain properties (change a type, a creator, a modification date, sharing status etc.). Commands are also provided for basic Finder's tasks : emptying the trash, restarting the computer etc.

All the commands are available from a menu called Mac Menu but the package also implements a 'shell' to execute all these functions from a command line. For instance, just type 'empty' at the prompt of Mac Shell to empty the trash. A very simple syntax is provided to write commands and to navigate in the MacOS files system.

All these actions are executed without leaving the Alpha editor. The package is almost exclusively based on Apple Events sent to the system.

See the tutorial file and read more information below for a complete description of all the items available in Mac Menu.

Installation

Automatic installation

The simplest way of installing the package is to use the automatic installation facility. Just double-click on the "OPEN TO INSTALL" file. Opening this file tells Alpha that a new package has to be installed : the procedure is automatic. Alpha knows where to store the different elements of your 'Mac Menu' package.

Manual installation

If you prefer a manual installation, take the following steps :

  1. put the "macMenu" folder in the "Menus" subfolder of the "Tcl"folder which is located at the same level as your Alpha application

  2. put the "Mac Menu Help" file and the "MacShell.help" file in the"Help" folder located at the same level as your Alpha application. Next time you launch Alpha, you will see a "Mac Menu Help" item in the Help menu.

  3. put the "MacMenu-Example" and "MacMenu-Example.tcl" files in thefolder called "Mode Examples" and located at the same level as the Alpha application.

  4. launch Alpha. You have to rebuild the package indices and the Tcl indices. "Rebuild Package Indices" is in the Config-"Packages menu, and "Rebuild Tcl Indices" is in the Tcl menu.

  5. quit Alpha and relaunch it : that's all there is to it.

After installing

Have a look at the Mac Menu preferences in the "Packages" submenu of the "Config" menu. You can set various flags there. More explanations below.

Quick start

Suppose you have a folder containing all the pages of a Web site and you want a list of the image files having extension gif or jpeg. In the "List Files" dialog window, specify the folder and click on the "Predef Exts" button. In the new window check gif and jpeg and press OK. This brings back to the previous window in which the Files Filter is now set like this :

     .*\.(jpeg|gif)
Click OK and you get the list you wanted. You could have specified "In all Subfolders" in the "process" popup menu to get a list including files in the nested subfolders.

Suppose now you want to send to another folder a copy of the files taken out of this structure whose names meet the following requirements :

You have to build a regular expression representing the first three conditions. In the "Copy Files" dialog window, the Files Filter should be :
     [AP].*_XY\.html?
Then click on the "Add conditions" button and in the new window, set the last two contitions like so :
     Modification date after 2000-12-25
     Size greater than 128k
leaving the other fields blank. Clicking on "Apply" brings back to the previous dialog in which you set the paths of the source and the target folders. In the "Process" popup menu, choose "in all Subfolders". Now click on "Copy" and there you go. The copy sent to the target folder will reproduce exactly the same hierarchy of folders and subfolders but will contain only the files corresponding to the required scheme.

Now suppose you want to rename the selected files. You want the new name to be like this :

Unless you cancelled in the "Copy Files" dialog window, all your settings will have been preserved when you open the "Rename Files" window. You have just one modification to do in the Files Filter regular expression : add a pair of parentheses to capture the .* part which will be refered to as \1 in the substitution expression :
     [AP](.*)_XY\.html?
The replacement string will then be :
     Q\1\.old
To have uppercase letters, click on the "Add options" button. In the new window, click on the "Casing" checkbox and choose UPPERCASE in the popup menu. Click "Apply" then click "Rename". That's all there is to it.

Dialogs description

Almost all the dialog windows in which you specify the options and conditions related to some kind of file manipulation share common elements.

Main selection dialogs

The top part of the dialog is an edit field in which you write a regular expression describing the naming scheme of the files you want to act upon. It is very important to note that it obeys the regular expressions syntax and not the so-called 'globbing syntax' used in some Tcl commands. For more info about the regular expressions, read the "Regular Expressions" file in the Help Menu. Regular expressions are a very powerful syntax designed to describe abstractly almost any kind of strings.

The top part of the dialog windows also contains two check boxes called "case sensitive" and "negate filter" : check or uncheck them as you want. If the "negate filter" checkbox is checked, Mac Menu will search for files which do NOT correspond to the files filter regular expression. If the "case sensitive" checkbox is unchecked, Mac Menu will not take casing into account : uppercase and lowercase letters will be considered equivalent. The "Add Conditions" button calls a new dialog window in which you can specify additional options concerning the MacOS type or creator of the files, the date of creation or modification and the size (in kbytes). Dates are indicated in the ISO format (yyyy-mm-dd).

NB: the "negate filter" flag, if set, negates the filtering regular expression but NOT the additional conditions. They are... additional.

A pop-up menu lets you specifiy whether an action should be taken on all the files corresponding to the filter in the current directory, or should be extended to the subfolders down to a specified level as well or even to all subfolders, subsubfolders etc.

Almost all the dialog windows contain an edit field to specify the source folder : the folder in which to look for files or the folder at the top of the hierarchy if subfolders are concerned too. You can write the complete path of the source folder in the edit field or use the "Set" button to browse through the file system with a standard dialog.

When relevant (to copy or move files), an additional edit field lets you choose a target folder. If files are taken out of a hierarchy, the hierarchy will be transported to the target folder : if corresponding subfolders do not exist in the target folder, they will be created automatically. If the target folder itself does not exist, it is created too so you can specify the name of a non existing folder in the edit field. Use the "Set" button to choose an existing folder.

All the dialog windows have at least two buttons at the bottom: one to execute the desired action, one to cancel.

Renaming dialog

The "Rename Files" dialog window contains a specific field to set the renaming scheme : it uses the substitution syntax of regular expressions. So you can use the special substitution symbols : & to designate the entire match, \1, \2 etc. to designate sub-expressions corresponding to pairs of parentheses in the files filtering regular expression. A button called "Add Options" brings up a new dialog window in which you can choose more options. They concern casing, incremental numbering and truncating. Tey have the following meaning :

Particular dialogs

The "Trash Files" dialog has no target folder field : the target is the trash. The "Untrash Files" dialog is different from the others and proposes two options : "last trashed" or "all". In the first case, will be untrashed (i-e sent back to their original position in the files system) only the files most recently trashed from the "Trash Files" item in the Mac Menu. This is a sort of 'undo' facility if you have accidentally trashed files or have a remorse. With the "all" option, all the files currently in the trash will be untrashed.

The "Change Creator" dialog has an additional button called "Other" : if a creator type is not in the popup menu, you can specify another one. This button brings up a new dialog with an edit field to enter the new creator type (four chars maximum). If you do not know the creator type corresponding to an application, use the "Same as" button and indicate the application or any document created with this application. The "Apply" button selects the new type and brings back the "Change Creator" dialog ; the "Add&Apply" button has the same effect but additionally records the new type in the popup menu to make it available for future use (the list is reset though each time Alpha is relaunched : to make an addition permanent use the Mac Menu Preferences. See section below about preferences).

The "Predef Exts" button is a facility to specify files with certain predefined extensions. It brings up a new dialog with a certain number of checkboxes : select the extensions you're interested in. The corresponding files filter regular expression will be built automatically in the main dialog window. If an extension is not mentioned in the "Predef Exts" dialog window, you have two possibilities :

Information dialog windows

The information windows display information about all kinds of items : files, folders, volumes, applications, processes or basic hardware. They almost all have a "Dismiss", a "Get Text". The File Infos dialog also has a "Set" button. With the "Dismiss" button, you simply quit the dialog. The "Get Text" button sends the collected information to a separate text window. The "Set" button allows you to set some properties : the corresponding fields are editable (an edit field for a variable or a checkbox for a flag). You validate your modifications with the "Set" button. Note that if your file is locked the modifications are not appliable : you must first unlock it. Be aware of what you are doing : changing low level properties is potentially dangerous. Don't play with the system files. In the case of a shared volume or folder, and if file sharing is on on the system, there is an additional "Sharing" button which gets and displays the complete sharing information about the item.

Menu Items Description

Here is the list of all the menu items of the Mac Menu with explanations. Certain items are obtained if you hold the Option Key down while opening the menu.

Main menu

Copy Files
Brings up a dialog in which you specify the files filter, the source and target folders and various options. Copy the selected files to the target creating the same hierarchy in the destination folder. The original files remain in the source folder.

Move Files
Brings up a dialog in which you specify the files filter, the source and target folders and various options. Move the selected files to the target creating the same hierarchy in the destination folder. The original files are removed from the source folder. Note that, as is the rule with MacOS, moving a file to another volume means in fact copying.

Rename Files
Brings up a dialog in which you specify the files filter, the replacement expression, the source folder and various renaming options : the "Add Options" button brings a new dialog to set casing, numbering and truncating options. Rename the selected files according to the new scheme.

Duplicate Files
Brings up a dialog in which you specify the files filter, the source folder and various options. Duplicate the selected files in their original folder.

Trash Files
Brings up a dialog in which you specify the files filter, the source folder and various options. Sends the selected files to the trash : the files are not deleted until you empty the trash.

When holding the option key down :

Untrash Files
Sends back the files which are in the trash to their original position. You can choose among two options : "last trashed" sends back only the files that where trashed the last time the trash command was used from the Mac Menu while "all" sends back all the files located in the trash. Don't expect a miracle : if the trash has been emptied, there is no resurrection.

Alias Files
Brings up a dialog in which you specify the files filter, the source folder and various options. You can also optionnally specify a target folder. There are two possibilities :

When holding the option key down :

Remove Aliases
Brings up a dialog in which you specify the source folder and the subfolders level. Remove all aliases found in these folders.

Lock Files
Brings up a dialog in which you specify the files filter, the source folder and various options. Lock the selected files in their original folder.

When holding the option key down :

Unlock Files
Brings up a dialog in which you specify the files filter, the source folder and various options. Unlock the selected files if they are locked.

List Files
Brings up a dialog in which you specify the files filter, the source folder and various options. Simply makes a list of the files selected according to the files filter and the various options and display it in a separate window. The "Sort by" pop-up menu allows you to choose one of five options (or no option) so that the list returned is sorted according to the selected criterion. You can sort by : "Modification date", "Creation date", "Size", "Kind", "Labels". Check the "Incl Crit" checkbox to include the value of the criterion for each item in the result.

Select Files
Brings up a dialog in which you specify the files filter, the source folder and various options. Select in the Finder (i-e hilite) the selected files. The Finder window corresponding to the source folder comes to the front showing the hilited (selected) files. This command works exclusively in the source folder (not in subfolders).

When holding the option key down :

Unselect Files
Brings up a dialog in which you specify the files filter, the source folder and various options. Unselect in the Finder (i-e remove hiliting from) the selected files : this unhilites only the files corresponding to the files filter and the various options. This means, as one might expect, that some files that were previously hilited might remain so while some others are unhilited.

Transtype Files
Brings up a dialog in which you specify the files filter, the source folder and the environment the files belong to in order to convert the line endings between the various plateform specific types (mac, unix and win). For instance if you choose to convert eols (end of lines) from unix to mac, only Unix type files will be converted to the Mac type. If you choose "all", conversion applies to all three kinds of files.

Change Creator
Brings up a dialog in which you specify the files filter, the source folder and various options : a popup list lets you choose the new creator you want to assign to the selected files. Use the Other button to find another creator.

Change Type
Brings up a dialog in which you specify the files filter, the source folder and various options : a popup list lets you choose the new type you want to assign to the selected files. Use the Other button to find another type.

Mac Shell
Opens a shell in which all the Mac Menu functions can be executed from a command line. See below the Mac Shell section for details on the syntax of this command line.

Empty Trash
Empty the trash.

Show Clipboard
Switches to the Finder and shows the Clipboard window.

Eject
Eject a removable volume (floppy, Zip, CD-ROM etc.). If there are several ejectable volumes, a list shows up from which you select the one you want to eject from its drive ; if there is only one ejectable volume, it is automatically ejected.

Restart
Launches the process of restarting the computer.

Shut Down
Launches the process of shuting down the computer.

Get Info submenu

File / Folder / Application
With these three items, a standard system window lets you designate the file, folder or application about which you want to get system information.

Volume / Process
With these two items, a list of all mounted volumes (and shared disks on remote computers) or a list of currently running processes lets you choose the one you want information about.

Hardware
Provides general hardware information about your computer (clock speed, CPU, etc.)

Mac Menu Bindings
Shows all the key bindings available with the Mac Menu in a separate window. See the "Key Bindings" section below.

Mac Menu Tutorial
Opens the tutorial file.

Mac Shell Syntax

The Mac shell provides a command line facility analogous to the Tcl shell ('cmd-y') or the Toolsever shell ('ctrl-cmd-y') already available in Alpha. You can open it with the "Mac Shell" menu item or with the 'opt-cmd-y' key combination. This section lists all the commands available in the Mac Shell.

The main commands are 'help', 'files' and 'infos'. There are also commands which allow you to navigate in the MacOS files system : 'pwd', 'cd', 'ls', 'ld'. Additionally you have a few utility commands : 'empty', 'eject', 'restart', 'shutdown' which behave like the corresponding menu items. Please see the tutorial (choose "Mac Menu Tutorial" in the "Get Info" submenu) for real life examples.

Certain options are not handled from the command line though : if you want to specify additional conditions (as explained above) you should rather use the dialog windows.

If a command is unknow to Mac Shell, it will try to evaluate it as a Tcl instruction. This means that you can use Mac shell as a Tcl shell.

Shell prompt

The shell prompt always indicates the name of the current folder. When opening the shell, its value defaults to the Alpha application's home directory.

'help' command

The 'help' command can be used alone or with one of the following subcommands :

help to have a list of all available commands
help optionsto have a list of all available options and flags
help moreto open a file with complete syntax
help bindingsto display key bindings
help tutorialto open the tutorial
help versionto get macMenu's version number

'files' command

The 'files' command is used with a subcommand to specify the type of action which is to be executed and flags to specify the conditions and options.

Options for the files command

Here is the signification of the various options. Some of them are required, the others have default values and can be omitted if not necessary.

-f "filter"filtering regular exprdefault '.*'
-s "folder"source folderdefault current folder (set with 'cd')
-l "level"nesting level (0, 1,... or all) default 0
-i "flag"case sensitive? default 0
-n "flag"negate? default 0
-t "folder"target folderno default
-t <kind>target eol in transtype default mac
-t "type"file's type no default
-c "type"file's creator no default
-o "flag"force overwrite? default : see prefs
-o <kind>original eol in transtype default unix
-r "replace"regsub expr for renaming default &
-all all files (equivalent to '-f .*')no value. Standalone option.
-k "flag"casing : u, l, w, f default : not set
-d "flag"numbering : 0/1 default : not set
-b <mcskl>sort byno default
-x "m[.n]"truncate default : not set

Note that the -c option is interpreted differently with the "files change" command than with the other "files" command : in the first case, it is the required option which tells which new creator should be assigned to the selected files. In the second case, it is an optional argument telling that only the files with the type declared by -c should be selected to perform the action.

Similarly the -t option is interpreted differently with the "files change" command than with the other "files" command : in the first case, it is the required option which tells which new type should be assigned to the selected files. Used with "files transtype", the -t flag designates the target kind of file (mac, unix or win). Otherwise, it is the argument to indicate the target folder in a move, copy or alias action.

The -b flag (b stands for 'by') is used only by "files list" and allows you to specifiy a sorting option. The option is specified by one of the letters m, c, s, k, l which correspond respectively to sorting by "Modification date", "Creation date", "Size", "Kind", "Labels".

It is essential that the filtering regular expression be enclosed in brackets if some characters are escaped. The brackets protect the escaped characters from being iterpreted by the Tcl interpreter before the regular expressions interpreter. For instance, to designate all files ending with a dot followed by one single number you want to use the following expression:

      .*\.\d
so you should write on the command line
     -f {.*\.\d}
If you do not enclose the regular expression in brackets, you must escape the characters twice i-e with a double backslash like this :
     -f .*\\.\\d
or
     -f ".*\\.\\d"
This remark concerns exclusively the regular expressions used on the command line : there is no need of brackets when you use the menu items and dialog windows.

If the -d flag is on (-d 1) the numbering will be done. There is no way to set the numbering options from the command line. The last used settings will be applied.

Subcommands of the 'files' command

Here is the list of the various subcommands you can append to the 'files' command together with the options they accept:

cmdsubcmdsoptions
filescopyRequired -t
Optional -f -s -l -i -n -all
filesmoveditto
filesrenameOptional -f -s -l -i -n -c -r -all
filestranstypeOptional -f -s -l -i -n -o -t -all
fileslistOptional -f -s -l -i -n -b -all
filesduplicateOptional -f -s -l -i -n -all
filestrashditto
fileslockditto
filesunlockditto
filesaliasditto
fileschangeRequired -c and/or -t
Optional -f -s -l -i -n -all
filesselectOptional -f -s -i -n -all
filesunselectditto
filesunaliasOptional -f -l -all
filesuntrashOptional -all

'infos' command

The 'infos' command is used with a subcommand to specify the item about which information is required. Its syntax is :

infos file "path"
infos folder "path"
infos volume "path"
infos appl "path"
infos process "processname"
infos hardware

Browsing commands

Here are the commands which help you setting easily the current folder :

pwd
(print working directory) Prints the current directory. The name of the directory is used in the shell's prompt.

cd "dir"
(change directory) The 'cd' command lets you change the current directory. In can be used in different manners:

cd
change to Alpha's home directory

cd .
change to directory of frontmost window (not including the shell). If there is no window open, change to Alpha's home directory

cd ..
change to parent directory. To go several levels up, type several .. separated by colons. E-g : cd ..:.. etc.

Alternatively

cd :
change to parent directory. To go several levels up, type several colons E-g : cd ::: etc.

cd "blah"
change to subfolder "blah" of current folder (if "blah" exists of course)

cd "abs_path"
change to directory corresponding to the absolute path "abs_path"

mkdir "dir"
(make directory) Create a new subfolder in the current folder. If no name is specified, it will be Untitled.

edit "file"
(edit a file) Give the name of the file : if it is in the current directory, the proc will complete the path. You can use the completion mechanism to enter the name of the file : type the first letters, then hit the Tab key. If the 'edit' command is used with no argument, you are prompted to select a file to edit.

ls
(list) Returns a list of all the files and folders contained in the current folder.

ld
(list directory) Returns a list of the subfolders contained in the current folder.

Misc commands

emptyto empty the trash
ejectto eject a mounted removable volume
restartto restart the computer
shutdownto shutdown the computer

Commands history

As with any Alpha shell, you can move through commands history with the 'up' and 'down' arrow keys while holding the 'control key' down. If you option-click in the title bar of the Mac shell, you also have a list of the last twenty command lines and you can select any of them which will be inserted in the shell.

Extending Mac Shell

You can create your own commands to use in Mac Shell. To create a new command called "mycmd", you must define a proc named macsh::mycmd and the value returned by this proc should be the text you want to be inserted in Mac Shell as a reply when the command is executed. If you want no reply, just return the empty string "".

The proc macsh::mycmd can take parameters and arguments depending on what syntax you want for your command (subcommands, additional arguments, options etc.). Please read different examples in the file macMenuShell.tcl.

All your commands can be stored in a file. This file should start with the following instruction :

 namespace eval macsh {}
The easiest solution is to locate this file in the MacMenu folder and to rebuild the Tcl indices to register your procs in Alpha.

Completion mechanism

There is a completion mechanism bound to the tabulation key (exactly like in most Unix shells).

Type the first letters of a command or of a file's or folder's name and hit the TAB key : the procedure will try to complete, looking either for a command name or for the relative or absolute path of a file or a folder. If there are several possible completions, a pick list is displayed. Note that :

Getting info

The "Get Info" submenu allows you to get (and set) information about various kinds of elements : file, folder, volume, application, running process and the computer itself. The results are displayed in a dialog window.

All these information windows have a button called "Get Text" to edit the results in a separate text window.

When appropriate, if a specific piece of information has a value which can be set or modified, it is edited in an editable field or with a checkbox so that you can change its value. Use the "Set" button to validate changes.

The search of information can be slow on... slow machines. Note that the information about hardware will be sought by the package only the first time and recorded since it is not likely to change during a session.

Here is a list of the properties you can find in the info windows (not all properties apply to all items of course) :

OwnerLogical sizeModification date
LockedVersion infoLogical page size
SharedCreation dateProcess partition
CommentLaunched fromLargest free block
CreatorPhysical sizeMinimum memory size
VersionRemote eventsOwner's privileges
CapacityUser RAM sizeProtected from move
ROM sizeStationery padSystem architecture
RAM sizeIs share pointLow memory area size
EjectableSystem versionAllocated memory size
Boot diskVirtual memoryEveryone's privilege
CPU family Bus clock speed Scripting terminology
Free bytes Hardware vendor Open Firmware present
Scriptable Software vendor Processor clock speed
Access pathGroup privilegesSuggested memory size

Key Bindings

There are a few easy to remember key bindings 'a la emacs'. Press 'ctrl-z', release, then hit one of the following letters :

ato make aliases
bto show this bindings info window
cto copy files
dto duplicate files
eto empty the trash
fto free (unlock) locked files
gto change files creator
hto open Mac shell
jto eject a disk
kto lock files
lto list files
mto move files
nto rename files
pto open the clipboard in the Finder
rto remove aliases
sto select files
tto send files to the trash
uto unselect files
xto exchange end of lines (transtype)
yto change files type
zto untrash files (z like undo)

You can also use 'opt-cmd-y' to open the Mac Shell (same as 'ctrl-z h'). Use the tabulation key to trigger the completion mechanism in Mac Shell (see above).

Preferences

The "Mac Menu Prefs..." item in the "Packages" submenu of the "Config" menu allows you to set a few general options :

Version History

Known problems

Please e-mail any problem or bug you encounter : berdesg@easynet.fr

Goto the Alpha utilities page :

http://webperso.easyconnect.fr/berdesg/alpha.html

License and Disclaimer

Copyright Bernard Desgraupes, 2001 All rights reserved. This software is free software 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:

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 the regents or contributors 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.