Skip to content

Command Reference

Jump to bottom
PhilLast edited this page Aug 19, 2020 · 107 revisions

All of the following commands are mirrored in a set of functions (API) in ⎕SE.acre that require the same data and return identical results. The format of the arguments and options necessarily differs between the user-commands and the API-functions as those of the former always comprise a character string while those of the latter are expected to form a list of the separate "arguments" (items) and optional name-value pairs. For illustration the following two statements would be equivalent.

      ]acre.Command arg1 arg2 -flag -opt1=val1
      ⎕SE.acre.Command 'arg1' 'arg2' ('flag' 1) ('opt1' 'val1')

If no arguments are provided but only a single option or flag, as with the -all flag where arguments are redundant, when the function is called the option must be enclosed so as to be provided to the framework as a single entity:

      ]acre.Refresh -all
      ⎕SE.acre.Refresh ⊂'all' 1

For commands and functions that expect names as argument, fully qualified (starting with '#.') are best supplied but if the command or function is called from elsewhere than the root (#) then acre will prefix that location to any name starting otherwise than '#.'.

Commands and functions both issue messages to a session log - and a log file if extant. (see Log). Commands only may cause some more urgent messages to be displayed also in the Dyalog session.

AfterSave

]Acre.AfterSave [string]

Set or query aftersave session parameter; the name of the function which, if 3=#.⎕NC, will run after acre has saved an edited item to file.

The setting is global for all projects opened subsequently that do not specify it for themselves using the optional homonymous AfterSave configuration parameter. It does not affect projects that were already open.

  • If string is missing or empty return the current setting.
  • If string is a name (0≤⎕nc) then replace and return the previous value.
  • Otherwise set the value to null and return the previous value.

The named function must conform as follows:

  • it must be dyadic or ambivalent - it must accept a left argument - and must return a result.
  • its left argument will be a clone of the internal namespace representing the config file associated with the tracked project to which the item belongs; this is provided in case the exit function requires reserved or non-reserved values from the config file.
  • its right argument will be the two-item list (edited item path.name)(source file path/name) which will already have been saved.
  • its result should be a charString, charMat or charList which will be used, if non-empty, as one or more log messages. Prefixing one or more of them with a "⎕" character will force them all also to the session.

BeforeFix

]Acre.BeforeFix [string]

Set or query beforefix session parameter; the name of the function which, if 3=#.⎕NC, will run before Dyalog has fixed an edited item which may not happen in all cases.

The setting is global for all projects opened subsequently that do not specify it for themselves using the optional homonymous BeforeFix configuration parameter. It does not affect projects that were already open.

  • If string is missing or empty return the current setting.
  • If string is a name (0≤⎕nc) then replace and return the previous value.
  • Otherwise set the value to null and return the previous value.

The named function must conform as follows:

  • it must be dyadic or ambivalent - it must accept a left argument - and must return a result.
  • its left argument will be a clone of the internal namespace representing the config file associated with the tracked project to which the item belongs; this is provided in case the exit function requires reserved or non-reserved values from the config file.
  • its right argument will be the three-item list (edited item path.name)(source file path/name)(edited_value (a charList)) which will not already have been fixed.
  • its result should be a charString, charMat or charList which will be used, if non-empty, as one or more log messages. Prefixing one or more of them with a "⎕" character will force them all also to the session.

CreateProject

]Acre.CreateProject projectfolder projectspace [-casecode] [-keephistory] [-variables]

Create a new project projectfolder with source code in space-tree projectspace.

The three modifiers -casecode, -keephistory and -variables all default to 'Off'.

  • If -casecode is 'On', item file names will be written with case codes.
  • If -keephistory is 'On', changes to items will be written additionally to changefiles which are then subject to additionally activated commands ]Changes, ]PurgeHistory, ]Redo, ]Restore and ]Undo.
  • If -variables is 'On' or 'Binary', any variables existing in the project-space will be included in the source and not otherwise.
  • If -variables is 'On', they will be stored encoded in APLAN with the extension '.apla'. If -variables is 'Binary' they will be stored unencoded each in its own component file with the extension '.binary'.
  • Two of the modifiers - casecode and -keephistory - with their values will be preserved as the homonymous configuration parameters CaseCode and KeepHistory.

The project folder must not exist. If you want to override an existing project folder, you must either first delete it in the operating system or, if it contains required resources, create the project in a new folder and move the contents to the old, deleting the new.

The minimum requirement for a folder to be considered a project folder is the existence of a sub folder named APLSource or a text file named acre.config. It is thus very easy to create a project by hand in the operating system.

Unless they already contain an item called quadVars a scripted namespace will be created with that name in the project space and all subspaces that differ from their parents in the values of the system variables ⎕IO ⎕ML and ⎕WX. The script will reset those vars to their original values whenever the project is opened. The script may be amended, cloned or deleted. Cloning it into sub-spaces will easily allow the controlling of the environment further down the space-tree.

  • NB. Acre automatically saves defined operations (fns & ops) and scripts (spaces, classes & interfaces) when created or changed in the editor but variables created after the project exists will need to be saved with SetChanged after which changes to them will be saved from the editor.

OpenProject

]Acre.OpenProject projectfolder [projectspace] [-track] [-dependencies]

Open projectfolder into the projectspace, if provided, else into the projectspace specified in acre.config file, if provided, else into a root level namespace named after the last node name of the project folder.

The two modifiers -track and -dependencies both default to 'On'.

  • If -track is 'On', the project will be recognised by Acre-Desktop commands by its project space and editor changes to items within the project will be saved. If 'Off', the project will be forgotten as soon as opened.
  • If -dependencies is 'On', projects specified in the configuration parameter Dependencies← will be opened before the project that specifies them. If 'Off', the Dependencies← parameter will be ignored.

If the target projectspace already exists, it is completely overwritten (replaced).

If the target projectspace is the root (#), the workspace is effectively cleared before instantiating the project code. Each path segment of the projectspace will be created if necessary.

A project may not be tracked underneath another tracked project.

The Startup configuration parameter of the project being opened but not those of its dependencies is executed in the project space.

A tracked project is closed by expunging its projectspace or by opening another project into the same target space.

Projects

]Acre.Projects [-when]

List tracked projects. Acre displays the project namespace, the project folder, and possibly other useful information for each project. In order of their opening. The -when flag adds the most recent OpenProject or Refresh date-time for each project.

Stats

]Stats projectspace [-all]

Display detailed project statistics, including number of functions, variables, etc.

  • flag -all for the command, ('all' 1) for the function, returns stats for all open projects

Changes

]Changes (projectspace|item) [-when]

Display recent changes to a project or to a specific item. If a project space is provided, a list of names of recently changed items is displayed. If a specific item is provided, a list of the changed source code is displayed.

In the former case the use of the -when modifier will add the modified date to each item name. If the modifier is given a date-time value then only those items changed from that time will appear.

In the latter case if the -when modifier is given a date-time then only source code changed from that time will appear. The naked switch causes version numbers and dates only to be returned.

  • NB. ]acre.Changes is disabled if KeepHistory←'Off'

PurgeHistory

]PurgeHistory (projectspace|item)

Purge change history for a project or an item. Only existing change or delete files are removed - for the entire project or the named item. Change files will continue to be created or incremented. To stop the creation of history set the configuration parameter: Keephistory←'Off'

  • NB. ]acre.PurgeHistory is disabled if KeepHistory←'Off'

Undo

]Acre.Undo item

Undo the most recent change to an item in a tracked project.

  • NB. ]acre.Undo is disabled if KeepHistory←'Off'

Redo

]Acre.Redo item

Redo the most recently undone change to an item in a tracked project.

  • NB. ]acre.Redo is disabled if KeepHistory←'Off'

Erase

]Acre.Erase (namespace|item[s]) [-recursive]

Erase one or more items from a tracked project. Items should be named explicitly or all members of a namespace and its sub-tree can be erased if the -recursive flag is used.

  • If KeepHistory←'On' acre will create a .delete-file or append to a .change-file renaming it to .delete that will contain the latest version of the item. This is then a candidate for the restore command or function.
  • Erasing items with the system command )ERASE or function ⎕EX will have no lasting effect as acre is unaware of the loss. Such items will be returned the next time the project is opened or refreshed.

Restore

]Acre.Restore item

Restore a deleted item from the local change history of a tracked project.

  • NB. ]acre.Restore is disabled if KeepHistory←'Off'

Refresh

]Acre.Refresh projectspace [-all]

Bring into the project space of a tracked project any changes made to its APLSource/ folder since it was previously opened or refreshed during this session. If KeepHistory is On then add or append to change files. Returns the names of changed items.

As most projects are probably well within the limits of a machine's cache, re-opening a project and thus bringing in changes and losing deletions* is usually very quick. The reason Refresh exists anyway is to maintain the integrity of the session, including the SI stack and any temporary items not intended to be stored, while bringing in essential external changes. To reopen the project would either destroy or severely disrupt such a session.

  • NB. Because acre has no way to distinguish between items erased from source externally during the session and items created temporarily within the session Refresh does not attempt to erase. To attempt to do so would militate against the reason for the command's existence.

  • flag -all for the command, ('all' 1) for the function, refreshes all open projects.

SetChanged

]acre.SetChanged aplname1 [aplname2,....] -recursive

Acre automatically saves members of tracked projects when they are changed in the editor. But items changed in any other way or copied into the project from elsewhere are unknown to acre. Members of tracked projects named in the argument of SetChanged are treated similarly being saved to the source folder and if KeepHistory is On added also to change files.

To save all members of a namespace, name the space as the only argument and add the -recursive flag. All appropriate members of the space and its sub-tree will be saved. That includes variables because it is assumed that with syntax you really want to save all stuff in the namespace and, in the event the -recursive flag is set, all sub namespaces. If you have variables but don't want them saved and tracked then delete them from the workspace before issuing the SetChanged command.

  • SetChanged is one of the two ways (the other being EditArray) to save a newly created variable. Once saved further edit changes will continue to be saved.

ToAPLAN

]acre.ToAPLAN name|"expression"

name or expression should evaluate to an APL array. The result is a CR separated character string in APL Array Notation "APLAN" that encodes that APL array.

  • For the command the expresson should be quoted, with "double-quotes" if it contains 'singles' and vice versa.
  • For the function both the name and the expression - whichever is supplied - must be quoted.

FromAPLAN

]acre.FromAPLAN name|"expression"

name or expression should evaluate to a character string, matrix or list of strings in APL Array Notation. The result is the APL array encoded by the source.

  • For the command the expresson should be quoted, with "double-quotes" if it contains 'singles' and vice versa.
  • For the function both the name and the expression - whichever is supplied - must be quoted.

EditArray

]acre.EditArray name

name should be the (qualified) name of any array. The value of the array is presented in a modal instance of the Dyalog Editor identically to the way it would be stored in a source file. A character string, matrix or list of strings is presented as-is. Any other array is encoded in APL Array Notation and presented as a list of strings.

The user may edit the value.

If no change is made or the edit session is aborted an empty string is returned.

If changed; a regular character array is saved and its fully qualified name returned; an APLAN encoded array is evaluated and if different from the original, the array is saved and its fully qualified name returned.

Escape sequences may be present in or added to the source file or edit array that represent control characters in the evaluated array as follows:

┌────────┬────────────────┐
│ escape │ control        │
├────────┼────────────────┤
│   \\   │ backslash      │
│   \0   │ nul            │
│   \b   │ backspace      │
│   \t   │ horizontal tab │
│   \n   │ linefeed       │
│   \f   │ formfeed       │
│   \r   │ return         │
└────────┴────────────────┘
  • EditArray is one of the two ways (the other being SetChanged) to save a newly created variable. Once saved further edit changes will continue to be saved.
  • An APLAN encoded array may be changed in such a way that it qualifies subsequently as a character string, matrix or list. In this case it will be saved as that different type, its file being renamed accordingly.
  • If invalid APLAN is entered a DOMAIN, SYNTAX or VALUE ERROR may be generated.

Log

]acre.Log hide|show|file|clear|all|find| no. of rows

All acre messages and blocks of messages are now added to the beginning of a session-log displayed in a separate window that appears during the first command of a session; and also appended to a log-file, if it exists, when it will be located in the acre installation folder whose default is the acre/ subfolder of the user's local folder that is the result of #.GetEnvironment'localappdata'

  • hide - removes the window 'though messages continue to be added to the log.
  • show - reinstates the window with the entire session-log in place.
  • file - returns the log-file name and creates it if missing.
  • clear - removes all messages from the session-log whether currently showing or not.
  • all - returns the entire contents of the session-log.
  • find "string" - returns all session-log entries that contain "string".
  • no. of rows - returns that number of messages from the beginning (top) of the session-log.

Once created the log-file continues to grow. Acre's only interaction is to append to it so long as it exists. The user can delete, edit, move or rename it.

The )CLEAR system command currently removes the window but without destroying the log exactly as the ]Log hide command.

The session-log keeps only the most recent 1000 rows when new rows are added.

CloseProject

]acre.CloseProject projectspace [-all]

The project in projectspace is closed in the sense that acre stops tracking it. The project space is untouched and all of the code remains in place. The result is the number of projects still open (tracked).

  • NB. although they may be the same, the argument to CloseProject is the project space path while that of OpenProject is the project folder path.
  • flag -all for the command, ('all' 1) for the function, closes all open projects.

CaseCode

]acre.CaseCode item(s)

Toggle supplied names between case-coded and not

      ]casecode #.abcdefghijklmnopqrstuvwxyz-abc
 #.abCDEFgHiJkLmnopqrstuvwxyz 
      ]casecode #.abCDEFgHiJkLmnopqrstuvwxyz 
 #.abCDEFgHiJkLmnopqrstuvwxyz-abc 
      ]casecode #.zero-0.one-1.two-2.three-3.four-4.five-5.six-6.seven-7.eight-8.nine-9
 #.zero.One.tWo.THree.foUr.FiVe.sIX.SEVen.eigHt.NinE 
      ]casecode #.zero.One.tWo.THree.foUr.FiVe.sIX.SEVen.eigHt.NinE 
 #.zero-0.One-1.tWo-2.THree-3.foUr-4.FiVe-5.sIX-6.SEVen-7.eigHt-8.NinE-9

The command/function is a self inverse:

  • if any supplied name contains a hyphen "-" then capitalise all names according to case-codes present
  • otherwise add case-codes to all supplied names.

Sourcefile

]acre.Sourcefile item(s)

Return the names of the sourcefiles that would contain the current definition of each supplied item name belonging in a tracked project. Neither the item nor the file has to exist.

      ]acre.Sourcefile #.project.SubSpace.ItemName
 C:/library/project/APLSource/SubSpace-9/ItemName-11.*
  • If the item existed its file extension would reflect its APL type.

Changefile

]acre.Changefile item(s)

Return the names of the changefiles that would contain the history of each supplied item name were it to be changed in a tracked project. Neither the item nor the file has to exist.

      ]acre.Changefile #.project.SubSpace.ItemName
 C:/library/project/.acre/changes/SubSpace-9.ItemName-11.*.change
  • If the item existed the asterisk would be replaced by the file extension that would apply to its sourcefile.
  • NB. ]acre.Changefile is disabled if KeepHistory←'Off'

Deletefile

]acre.Deletefile item(s)

Return the names of the deletefiles that would contain the history of each supplied item name were it to be ]ERASEd from a tracked project. Neither the item nor the file has to exist.

      ]acre.Deletefile #.project.SubSpace.ItemName
 C:/library/project/.acre/changes/SubSpace-9.ItemName-11.*.delete
  • If the item existed the asterisk would be replaced by the file extension that would apply to its sourcefile.
  • NB. ]acre.Deletefile is disabled if KeepHistory←'Off'

Itemname

]acre.Itemname sourcefile(s)

Return the names of the items whose current definition would be held in each supplied sourcefile name. Neither the item nor the file has to exist.

      ]itemname Space-1/SubSpace-9/ItemName-11.* 
 Space.SubSpace.ItemName 
      ]itemname C:/library/project/APLSource/Space-1/SubSpace-9/ItemName-11.* 
 #.projectSpace.Space.SubSpace.ItemName

In the first example above acre does not recognise the putative file as positively belonging to any tracked project so it converts only that part it can see.

In the second the project is open so acre can prefix the project space to the path below APLSource.

Nameclass

]acre.Nameclass item(s)

Return the nameclass of the item(s) whose names are supplied. The items do not have to be in a tracked project. Actually returned is the file extension that would be applied to the sourcefile associated with the item:

.apla, .aplf, .aplo, .apln, .aplc, .apli, .charlist, .charmat, .charstring or .*

but see table of file types.

Version

]acre.Version

Return the version of acre currently running in this Dyalog session as a charlist with items:

'Acre' (semantic-version-number (major.minor.patch+build) ) (build-date) (build-time)

      ]acre.Version                                                        
 Acre  5.2.0+239  2019-08-14  11.15

Removeacre

]acre.Removeacre

Close all tracked projects and remove the ⎕SE.acre namespace resetting ⎕SE as found.

      ]ACRE.Removeacre
Now safe to save session without acre

date-time

On output date-times represent dates as YYYY-MM-DD hh:mm:ss [⍟] in local time. On input the format is quite relaxed where any of the separators -/ :. or none can be used in any position. The digits are most significant from the left so any trailing values can be elided.

Examples:

'2019-08-20 09:55:07' ⍝ full date-time
'2019/08/20.09.55'    ⍝ start of minute
'2019-08-20.09'       ⍝ start of hour
'2019082009'          ⍝ as above, no separator required even between day and hour
'20190820'            ⍝ start of day
'201908'              ⍝ start of month
'2019'                ⍝ start of year
'2019-08-20T09:55:07' ⍝ is NOT supported

If it is required to program the date-time {1↓0⍕100⊥6⍴⍵} gives 20190820095507 for the above and is the simplest yet found.

  • It is important to note that date-times have one second precision. Particularly with respect to the when modifier two events occurring less than one second apart may be recorded as simultaneous.
Clone this wiki locally