Handling of <watch> improved and Help polished

APLSource/Cider/History.apla

@@ -1,4 +1,10 @@
 (
+ '* 0.42.0 ⋄ 2024-07-04'
+ '  * Help page for "OpenProject" improved'
+ '  * -??? help page for "OpenProject" added'
+ '  * In OpenProject, -watch= did not allow "none"'
+ '  * -watch=, when specified, was not reported; now it is ALWAYS reported'
+ '  * A [LINK] section in the Cider config file is from now on ignored in case there is a file .linkconfig      '
  '* 0.41.1 ⋄ 2024-06-27'
  '  * On Linux and Mac-OS, the folder /home/<⎕AN> is no longer hard coded but established with '
  '    2 ⎕NQ ''.'' ''GetEnvironment'' ''HOME'''

APLSource/Cider/OpenProject.aplf

@@ -17,7 +17,7 @@
  '"folder" must be specified'Assert 0<parms.⎕NC'folder'
  '"folder" must be specified'Assert 0<≢parms.folder
  '"projectSpace" must be specified'Assert 0<parms.⎕NC'projectSpace'
- '"watch" must be one of: ns|dir|both'Assert(⊂⎕C parms.watch)∊'ns' 'dir' 'both' 0
+ '"watch" must be one of: ns|dir|both'Assert(⊂⎕C parms.watch)∊'ns' 'dir' 'both' 'none' 0
  p←{⍺←parms.(verbose batch) ⋄ ⍺ PrintToSession ⍵}
  parms←(p GetFolderFromAlias)parms
  ('Folder does not exist: ',parms.folder)Assert F.Exists parms.folder
@@ -63,12 +63,7 @@
  configFilename HandleSysVars config
  source←parms.folder,(0<≢config.CIDER.source)/'/',config.CIDER.source           ⍝ For linking we are only interested in the code folder
  ('Source folder does not exist: ',parms.folder)Assert F.Exists parms.folder
- linkOptions←ExtractLinkOptions config                                          ⍝ Merge the default options with Cider's options
- :If 0≢parms.watch
-     config.LINK.watch←linkOptions.watch←parms.watch                            ⍝ Was specified by the user
- :Else
-     parms.watch←(1+HasDotNet)⊃'ns' 'both'                                      ⍝ Default is "both" but for the time being only when .NET is available
- :EndIf
+ linkOptions←ProcessLinkOptions parms config
  p'Bringing in the source code...'
  projectSpace_←CheckTargetNamespaceAndLinkFolder projectSpace_ parms config.CIDER.source
  :If parms.importFlag
@@ -85,8 +80,9 @@
          res Assert 0=parms.batch
          (1 parms.batch)p res
      :EndIf
-     (1 parms.batch)p ReportLinkSettings config
  :EndIf
+ (1 parms.batch)p'watch'ReportLinkSettings linkOptions
+ 1 p parms.batch ReportWatch res
  :If 0=parms.noPkgLoad
      pkgStatus←parms CheckForTatinPackages config
      :If 0<pkgStatus

APLSource/Cider/ProcessLinkOptions.aplf

@@ -0,0 +1,29 @@
+ r←ProcessLinkOptions(parms config);path;filename;msg
+ r←⎕NS''
+ path←config.CIDER.source{0=≢⍺:⍵ ⋄ ⍵,'/',⍺}parms.folder
+ filename←(F.AddTrailingSep path),'.linkconfig'
+ :If F.IsFile filename
+     :If 0≢parms.watch
+         r.watch←parms.watch                     ⍝ Was specified by the user, and that takes (temporarily) precendence
+     :EndIf
+     :If 9=config.⎕NC'LINK'
+     :AndIf 0<≢config.LINK.⎕NL⍳16
+     :AndIf 0=parms.batch
+         msg←''
+         msg,←⊂'There is a file .linkconfig in:'
+         msg,←⊂F.EnforceSlash path
+         msg,←⊂'but there is also a non-empty "Link" section in Cider''s config file'
+         msg,←⊂'which will be ignored because of the .linkconfig file.'
+         msg,←⊂'Consider deleting the "Link" section from Cider''s config file!'
+         Box Frame msg
+     :EndIf
+ :Else
+     r←ExtractLinkOptions config                 ⍝ Merge the default options with Cider's options
+     :If 0≢parms.watch
+         config.LINK.watch←parms.watch           ⍝ Was specified by the user, and that takes (temporarily) precendence
+     :ElseIf 2=r.⎕NC'watch'
+         parms.watch←r.watch
+     :Else
+         parms.watch←(1+HasDotNet)⊃'ns' 'both'   ⍝ Default is "both" but for the time being only when .NET is available
+     :EndIf
+ :EndIf

APLSource/Cider/ReportLinkSettings.aplf

@@ -1,8 +1,16 @@
- {r}←ReportLinkSettings cfg;list
+ {r}←{ignore}ReportLinkSettings linkOptions;list;defaults;ind;b;list2
 ⍝ Report all Link settings (if any) that differ from their default
-⍝ `cfg` is a namespace representing a project's Cider config file.
  r←''
- list←' '~⍨¨↓cfg.LINK.⎕NL 2
- :If 0<≢list
-     r←cfg∘{'LINK:',⍵,'=',⍕⍺.LINK⍎⍵}¨list
+ ignore←{2=⎕NC ⍵:⍎⍵ ⋄ ''}'ignore'
+ :If ~(⊂linkOptions)∊''⍬
+     list←' '~⍨¨↓linkOptions.⎕NL 2
+     list←list~⊆ignore
+     :If 0<≢list
+         defaults←⎕SE.Link.U.DefaultOpts ⍬
+         list2←' '~⍨¨↓defaults.⎕NL 2
+         ind←list2⍳list
+         (list ind)←(ind≤≢list2)∘/¨list ind
+     :AndIf ∨/b←(linkOptions.⍎¨list)≢¨defaults.⍎¨list2[ind] ⍝ Where does the actual value differ from the default?
+         r←linkOptions.{⍵,'=',⍎⍵}¨b/list
+     :EndIf
  :EndIf

APLSource/Cider/ReportWatch.aplf

@@ -0,0 +1,15 @@
+ r←batchFlag ReportWatch msgs
+⍝ "msgs" is what was return by Link's `Create` or `Import` function.
+⍝ Returns the setting of Link's "watch" parameter.
+⍝ Because it is so important it is always reported, even when it carries the default.
+ r←''
+ :If ~batchFlag
+     r←'Link parameter "watch" is <'
+     r,←,{
+         ∨/'←→'⍷⍵:'both'
+         ∨/'←'⍷⍵:'dir'
+         ∨/'→'⍷⍵:'ns'
+         'none'
+     }msgs
+     r,←,'>'
+ :EndIf

APLSource/Cider/UC/Help.aplf

@@ -56,43 +56,27 @@
  :Case 1
      :Select ⎕C Cmd
      :Case ⎕C'OpenProject'
-         r,←⊂'Takes a path to a folder that must host a file "',##.ConfigFilename,'" or a pre-defined alias.'
+         r,←⊂'Takes a path to a folder that must host a file "',##.ConfigFilename,'" or a pre-defined [alias].'
          r,←⊂'The config file must specify all variables required by Cider, including "source".'
          r,←⊂'The contents of "source" is then linked to "parent.projectSpace" by default.'
-         r,←⊂'If no folder or alias is specified, Cider will present a list with all defined aliases.'
-         r,←⊂''
-         r,←⊂'An alias must be embraced by square brackets, for example:'
-         r,←⊂'    ]Cider.OpenProject [alias]'
-         r,←⊂'The "*" wildcard is supported, but only at the end. The following statement will list all'
-         r,←⊂'projects that start their names with "A"'
-         r,←⊂'    ]Cider.OpenProject [A*]'
          r,←⊂''
          r,←⊂'-parent         The project is loaded into Cider.(parent.projectSpace) unless this is (temporarily)'
          r,←⊂'                overwritten by setting the -parent= and/or the -projectSpace= option(s).'
-         r,←⊂'-projectSpace   The project is loaded into Cider.(parent.projectSpace) unless this is (temporarily)'
-         r,←⊂'                overwritten by setting the -projectSpace= and/or the -parent= option(s).'
-         r,←⊂'-import         By default the namespace is linked to folder. By specifying the -import'
-         r,←⊂'                flag this can be avoided: the code is then loaded into the workspace with the'
-         r,←⊂'                Link.Import method, meaning that changes are not tracked.'
-         r,←⊂'                With -import the status of neither Git nor any installed Tatin packages is checked.'
+         r,←⊂'-projectSpace   See -parent.'
+         r,←⊂'-import         By default the namespace is linked to a folder. By specifying the -import flag this'
+         r,←⊂'                can be avoided: the code is then loaded with Link.Import and changes are not tracked.'
          r,←⊂'-alias=         In case you are going to work on a project frequently you may specify -alias=name '
          r,←⊂'                for quicker access: rather than a path you can then specify just the [alias].'
-         r,←⊂'                Note that aliases are not case sensitive.'
-         r,←⊂'                (In order to remove an alias use ]Cider.ListAliases -edit)'
          r,←⊂'-noPkgLoad      By default the Tatin packages from the installation folder(s) defined in the'
          r,←⊂'                config file will be loaded. If you don''t want this specify -noPkgLoad'
-         r,←⊂'-watch          Defaults to "both" (if .NET is available) but may be "ns" or "dir" instead when Link 3'
-         r,←⊂'                is around. With Link 4 and later this is left to Link.'
-         r,←⊂'                * "ns" means that changes in the workpace are saved on disk'
-         r,←⊂'                * "dir" means that any changes on disk are brought into the WS'
-         r,←⊂'                * "both" means that any changes in either "ns" or "dir" are reflected accordingly'
-         r,←⊂'                   However, currently "both" works only under Windows.'
-         r,←⊂'                   Note that the flag does NOT change the config file on disk'
+         r,←⊂'-watch          Defaults to "both" (if .NET is available!) but may be "ns", "dir" or "none" instead.'
          r,←⊂'                Refer to the Link documentation for details.'
+         r,←⊂'                This flag does NOT change the config file on disk: it''s a temporary measure.'
          r,←⊂'-verbose        If this is specified then Cider reports every single step it carries out.'
          r,←⊂'-ignoreUserExec Suppress execution of a user function defined in Cider''s config file once'
-         r,←⊂'-batch          Does not print to the session and prevents user interaction. In a situation were'
-         r,←⊂'                user must decide what to do an error is thrown.'
+         r,←⊂'-batch          Does not print to the session and prevents user interaction. This is for test cases;'
+         r,←⊂'                If you feel a need for this you should use the API function "⎕SE.Cider.OpenProject".'
+         r,←⊂'Fore more help enter -???'
      :Case ⎕C'AddNuGetDependencies'
          r,←⊂'Requires one mandatory argument: a comma-separated list of NuGet packages to be installed.'
          r,←⊂''
@@ -253,5 +237,28 @@
          r,←⊂'one or both of them on display in the default browser.'
      :EndSelect
  :Case 2
-     r,←⊂'There is no additional help available'
+     :Select ⎕C Cmd
+     :Case ⎕C'OpenProject'
+         r,←⊂'Paths and Aliases'
+         r,←⊂'-----------------'
+         r,←⊂'1. If neither a folder nor an alias is specified, Cider will present a list with all known projects.'
+         r,←⊂'2. Aliases are NOT case sensitive'
+         r,←⊂'3. In order to remove an alias use:'
+         r,←⊂'   ]Cider.ListAliases -edit'
+         r,←⊂'4. The "*" wildcard is supported, but only at the end. The following statement will list all'
+         r,←⊂'   projects that start their names with "A"'
+         r,←⊂'   ]Cider.OpenProject [A*]'
+         r,←⊂''
+         r,←⊂'The -watch= flag'
+         r,←⊂'----------------'
+         r,←⊂'* With Link 4 and later, "watch" should be defined in a Link config file.'
+         r,←⊂'  This flag does NOT change the config file on disk: it''s a temporary measure.'
+         r,←⊂'* "watch" defaults to "both" (but only if if .NET is available). There are other options available.'
+         r,←⊂'                * "both" means that any changes in either "ns" or "dir" are reflected accordingly'
+         r,←⊂'   * "ns"   : Changes in the workpace are saved on disk'
+         r,←⊂'   * "dir"  : Changes on disk are brought into the WS'
+         r,←⊂'   * "none" : Changes are ignored'
+     :Else
+         r,←⊂'There is no additional help available'
+     :EndSelect
  :EndSelect

APLSource/Cider/UC/List.aplf

@@ -6,7 +6,7 @@
      c.Name←'OpenProject'
      c.Desc←'Load all source files into the WS and keep it linked by default'
      c.Group←'Cider'
-     c.Parse←'1s -projectSpace= -parent= -alias= -suppressInit -import -noPkgLoad -ignoreUserExec -watch=ns dir both -verbose -batch'
+     c.Parse←'1s -projectSpace= -parent= -alias= -suppressInit -import -noPkgLoad -ignoreUserExec -watch=ns dir both none -verbose -batch'
      r,←c
 
      c←⎕NS''

APLSource/Cider/Version.aplf

@@ -1,7 +1,3 @@
  r←Version
 ⍝ See also `History`
-<<<<<<< HEAD
- r←'0.41.0+671'
-=======
- r←'0.41.1+671'
->>>>>>> dev
+ r←'0.42.0+671'

APLSource/TestCases/Test_Open_053.aplf

@@ -0,0 +1,31 @@
+ R←Test_Open_053(stopFlag batchFlag);⎕TRAP;parms;qdmx;filename;success;log
+⍝ Open a project with watch=none
+ ⎕TRAP←(999 'C' '∘∘∘ ⍝ Deliberate error')(0 'N')
+ R←T._Failed
+
+ 'TEMP'#.⎕NS''
+
+ parms←##.Cider.CreateOpenParms ⍬
+ parms.folder←∆GetTestPath⊃⎕SI
+ parms.parent←'#.TEMP'
+ parms.watch←'none'
+ parms.ignoreUserExec←1
+ parms.batch←1
+ filename←parms.folder,'/APLSource/Hello.aplf'
+ (⊂'r←Hello' 'r←''World''')⎕NPUT filename 1
+ ##.Cider.C.YesOrNo_Answers←1 2⍴'ChangeCurrentDir@' 'n'
+
+ (success log)←##.Cider.OpenProject parms
+ Assert success
+ →T.GoToTidyUp∨/'ERROR'⍷log
+
+ →T.GoToTidyUp'none'≢#.TEMP.Foo.CiderConfig.LINK.watch
+
+ R←T._OK
+
+∆TidyUp:
+ ##.Cider.C.Cleanup
+ {}(~parms.batch)⎕SE.Cider.CloseProject'#.TEMP.Foo'
+ (⊂'r←Hello' 'r←''World''')⎕NPUT filename 1
+ #.⎕EX'TEMP'
+⍝Done

TestData/myproj/APLSource/.linkconfig

@@ -1 +1 @@
-{  LinkVersion: { ID: "4.0.17"},  Settings: {    watch: "ns",  },}
+{  LinkVersion: { ID: "4.0.17"},  Settings: {    watch: "none",  },}

Tests/Test_Open_053/APLSource/Hello.aplf

@@ -1,2 +1,2 @@
- r←Hello
- r←'World'
+r←Hello
+r←'World'

Tests/Test_Open_053/cider.config

@@ -1 +1,29 @@
-{  CIDER: {    init: "",    make: "",    parent: "#",    projectSpace: "Foo",    project_url: "",    source: "APLSource",    dependencies: {        tatin: "packages",    },    dependencies_dev: {        tatin: "packages_dev=TestCases",    },    tests: "",  },  LINK: {    watch: "ns",  },  SYSVARS: {    io: 1,    ml: 1,  },  USER: {  },}
+{
+  CIDER: {
+    cider_version: "0.42.0",
+    dependencies: {
+      nuget: "",
+      tatin: "packages",
+    },
+    dependencies_dev: {
+      tatin: "packages_dev=TestCases",
+    },
+    distributionFolder: "",
+    init: "",
+    make: "",
+    parent: "#",
+    projectSpace: "Foo",
+    project_url: "",
+    source: "APLSource",
+    tests: "",
+  },
+  LINK: {
+    watch: "ns",
+  },
+  SYSVARS: {
+    io: 1,
+    ml: 1,
+  },
+  USER: {
+  },
+}

apl-package.json

@@ -21,5 +21,5 @@
   tags: "project-management",
   tatin_version: "0.103.0",
   userCommandScript: "APLSource/Cider_UC.dyalog",
-  version: "0.41.1+749",
+  version: "0.42.0+751",
 }

docs/Cider-API-Reference.md

@@ -482,6 +482,8 @@ You may instead set this to "ns", which forces Link to write changes in the WS t
 
 You may also set this to "dir", when changes on the file system will be brought into the WS while changes in the WS are _not_ saved to disk.
 
+Specify "none" if all changes should be ignored.
+
 Other settings of `watch` will result in an error.
 
 Note that `CreateOpenParms` will assign a `0` to `watch. That allows recognizing whether the user has set this; eventually 0 will become "both", the default.
@@ -562,3 +564,4 @@ This can be just `1.2.3`,  but it may be something like `1.2.3-beta-1+113`
 
 
 
+

docs/Cider-User-Guide.md

@@ -446,16 +446,22 @@ These are LINK parameters which are passed on to LINK when Cider brings the APL
 
 Note that this is a temporary solution: LINK should have its own config files for this, and will get them with Link 4.0. 
 
-However, until all supported versions of Link can deal with Link's own configuration file, Cider will save non-defaults values in a Cider project config file.
+However, until all supported versions of Link can deal with Link's own configuration file, Cider will save non-default values in a Cider project config file.
+
+If there is a Link config file by the name `.linkconfig`, then any definition in the "Link" section of the Cider config file is ignored. A message will remind the user of deleting the "Link" section from the Cider config file.
+
+Cider will look for the file in what [`source`](#) defines. If `source` is empty then it is the root of the project.
 
 ###### watch
 
 Defines which source to track for changes, so the other can be synchronised.
 
-Defaults to "both" (namespace _and_ disk) and "ns" otherwise. Can also be "dir". 
+Defaults to "both" (namespace _and_ disk) and "ns" otherwise. Can also be "dir" and "none". 
 
 Note that for "both" and "dir" .NET or .NET Core is required. Under Windows this is a given, but not so on Linux and Mac-OS: it may or may not be available. If it is not, the default for "watch" will be "ns".
 
+"watch" is a very important parameter; that's why Cider will always report the setting. Other Link settings are only reported when they diverge from the default.
+
 ##### SYSVARS
 
 This section allows you to define system variables. `⎕IO` and `⎕ML` should always be defined here.
@@ -844,5 +850,6 @@ An example:
 
 
 
+
 
 

html/Cider-API-Reference.html

@@ -434,6 +434,7 @@ <h3 data-id="watch">22.7. watch</h3>
 <p>Defaults to “both”, meaning that changing any APL objects in the workspaces will result in Link updating the corresponding file on disk, and any change on disk will be reflected by changing the workspace.</p>
 <p>You may instead set this to “ns”, which forces Link to write changes in the WS to disk but ignore changes on the file system.</p>
 <p>You may also set this to “dir”, when changes on the file system will be brought into the WS while changes in the WS are <em>not</em> saved to disk.</p>
+<p>Specify “none” if all changes should be ignored.</p>
 <p>Other settings of <code>watch</code> will result in an error.</p>
 <p>Note that <code>CreateOpenParms</code> will assign a <code>0</code> to `watch. That allows recognizing whether the user has set this; eventually 0 will become “both”, the default.</p>
 <div class="leanpub_A">

html/Cider-User-Guide.html

@@ -586,15 +586,18 @@ <h5 data-id="LINK">2.6.1.2. LINK</h5>
 </div>
 <p>These are LINK parameters which are passed on to LINK when Cider brings the APL code into the WS with LINK.</p>
 <p>Note that this is a temporary solution: LINK should have its own config files for this, and will get them with Link 4.0.</p>
-<p>However, until all supported versions of Link can deal with Link's own configuration file, Cider will save non-defaults values in a Cider project config file.</p>
+<p>However, until all supported versions of Link can deal with Link's own configuration file, Cider will save non-default values in a Cider project config file.</p>
+<p>If there is a Link config file by the name <code>.linkconfig</code>, then any definition in the “Link” section of the Cider config file is ignored. A message will remind the user of deleting the “Link” section from the Cider config file.</p>
+<p>Cider will look for the file in what <a href="#source" class="bookmark_link"><code>source</code></a> defines. If <code>source</code> is empty then it is the root of the project.</p>
 <div class="h_tag">
 <a href="#watch" id="watch" class="autoheader_anchor">
 <h6 data-id="watch">2.6.1.2.1. watch</h6>
 </a>
 </div>
 <p>Defines which source to track for changes, so the other can be synchronised.</p>
-<p>Defaults to “both” (namespace <em>and</em> disk) and “ns” otherwise. Can also be “dir”.</p>
+<p>Defaults to “both” (namespace <em>and</em> disk) and “ns” otherwise. Can also be “dir” and “none”.</p>
 <p>Note that for “both” and “dir” .NET or .NET Core is required. Under Windows this is a given, but not so on Linux and Mac-OS: it may or may not be available. If it is not, the default for “watch” will be “ns”.</p>
+<p>“watch” is a very important parameter; that's why Cider will always report the setting. Other Link settings are only reported when they diverge from the default.</p>
 <div class="h_tag">
 <a href="#sysvars" id="sysvars" class="autoheader_anchor">
 <h5 data-id="SYSVARS">2.6.1.3. SYSVARS</h5>