Advanced features - the-carlisle-group/Acre-Desktop GitHub Wiki
This page is now completely redundant.
Navigate this page:
Overview
Acre desktop is designed to offer as few commands as possible. Those commands should suffice for the vast majority of your work.
However, there are advanced features available you might well need every now and then. All these features are available via the ⎕se.acre.run function which becomes available once any acre user command is executed, forcing acre to be loaded into ⎕SE.
BTW, the easiest way to achieve that is to ask acre for a list of tracked projects with
]acre.Projects
although most of the facilities offered require the prior opening of at least one project which will ensure acre is already present.
File names
There are three methods available associated with filenames: sourcefile, changefile and deletefile. All return a text string containing a fully qualified filename which file might or might not exist.
sourcefile refers to files in the folder APLSource/, which keeps all APL source code files, hence the name.
changefile and deletefile refer to the folder .acre/changes which only exists if the acre config file contains a statement KeepHistory←'On' (because the default is "Off"). See Local Change History for details.
For all three the right argument should be a simple string containing the fully or relatively qualified name of an item - existing or not - in a namespace that is part of a tracked acre project.
If the argument is enclosed or nested only the first name is processed.
"Source" Filenames
The extension of the file depends on the type of object. See Name Class for details.
Examples:
⍝ existing function:
'sourcefile'⎕se.acre.run '#.myAcreProject.myDfns'
C:/.../myAcreProject/APLSource/myDfns-4.function
⍝ missing item:
'sourcefile'⎕se.acre.run '#.myAcreProject.DoesNotExist'
C:/.../myAcreProject/DoesNotExist-91.*
⍝ not a tracked project:
⍴'sourcefile'⎕se.acre.run '#.DoesNotEixst'
0
"Change" Filenames
The extension of the file is .change. Before that is the name class of the item separated by a dot from the rest of the filename. The name class depends on the type of the object.
Examples:
⍝ existing function:
'changefile'⎕se.acre.run '#.myAcreProject.myDfns'
C:/.../myAcreProject/APLSource/myDfns-4.aplf.change
⍝ missing item:
'sourcefile'⎕se.acre.run '#.myAcreProject.DoesNotExist'
C:/.../myAcreProject/DoesNotExist-91.*.change
⍝ not a tracked project:
⍴'changefile'⎕se.acre.run '#.DoesNotEixst'
0
"Delete" Filenames
The extension of the file is .delete. Before that is the name class of the item prior to its deletion separated by a dot from the rest of the filename.
Examples:
⍝ existing function:
'deletefile'⎕se.acre.run '#.myAcreProject.myDfns'
C:/.../myAcreProject/.acre/changes/myDfns-4.aplf.delete
⍝ missing item:
'deletefile'⎕se.acre.run '#.myAcreProject.DoesNotExist'
C:/.../myAcreProject/.acre/changes/DoesNotExist-91.*.delete
⍝ not a tracked project:
⍴'deletefile'⎕se.acre.run '#.DoesNotEixst'
0
The above examples do not reflect actual delete file names insofar as the existence of a delete file implies the item's non-existence in the workspace. run will then produce a file name with an asterisk * in place of the previous name class as that is now unknown. Contrariwise run's producing a file name with a proper name class indicates that the item is not in fact deleted.
Name class
The argument is a simple string or nested list of item names irrespective of whether they are in a tracked project. A simple string is treated as a one item list.
The result is a conforming nested list of the file-extensions that would be added to source, change or delete files representing the name class of the names in the argument.
A comprehensive list of item types, file extensions and corresponding numeric name classes is available by:
'nameclass'⎕se.acre.run'?'
Character Matrix .charmat 2.1
Character String .charstring 2.1
Class .aplc 9.4
Class Instance .* 9.2
Container Namespace 9.1
Derived Function .* 3.3
Direct Function .aplf 3.2
Direct Operator .aplo 4.2
General Array .array 2.1
Gui Object .* 9.2
Interface .apli 9.5
List Of Strings .charlist 2.1
Missing Item .* 0
Mixed Array .array 2.1
Numeric Array .array 2.1
Scripted Namespace .apln 9.1
Traditional Function .aplf 3.1
Traditional Operator .aplo 4.1
Item Name
The argument is a simple string or a list of source file names of files which might or might not exist in or below the APLSource folder of a tracked project. A simple string is treated as a one item list.
The result is a conforming list of fully qualified item names as they exist or would exist in the project space having resolved any case codes.
Examples:
⍝ First example:
sf←'sourcefile'⎕se.acre.run '#.myAcreProject.myDfns'
'itemname'⎕se.acre.run sf
'#.myAcreProject.myDfns'
⍝ Second example:
≡⎕←'itemname'⎕SE.acre.run 'sourcefile'⎕SE.acre.run'#.myAcreProject.DoesNotExist'
#.myAcreProject.DoesNotExist
2
⍝ Third example:
⍴'sourcefile'⎕se.acre.run 10⍴⊂'#.myAcreProject.myDfns'
10
⍝ Fourth example:
⍬≡⍴'itemname'⎕SE.acre.run 'sourcefile'⎕SE.acre.run'#.DoesNotExist'
1
Note that this does not work on either a change file or a delete file.
Version number
To get acre's current version number:
'version'⎕SE.acre.run ''
Acre 4.2.0 2018-04-04
Case Code
The argument is a qualified or unqualified name representing an item which might or might not exist whether in a tracked project or not. In case the argument is either enclosed or nested only the first name is processed.
If the name contains even a single hyphen each dot separated node is processed to restore its casing according to the case code which is itself removed. Nodes containing no hyphen are preserved intact.
If no hyphen is present anywhere in the name each dot separated node has a case code added to represent the present casing of that node.
Examples:
⍝ lowercase with case codes → capitalised accordingly
'casecode' ⎕se.acre.run 'zero-0.one-1.two-2.three-3.four-4.five-5.ninetynine-99'
'zero.One.tWo.THree.foUr.FiVe.NinETynIne'
⍝ mixed case without case codes → adds corresponding case codes
'casecode' ⎕se.acre.run 'zero.One.tWo.THree.foUr.FiVe.NinETynIne'
'zero-0.One-1.tWo-2.THree-3.foUr-4.FiVe-5.NinETynIne-99'
For further details on case codes see Item Names and File Names.