CONTRIBUTING.md polished

APLSource/APLTreeUtils2.aplc

@@ -3,25 +3,31 @@
 ⍝ While `APLTreeUtils` was a namespace scipt designed to be included into pretty much every member of the
 ⍝ APLTree library, `APLTreeUtils2` is a class with shared methods. You are supposed to call those methods.
 ⍝ This has some major advantageous over the old approach:
-⍝ * It's possible to add new functions to `APLTreeUtils`. With the old approach there was always the possibility
+⍝ * It's possible to add new functions to `APLTreeUtils2`. With the old approach there was always the possibility
 ⍝   of a name clash, so adding new function was practically impossible.
 ⍝ * The sequence of fixing does not matter (though with lazy fixing that should not be an issue anymore anyway,
 ⍝    but at the time of writing it still is).
 ⍝ * Over the years we have seen rare `⎕IO` and `⎕ML` issues with `:Include`. We just avoid the possibility now.\\
 ⍝ For a list with the precise differences between `APLTreeUtils` and `APLTreeUtils2` see the project ReadMe on
-⍝ GitHub. Note that there are many. Most importantly, `APLTreeUtils2` requires Dyalog 18.0.
+⍝ GitHub. Note that there are many. Most importantly, `APLTreeUtils2` requires at least Dyalog 18.0.
 ⍝ Kai Jaeger\\
 ⍝ Homepage: <https://github.com/aplteam/APLTreeUtils2/>
 
     ⎕ML←⎕IO←1
 
     ∇ r←Version
       :Access Public Shared
-      r←'APLTreeUtils2' '1.2.1+62' '2023-10-05'
+      r←'APLTreeUtils2' '1.3.0+62' '2023-11-05'
     ∇
 
     ∇ History
-    ⍝ * 1.2.0 from 2023-10-05
+    ⍝ * 1.3.0 from 2023-11-05
+    ⍝   * `ToNum` now accepts a left argument which is returned in case the right argument is an empty vector.
+    ⍝   * New methods: `BitsToInt` and `IntToBits`
+    ⍝ * 1.2.2 from 2023-10-09
+    ⍝   * Minor fix in CreateUUID
+    ⍝   * License corrected
+    ⍝ * 1.2.1 from 2023-10-05
     ⍝   * Bug fix in `Create_UUID`
     ⍝ * 1.2.0 from 2023-05-08
     ⍝   * Bug fix: version number corrected
@@ -67,10 +73,16 @@
       r←0 2∊⍨10|⎕DR y
     ∇
 
-    ∇ r←ToNum y
-    ⍝ Transforms `y` into number(s)
+    ∇ r←{default}ToNum y
+    ⍝ Transforms `y` into number(s).\\
+    ⍝ In case `y` is empty `default` is returned which defaults to ⍬ (empty numeric vector).
       :Access Public Shared
-      r←⊃(//)⎕VFI y
+      :If 0=≢y
+      :AndIf 0<⎕NC'default'
+          r←default
+      :Else
+          r←⊃(//)⎕VFI y
+      :EndIf
     ∇
 
     ∇ r←IsScripted y
@@ -302,7 +314,7 @@
     ∇ r←Create_UUID
     ⍝ Produces a UUID
       :Access Public Shared
-      r←'-'@(4+5×⍳4)⊢(⎕D,⎕C ⎕A)[4{9+|⍵}@20⊢5@15?36⍴16]
+      r←'-'@(4+5×⍳4)⊢(⎕D,⎕C ⎕A)[4(9+|)@20⊢5@15?36⍴16]
     ∇
 
     ∇ r←{type}Base64 txt;charset
@@ -420,4 +432,18 @@
           cats''∘four¨24 part 8 bits ⍵
       }
 
+    ∇ r←BitsToInt y
+    ⍝ Unsigned
+      :Access Public Shared
+      r←(32⍴2)⊥⌽32↑y
+    ∇
+
+
+    ∇ r←IntToBits y
+    ⍝ Unsigned
+      :Access Public Shared
+      r←⌽(32⍴2)⊤y
+    ∇
+
+
 :EndClass

APLSource/Admin/CopyScriptsFromPackagesIn.aplf

@@ -0,0 +1,24 @@
+ {r}←{targetFolder}CopyScriptsFromPackagesIn path2Packages;packages;i;package;packageID;packageName;fullName;F
+⍝ Copy scripts installed in `path2Packages` over to `targetFolder` which defaults to APLSource/
+⍝ Note that packages that are not just scripts are NOT handled. CommTools and FilesAndDirs are examples.
+⍝ This function is called by `CheckForLaterVersion`.
+ r←0
+ F←##.FilesAndDirs
+ targetFolder←{0<⎕NC ⍵:⍎⍵ ⋄ './APLSource/'}'targetFolder'
+ packages←{⍵.packageID}##.Registry.APLfromJSON⊃⎕NGET path2Packages,'/apl-buildlist.json'
+ :For i package :InEach (⍳≢packages)packages
+     packageID←⊃,/1↓⎕NPARTS package
+     packageName←{{⍵↑⍨¯1+⍵⍳'-'}⍵↓⍨⍵⍳'-'}packageID
+     fullName←⊃F.Dir targetFolder,'/',packageName,'.*'
+     :If 0=≢fullName
+         :If F.IsDir path2Packages,'/',packageID,'/APLSource'
+             r∨←(targetFolder,'/')(⎕NCOPY⍠('IfExists' 'ReplaceIfNewer')('Wildcard' 1)F.ExecNfunction)path2Packages,'/',packageID,'/APLSource/*'
+         :Else
+             r∨←(targetFolder,'/')(⎕NCOPY⍠('IfExists' 'ReplaceIfNewer')('Wildcard' 1)F.ExecNfunction)path2Packages,'/',packageID,'/',packageName,'*'
+         :EndIf
+     :Else ⍝ Simple files
+         fullName←⊃F.Dir path2Packages,'/',package,'/',packageName,'.*'
+         r∨←(targetFolder,'/')(⎕NCOPY⍠('IfExists' 'ReplaceIfNewer')F.ExecNfunction)fullName
+     :EndIf
+ :EndFor
+⍝Done

APLSource/Admin/HandleRunFunction.aplf

@@ -0,0 +1,9 @@
+ {r}←HandleRunFunction dummy;myZip;zipFilename
+⍝ Copies the "Run.aplf" function and also creates a ZIP file for it
+ r←0
+ './Dist/'⎕NCOPY⍠('IfExists' 'Replace')⊣'Run.aplf'
+ zipFilename←'./Dist/Run.zip'
+ myZip←⎕NEW ##.ZipArchive(,⊂zipFilename)
+ F.PWD myZip.Add'Run.aplf'
+ myZip.Dispose
+⍝Done

APLSource/Admin/Make.aplf

@@ -26,7 +26,7 @@
      :EndIf
  :EndIf
 
- path←(2 ⎕NQ #'GetEnvironment' 'USERPROFILE'),'\Documents\Dyalog APL Files\StartupSession\CiderTatin\Tatin'
+ path←(2 ⎕NQ #'GetEnvironment' 'USERPROFILE'),'\Documents\Dyalog APL Files\SessionExtensions\CiderTatin\Tatin'
  :If F.IsDir path                                           ⍝ Does a folder Tatin/  live in the version-agnostic folder?
  :AndIf F.IsFile path,'/Tatin.dyalog'                       ⍝ Does the Tatin user command script live there?
      file1←path,'/Tatin.dyalog'
@@ -89,6 +89,7 @@
  0 0⍴{⎕←⍵}⍣(~batchFlag)⊣'   Process started for "making" the Tatin Server...'
  {⍵.HasExited:shy←0 ⋄ _←⎕DL 0.2 ⋄ ∇ ⍵}P_
  'The process exited with an error code'Assert 0=P_.Proc.ExitCode
+ HandleRunFunction ⍬
  UpdateTestServerAssets ⍬
  {}⎕SE.Link.Refresh'#.Tatin'
  :If CopyTatinClientToUserDocuments batchFlag

APLSource/Client/Add2Config.aplf

@@ -4,7 +4,7 @@
  cfg←ReadPackageConfigFile path
  ⍎'cfg.',name,'←value'
  :Trap Reg.ErrorNo
-     WritePackageConfigFile path cfg
+     0 WritePackageConfigFile path cfg
  :Else
      qdmx←⎕DMX
      msg←qdmx.EM

APLSource/Client/AddTatinVersionNumber.aplf

@@ -0,0 +1,5 @@
+ pkgCfg←AddTatinVersionNumber pkgCfg
+⍝ Inject or update the tatin version number the package configuration was created / changed by.
+⍝ `pkgCfg` is a namespace with values
+ pkgCfg.tatin_version←{⍵↑⍨¯1+⍵⍳'+'}2⊃Reg.Version
+⍝Done

APLSource/Client/BuildPackage.aplf

@@ -16,6 +16,9 @@
 ⍝      If no build number is specified the original build number is taken and bumped.
 ⍝      Otherwise the given version and build number rule (the build number is not bumped).
 ⍝   The package config file is updated as a side effect.
+ :If 'Win'≡##.APLTreeUtils2.GetOperatingSystem ⍬
+     'On Windows, Tatin requires .NET Framework to be available for building packages'Assert 0=##.APLTreeUtils2.ToNum 2 ⎕NQ #'GetEnvironment' 'DYALOG_NETCORE'
+ :EndIf
  parms.projectPath←RemoveFileProtocol parms.projectPath
  parms.projectPath←⊃1 ⎕NPARTS ##.FilesAndDirs.AddTrailingSep parms.projectPath
  cfg_←ReadPackageConfigFile parms.projectPath
@@ -43,7 +46,7 @@
  :If 0<≢cfg.assets
      cfg.assets←{1=≢⍵:⊃⍵ ⋄ 1↓⊃,/',',¨⍵}ProcessAssetsProp parms.projectPath cfg.assets
  :EndIf
- ⍝ CreateAPIfromCFG cfg   ⍝TODO⍝ Should we implement this?!
+ ⍝ CreateAPIfromCFG cfg   ⍝TODO⍝ Should we implement this?! Yes we should!
  :If ≢/{⎕JSON⍠('Dialect' 'JSON5')⊣⍵}¨cfg cfg_
      WritePackageConfigFile parms.projectPath cfg
  :EndIf

APLSource/Client/CheckBuildList.aplf

@@ -14,12 +14,12 @@
  filename1←folder,Reg.BuildListFilename
  filename2←folder,Reg.DependenciesFilename
  :If ~force
-     ⍝ Tatin always writes the dependency file first and the build list next to file,
-     ⍝ yet the timestamps in the milliseconds sometimes pretend it to be the other way round.
-     ⍝ Therefore we add one second to make sure that we only re-build the build list when the
-     ⍝ dependency file has really been modified by a user with an editor.
-     ts1←1 GetFileTime filename1
-     ts2←GetFileTime filename2
+     ⍝ Tatin always writes first the dependency file and only then the build list to the disk,
+     ⍝ yet the timestamps in the milliseconds sometimes pretend it to be the other way round (Windows).
+     ⍝ Therefore we add one second for the build list to make sure that we only re-build the build list
+     ⍝ when the dependency file has really been modified by a user with an editor.
+     ts1←GetFileTime filename1
+     ts2←1 GetFileTime filename2
  :EndIf
  tree←ReadBuildList filename1
  deps←ReadDependencyList filename2

APLSource/Client/CreateAPIfromCFG.aplf

@@ -6,7 +6,7 @@
 ⍝ We need to establish a way that allows indentifying the namespace within a project that is going to be the package, if any!
 ⍝ In my (Kai's) case it is by convention: A project Foo always has a namepsace Foo.Foo that is going to be the package.
 ⍝ However, other people may have different ideas, including one where the project is actually identical with the package.
- ∘∘∘
+ ∘∘∘   ⍝TODO⍝
  r←⍬
  api←'##.',cfg.name,'.',cfg.api
  :If ~(⎕NC⊂api)∊9.4 9.5             ⍝ Not for classes and interfaces

APLSource/Client/InitPackageConfig.aplf

@@ -61,6 +61,7 @@
      {}cfg.⎕EX'wx'              ⍝ Not anymore (since 0.61.0)
      list←(' '~¨⍨↓cfg.⎕NL 2)~' '~¨⍨↓'_'cfg.⎕NL 2 ⍝ user properties start with "_" by convention
      bool←list∊varsList,('uri' 'date') ⍝ These are injected by the server
+     bool∨←list∊'tatin_version' ''
      :If ∨/~bool
          msg←'Invalid propert',((1+1<+/~bool)⊃'y' 'ies'),' in config namespace: ',⊃{⍺,',',⍵}/((~bool)/list)
          msg Assert 0

APLSource/Client/InitialisePackage.aplf

@@ -10,7 +10,7 @@
      folder←⍵
      _←F.MkDir folder
      ('file "',CFG_Name,'" already exists')Assert 0=F.Exists folder,'/',CFG_Name:1
-     cfg←1 WritePackageConfigFile folder cfg
+     cfg←0 WritePackageConfigFile folder cfg
      fn←folder,'/',cfg.source
      _←{F.MkDir ⍵}⍣(0=F.Exists fn)⊣fn
      1:cfg

APLSource/Client/LoadDependencies.aplf

@@ -21,7 +21,7 @@
  :If isUC←'[myucmds]'{⍺≡⎕C(≢⍺)↑⍵}installFolder
      installFolder←GetMyUCMDsFolder(≢'[myucmds]')↓installFolder
  :EndIf
- ('Folder does not exist:',⍕installFolder)Assert ⎕NEXISTS installFolder
+ ('Folder does not exist: ',⍕installFolder)Assert ⎕NEXISTS installFolder
  :If 0=≢targetSpace
      targetSpace←(1+isUC)⊃'#' '⎕SE'
  :EndIf

APLSource/Client/LoadPackages.aplf

@@ -49,7 +49,7 @@
  :EndTrap
  →(0=≢paths)/0
  :Trap Reg.ErrorNo
-     loaded←LoadDependencies tempFolder targetSpace
+     r←≢loaded←LoadDependencies tempFolder targetSpace
  :Else
      qdmx←⎕DMX
      ⎕DL 0.01
@@ -58,7 +58,6 @@
      (⊃{0=≢⍺:⍵ ⋄ ⍺}/qdmx.(Message EM))⎕SIGNAL{⍺=0:⍵ ⋄ ⍺}/qdmx.(ENX EN)
  :EndTrap
  ⎕DL 0.01
- r←≢F.ListDirs tempFolder,'/'
  :If ~MyUserSettings.caching
      list←F.ListDirs tempFolder
      :If 0=≢list                                                ⍝ Anything? At all?!

APLSource/Client/WritePackageConfigFile.aplf

@@ -1,34 +1,34 @@
- {cfg}←{initializeFlag}WritePackageConfigFile(path cfg);qdmx;cfg_file;tmp
-⍝ Write package config file to disk.
-⍝ By default several properties are checked and an error is thrown in case something is not quite right,
-⍝ This can be changed by passing a 1 as ⍺. In this case two checks are NOT perfortmed:
-⍝ * "source" might be empty
-⍝ * "assets" is ignored, and therefore might not exist
- initializeFlag←{0<⎕NC ⍵:⍎⍵ ⋄ 0}'initializeFlag'
+{cfg}←{check}WritePackageConfigFile(path cfg);qdmx;cfg_file;tmp
+⍝ Write package config file to disk.\\
+⍝ By default several properties are checked and an error is thrown in case something is not quite right.\\
+⍝ This can be changed by passing a 0 as ⍺. In this case the checks are **not** performed.
+ check←{0<⎕NC ⍵:⍎⍵ ⋄ 1}'check'
  cfg←InitPackageConfig cfg
- :If 0=initializeFlag
+ :If check
      '"source" must not be empty'Assert 0<≢cfg.source
  :EndIf
  '"source" must be simple'Assert 1=|≡cfg.source
  '"source" must be character'Assert' '=1↑0⍴cfg.source
  path←⊃1 ⎕NPARTS path,'/'
  cfg_file←path,CFG_Name
- {}ValidateVersion cfg.version
- cfg←ValidatePackageFiles cfg
- cfg←initializeFlag ValidateOSprops cfg
- cfg←ValidateTags cfg
- cfg←ValidateAPI cfg
- cfg←ValidateDocumentation cfg
- :If 0=≢cfg.license
-     cfg.license←MyUserSettings.license
+ :If check
+     {}ValidateVersion cfg.version
+     cfg←ValidatePackageFiles cfg
+     cfg←check ValidateOSprops cfg
+     cfg←ValidateTags cfg
+     cfg←ValidateAPI cfg
+     cfg←ValidateDocumentation cfg
+     :If 0=≢cfg.license
+         cfg.license←MyUserSettings.license
+     :EndIf
+     cfg←ValidateMaintainer cfg
+     cfg←path ValidateFiles cfg
+     ⍝ Note that we cannot validate the license, that's up to the server.
+     'Invalid: "assets" - not a path'Assert~','∊cfg.assets
+     cfg.assets←path PolishAssetsPaths cfg.assets
+     path ValidateAssets cfg.assets
+     {}path CheckAssetsExist cfg.assets
  :EndIf
- cfg←ValidateMaintainer cfg
- cfg←path ValidateFiles cfg
- ⍝ Note that we cannot validate the license, that's up to the server.
- 'Invalid: "assets" - not a path'Assert~','∊cfg.assets
- cfg.assets←path PolishAssetsPaths cfg.assets
- path ValidateAssets cfg.assets
- {}path CheckAssetsExist cfg.assets
  'Invalid package name'Assert 0=(⎕NS''){0=≢⍵:0 ⋄ ⍺.⎕NC ⍵}cfg.name
  tmp←cfg_file,'.tmp'
  :Trap 0

APLSource/CodeCoverage.aplc

@@ -54,11 +54,13 @@
 
     ∇ r←Version
       :Access Public Shared
-      r←'CodeCoverage' '0.10.2+52' '2023-04-09'
+      r←'CodeCoverage' '0.10.3+52' '2023-06-23'
     ∇
 
     ∇ History
       :Access Public Shared
+    ⍝ * 0.10.3 from 2023-04-23
+    ⍝   * Bug fix: Instance names could not be assigned to "ignore"
     ⍝ * 0.10.2 from 2023-04-09
     ⍝   * On non-Windows platforms the file access matrix needs setting to avoid problems
     ⍝ * 0.10.1 from 2023-04-08
@@ -137,18 +139,14 @@
         ∇ r←Get
           r←','(≠⊆⊢),_ignore
         ∇
-        ∇ set value;v;b;v2;noOf
+        ∇ set value;v;noOf
           :If 0=noOf←+/∧\1=≡¨value.NewValue
               v←∊value.NewValue
           :Else
               v←(⊃{⍺,',',⍵}/noOf↑value.NewValue),noOf↓value.NewValue
           :EndIf
           'Must be character vector'⎕SIGNAL 11/⍨' '≠1↑0⍴v
           ('Has invalid characters',b/v)⎕SIGNAL 11/⍨∨/b←~v∊APL_Chars,',⎕#.'
-          v2←','(≠⊆⊢),v
-          :If ∨/~b←0<⎕NC⊃v2
-              11 ⎕SIGNAL⍨'Unknown names: ',⊃{⍺,',',⍵}/(~b)/v2
-          :EndIf
           _ignore←v
         ∇
     :EndProperty