Item Names and File Names

Every item in a project has a file name associated with it. APL is case sensitive. Some operating systems, like Windows and Mac OS, are not. This presents a problem.

Acre Desktop solves this by inserting a case code between the file name and the extension. Consider the six functions getdata, GetData, getData, GetData, GetDATA, and GETDATA. The correspondings files are named as:

getdata-0.aplf
Getdata-1.aplf
getData-8.aplf
GetData-9.aplf
GetDATA-79.aplf
GETDATA-7f.aplf

The case code serves two separate but related purposes; it guarantees a unique file name, and it encodes the casing of the item name. If the file casing should ever be lost due to the operating system or some ill-behaved third party software, Acre Desktop will know about it and can restore the casing.

There is no need for the programmer to ever compute a case code. When creating a file manually in the operating system, the case code may simply be omitted if there is no file name conflict. Acre will add the appropriate case code when it opens the project.

Resolving Inconsistent Names, Case Codes and Types.

The external file name, the case code, and the internal item name and type are normally consistent. But because files may be directly edited or created in the operating system, and because third party software may not respect case preservation, it is possible that conflicts may arise. Acre Desktop handles these as follows:

• Acre Desktop first resolves the external name by applying the case codes to the respective folder and file names irrespective of the setting of the CaseCode parameter (see below). Where there is no case code the casing of the filename is assumed to be correct.

• The name thus formed is the target name for the item represented in the file. If multiple files exist whose names resolve to the same target such as can happen if one has a case code and another doesn't or they have identical names but different types a warning message is issued.

• Regardless of any inconsistency, the content of each file undergoes an attempt to fix the item in the workspace according to the internal name if possible and the target name for arrays which have no internal name. The process used in the attempt depends on the stated type: ⎕FX for functions and operators; ⎕FIX for scripts: namespaces, classes and interfaces; direct assignment for text arrays: strings, lists and matrices; and decoding followed by direct assignment for general arrays.

• If the item will not fix a message is issued to that effect. This might be because the definition is invalid; the external type is inconsistent with the content; or multiple files exist for the same item. In the latter case one only of the items if any will exist in the opened project. It will be the user's responsibility to resolve the issue.

• The actual name and type fixed is then used to generate a correct name for the complete file path including case codes for each node if CaseCode is 'On' and not otherwise. Any discrepancy will then cause a message to be issued informing the user that "target-type target-name fixed as actual-type actual-name" and an attempt will be made to rename the file and possibly containing folders to reflect the reality.

• If the file cannot be renamed a message is issued to that effect. This might be because the CaseCode parameter is 'Off', the OS is case agnostic and two items have been fixed with the same type and names that differ only in their case. Or files exist with different types but containing definitions whose internal name is the same.

Computing the Case Code

The case code is computed by taking the base 16 representation of the base 2 number indicated by flagging uppercase letters in reverse order:

      f←{
            b←{(~∧\⍵=0)/⍵}⌽⍵≠819⌶⍵
            n←1⌈⌈(≢b)÷4
            r←(n,4)⍴(-n×4)↑b
            '0123456789abcdef'[2⊥⍉r]
         }  


      f¨'getdata' 'Getdata' 'getData' 'GetData' 'GetDATA' 'GETDATA' 
0  1  8  9  79  7f

This technique has several useful properties. An all-lowercase name has a case code of "0". A name with one and only one uppercase letter in the first position has a case code of "1". Names in CamelCase tend to be relatively low numbers. Finally, there is no limit on the length of the name.

The CaseCode Configuration Parameter

The use of case codes in file names is controlled by the CaseCode configuration parameter in the project's configuration file.

If CaseCode is 'On' case codes are inserted and enforced in file names. If CaseCode is 'Off' (the default), case codes are not added and are removed if present. The CaseCode parameter may be explicitly set when creating a project by use of the -casecode= modifier:

      ]CreateProject ProjectFolder ProjectSpace -CaseCode=on|off

If a potential project has no case name conflicts, and none are expected to arise, it may be appropriate to set the CaseCode to 'Off'. When the CaseCode is 'Off', Acre Desktop dispenses with the case code in file and folder names.

It is left up to the operating system to determine if otherwise identical but differently cased names are allowed. Furthermore, no effort is made to preserve case for namespaces (folder names), or for items that do not have internal names like arrays. The case code schema is designed to gracefully disappear for projects where it is not needed, or for use on operating systems that are case sensitive.

In general, the CaseCode parameter is set once when the project is created and not changed. However, nothing prevents it from being changed, and AcreDesktop does nothing special; it simply applies the rules above.

Thus, if an existing project's CaseCode property is changed from 'off' to 'on', then upon opening, Acre will rename every file and folder in the project, inserting the case code. Conversely if CaseCode is changed from 'on' to 'off', then upon opening, Acre Desktop will reverse the process for every file and folder that does not cause a conflict while warnings are issued for any which cannot thus be renamed.

The appropriate way to change the CaseCode property of a project is to open the project with -track=off and then create a new project.