The Project Configuration File - the-carlisle-group/Acre-Desktop GitHub Wiki

A project has a configuration file in it's root folder. The file is named acre.config (though the old, now deprecated name acreconfig.txt is still supported for the time being), and it is a simple text file. It is part of the project and should be stored in any source code management system. The file is optional, as is every parameter in it. Acre creates this file for you when you use the ]CreateProject command. If you are creating a project from scratch in the operating system, you may create it yourself.

The file format may be a JSON object or an APLAN or scripted namespace. For example this:

{
  "CaseCode": "On",
  "Dependencies": [
    "Rumba",
    "Utilities"
  ],
  "KeepHistory": "On",
  "MyCustomField": "possibly required by ancillary software",
  "ProjectSpace": "#.CarlisleRumba",
  "StartUp": "Initialize",
  "Variables": "Off"
}

is equivalent to this:

[
   CaseCode←'On'
   Dependencies←('Rumba')('Utilities')
   KeepHistory←'On'
   MyCustomField←'possibly required by ancillary software'
   ProjectSpace←'#.CarlisleRumba'
   StartUp←'Initialize'
   Variables←'Off'
]

and this:

:NameSpace
   CaseCode←'On'
   Dependencies←('Rumba')('Utilities')
   KeepHistory←'On'
   MyCustomField←'possibly required by ancillary software'
   ProjectSpace←'#.CarlisleRumba'
   StartUp←'Initialize'
   Variables←'Off'
:EndNamespace

Notes:

  • Any validly named values can be added to the file but a limited few are expected and reserved by acre.
  • The default is now JSON format since acre 6.0.0. Formerly it was APLAN.
  • JSON was introduced only in Dyalog 14.1, so if you need to use acre with older versions than 14.1 then you must avoid JSON.
  • From Dyalog 14.1 to 16.0 JSON was implemented as a pair of I-Beams. Dyalog 16.0 introduced ⎕JSON and 17.0 withdrew the I-Beams. Acre's emulation machanism handles this correctly.

Reserved Configuration Parameters

ProjectSpace

ProjectSpace is the fully qualified path of the namespace for the project. This defaults to a root level namespace named after the last node name of the project folder. This parameter is overridden if a second argument is supplied by the ]OpenProject command.

Dependencies

Dependencies is a list of zero or more additional projects to open. Either all items of the list are simple strings or all are namespaces.

  • Each string will contain the name of the dependency's project-folder and optionally the target project-space after a blank.
  • Each namespace will contain, among other things, a string called "name" being the name of the dependency's project-folder and optionally one called "space" being the target project-space.
  • The -track and -dependencies modifiers are neither required nor permitted in the Dependencies config parameter as dependencies automatically inherit the same values as the project that requires them.

Startup

StartUp is an expression to be executed in the project namespace of a tracked project, after all included projects are opened. Function calls should be fully qualified or relative to the project space.

CaseCode

CaseCode is a boolean flag (values "On" or "Off") indicating whether or not Acre Desktop should use case-codes when creating file names. The default value is "Off" since version 4.9; before that the default was "on". If the -casecode modifier is specified in ]CreateProject then its value is preserved as the value of this parameter.

See Item Names and File Names for details.

KeepHistory

KeepHistory is a boolean flag (values "On" or "Off") indicating whether or not Acre Desktop should store the history of workspace items. The default value is "Off" since version 4.9; before that the default was "on". When switched "off", the commands ]Changes, ]Restore, ]Undo, ]Redo and ]PurgeHistory are disabled. If the -keephistory modifier is specified in ]CreateProject then its value is preserved as the value of this parameter.

See Local Change History for further details.

Variables

Variables is a boolean flag (values "On" or "Off") indicating whether or not Acre Desktop should store variables newly created in the editor by default. The default value is "Off". If the -variables modifier is specified in ]CreateProject then its value is preserved as the value of this parameter.

In either case the ]SetChanged command will be honoured as will changes to a variable already having an associated source file.

AfterSave

AfterSave is an optional parameter which can be set for a single project in its configuration file but can be set globally by command ]AfterSave for all projects opened subsequently that do not specify it for themselves. If set, its value may be the name of a globally accessible function to be called by acre after a member of the project is edited. But the setting of any value in the configuration file, empty or not, prevents its being overridden by the global setting created by the command.