Skip to content

Commit

Permalink
Documentation amended
Browse files Browse the repository at this point in the history
  • Loading branch information
@aplteam
aplteam committed Apr 18, 2023
1 parent d301c5d commit bcb8e53
Show file tree
Hide file tree
Showing 4 changed files with 53 additions and 33 deletions.
22 changes: 15 additions & 7 deletions APLSource/Cider/Cider.aplc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,7 @@
:EndIf
:EndIf
InjectConfigDataIntoProject config projectSpace_ parms.folder
{}ExecProjectInitFunction⍣(~parms.suppressInit)⊣config projectSpace_
{}ExecProjectInitFunction⍣(~parms.suppressInit)⊣config projectSpace_ parms.folder
ExecUserFunction config
successFlag←SUCCESS
:If 0=parms.quietFlag
Expand Down Expand Up @@ -650,21 +650,21 @@
:EndIf
∇

∇ {r}←ExecProjectInitFunction(config projectSpace);fns
∇ {r}←ExecProjectInitFunction(config projectSpace projectHome);fns
⍝ Check whether a function "lx" is specified in the configuration and if so execute it.
r←0
:If 0<≢config.CIDER.init
:If '⋄'∊config.CIDER.init
(⊂projectSpace config)ExecProjectFunction_¨'⋄'(≠⊆⊢)config.CIDER.init
:Else
(projectSpace config)ExecProjectFunction_ config.CIDER.init
(projectSpace config projectHome)ExecProjectFunction_ config.CIDER.init
:EndIf
:EndIf
∇

∇ {r}←x ExecProjectFunction_ init;fns;config;projectSpace;qdmx
∇ {r}←x ExecProjectFunction_ init;fns;config;projectSpace;qdmx;projectHome
r←⍬
(projectSpace config)←x
(projectSpace config projectHome)←x
:If 3=projectSpace.⎕NC init
p'Executing the project''s initialising function "',(init~' '),'"...'
:Select 1 2⊃projectSpace.⎕AT init
Expand All @@ -675,16 +675,24 @@
qdmx←⎕DMX
1 p Frame'Executing "init" crashed: ',qdmx.EM
:EndTrap
:CaseList 1 ¯2
:Case 1
fns←projectSpace.⍎init
:Trap 0
fns config
:Else
qdmx←⎕DMX
1 p Frame'Executing "init" crashed: ',qdmx.EM
:EndTrap
:CaseList 2 ¯2
fns←projectSpace.⍎init
:Trap 0
projectHome fns config
:Else
qdmx←⎕DMX
1 p Frame'Executing "init" crashed: ',qdmx.EM
:EndTrap
:Else
1 p Frame'Invalid function valence: is ambivalent'
'Invalid value returned by ⎕AT'⎕SIGNAL 11
:EndSelect
:Else
1 p Frame'Could not execute "',init,'": function not found; check config file!'
Expand Down
2 changes: 1 addition & 1 deletion apl-package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,5 +19,5 @@
source: "APLSource/Cider/",
tags: "project-management",
userCommandScript: "APLSource/Cider_UC.dyalog",
version: "0.24.1+393",
version: "0.24.1+394",
}
39 changes: 23 additions & 16 deletions docs/Cider-User-Guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,9 +132,14 @@ packages=Foo,packages_dev=TestCases

###### init

If not empty this must be an expression that would call a function within the project. It must be defined relative to `projectSpace`.
If not empty this must be the name of a function within `projectSpace`. The function will be executed after a project was opened.

The expression will be executed after a project was opened.
Such a function should not return a result.

Such a function may be niladic, monadic, ambivalent or dyadic:

* A non-niladic function receives a namespace with the project configuration as right argument
* An ambivalent or dyadic function receives a path as left argument: this is the home folder of the project


###### make
Expand Down Expand Up @@ -213,6 +218,8 @@ Defaults to "both" but can be "ns" or "dir" as well.

Defines which source to track for changes, so the other can be synchronised.

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".

##### SYSVARS

This section allows you to define system variables. `⎕IO` and `⎕ML` should always be defined here.
Expand Down Expand Up @@ -369,14 +376,12 @@ Now there might well be demand for executing some code to initialise your projec
This can be achieved by assigning the name of a function to `init`. This must again be relative to the root of your project.
Notes:
* The function should not return a result. If it does anyway it should be shy. Any result would be ignored.
* The function must be either monadic or niladic. If it is monadic then `⍬` is passed as the right argument.
The function should not return a result. If it does anyway it should be shy. Any result would be ignored.
What is passed as the right argument might well change in a future release.
Such a function may be niladic, monadic, ambivalent or dyadic:
Note that you can access the configuration data of the project from within your initialisation function by questioning the `CiderConfig` namespace.
* A non-niladic function receives a namespace with the project configuration as right argument
* An ambivalent or dyadic function receives a path as left argument: this is the home folder of the project
#### 9. Executing user-specific code
Expand All @@ -396,17 +401,10 @@ That file already contains a definition of the keyword `ExecuteAfterProjectOpen`
}
```
What is this good for you may ask? Well, let's assume that you are not using Git but a different version control Software. With Git, Cider would execute the "status" command and show the result to the user. With your version control software, it can't do something similar.
What is this good for you may ask? Well, let's assume that you are not using Git but a different version control software. With Git, Cider would execute the "status" command and show the result to the user. With your version control software, it can't do something similar.
You can easily achieve that by yourself: just add the required code to a function you load early into `⎕SE`, and then make sure that `ExecuteAfterProjectOpen` is calling that function and you are done.
[^tatin]: _Tatin_ is a Dyalog APL package manager: <https://github.com/aplteam/Tatin>
[^link]: _LINK_ is a tool designed to bring APL code into the workspace and keep it in sync with the files the code came from: <https://github.com/dyalog/Link>
[^load_tatin_pkgs]: Strictly speaking only references to the packages are injected into your application or tool. The actual packages are loaded into either `#._tatin` or `⎕SE._tatin`
[^winonly]: At the time of writing (July 2022) this works under Windows but not on other operating systems. However, Dyalog plans to implement this feature on all platforms.
## Misc
Expand Down Expand Up @@ -446,3 +444,12 @@ The following example was created in a workspace where the project `APLGit2` was
aplteam-IniFiles-5.0.3 0 https://tatin.dev/
aplteam-DotNetZip-2.0.2 0 https://tatin.dev/
```
[^tatin]: _Tatin_ is a Dyalog APL package manager: <https://github.com/aplteam/Tatin>
[^link]: _LINK_ is a tool designed to bring APL code into the workspace and keep it in sync with the files the code came from: <https://github.com/dyalog/Link>
[^load_tatin_pkgs]: Strictly speaking only references to the packages are injected into your application or tool. The actual packages are loaded into either `#._tatin` or `⎕SE._tatin`
[^winonly]: At the time of writing (July 2022) this works under Windows but not on other operating systems. However, Dyalog plans to implement this feature (or something similar) on all platforms.
23 changes: 14 additions & 9 deletions html/Cider-User-Guide.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -144,8 +144,13 @@ <h6 data-id="tatinFolder">2.2.1.1.4. tatinFolder</h6>
<h6 data-id="init">2.2.1.1.5. init</h6>
</a>
</div>
<p>If not empty this must be an expression that would call a function within the project. It must be defined relative to <code>projectSpace</code>.</p>
<p>The expression will be executed after a project was opened.</p>
<p>If not empty this must be the name of a function within <code>projectSpace</code>. The function will be executed after a project was opened.</p>
<p>Such a function should not return a result.</p>
<p>Such a function may be niladic, monadic, ambivalent or dyadic:</p>
<ul>
<li>A non-niladic function receives a namespace with the project configuration as right argument</li>
<li>An ambivalent or dyadic function receives a path as left argument: this is the home folder of the project</li>
</ul>
<div class="h_tag">
<a href="#make" id="make" class="autoheader_anchor">
<h6 data-id="make">2.2.1.1.6. make</h6>
Expand Down Expand Up @@ -218,6 +223,7 @@ <h6 data-id="watch">2.2.1.2.4. watch</h6>
</div>
<p>Defaults to “both” but can be “ns” or “dir” as well.</p>
<p>Defines which source to track for changes, so the other can be synchronised.</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>
<div class="h_tag">
<a href="#SYSVARS" id="SYSVARS" class="autoheader_anchor">
<h5 data-id="SYSVARS">2.2.1.3. SYSVARS</h5>
Expand Down Expand Up @@ -360,13 +366,12 @@ <h4 data-id="8-Initialising-a-project">2.3.8. 8. Initialising a project (optiona
</div>
<p>Now there might well be demand for executing some code to initialise your project.</p>
<p>This can be achieved by assigning the name of a function to <code>init</code>. This must again be relative to the root of your project.</p>
<p>Notes:</p>
<p>The function should not return a result. If it does anyway it should be shy. Any result would be ignored.</p>
<p>Such a function may be niladic, monadic, ambivalent or dyadic:</p>
<ul>
<li>The function should not return a result. If it does anyway it should be shy. Any result would be ignored.</li>
<li>The function must be either monadic or niladic. If it is monadic then <code>⍬</code> is passed as the right argument.
<p>What is passed as the right argument might well change in a future release.</p></li>
<li>A non-niladic function receives a namespace with the project configuration as right argument</li>
<li>An ambivalent or dyadic function receives a path as left argument: this is the home folder of the project</li>
</ul>
<p>Note that you can access the configuration data of the project from within your initialisation function by questioning the <code>CiderConfig</code> namespace.</p>
<div class="h_tag">
<a href="#9-Executing-user-specific-code" id="9-Executing-user-specific-code" class="autoheader_anchor">
<h4 data-id="9-Executing-user-specific-code">2.3.9. 9. Executing user-specific code</h4>
Expand All @@ -380,7 +385,7 @@ <h4 data-id="9-Executing-user-specific-code">2.3.9. 9. Executing user-specific c
<pre><code>{
ExecuteAfterProjectOpen: "",
}</code></pre>
<p>What is this good for you may ask? Well, let's assume that you are not using Git but a different version control Software. With Git, Cider would execute the “status” command and show the result to the user. With your version control software, it can't do something similar.</p>
<p>What is this good for you may ask? Well, let's assume that you are not using Git but a different version control software. With Git, Cider would execute the “status” command and show the result to the user. With your version control software, it can't do something similar.</p>
<p>You can easily achieve that by yourself: just add the required code to a function you load early into <code>⎕SE</code>, and then make sure that <code>ExecuteAfterProjectOpen</code> is calling that function and you are done.</p>
<div class="h_tag">
<a href="#Misc" id="Misc" class="autoheader_anchor">
Expand Down Expand Up @@ -425,7 +430,7 @@ <h3 data-id="ListTatinPackage">3.1. ListTatinPackage</h3>
<li id="fnref1"><p><em>Tatin</em> is a Dyalog APL package manager: <a href="https://github.com/aplteam/Tatin" class="external_link">https://github.com/aplteam/Tatin</a></p><a href="#fnref1" class="footnote_anchor"></a>
<li id="fnref2"><p><em>LINK</em> is a tool designed to bring APL code into the workspace and keep it in sync with the files the code came from: <a href="https://github.com/dyalog/Link" class="external_link">https://github.com/dyalog/Link</a></p><a href="#fnref2" class="footnote_anchor"></a>
<li id="fnref3"><p>Strictly speaking only references to the packages are injected into your application or tool. The actual packages are loaded into either <code>#._tatin</code> or <code>⎕SE._tatin</code></p><a href="#fnref3" class="footnote_anchor"></a>
<li id="fnref4"><p>At the time of writing (July 2022) this works under Windows but not on other operating systems. However, Dyalog plans to implement this feature on all platforms.</p><a href="#fnref4" class="footnote_anchor"></a>
<li id="fnref4"><p>At the time of writing (July 2022) this works under Windows but not on other operating systems. However, Dyalog plans to implement this feature (or something similar) on all platforms.</p><a href="#fnref4" class="footnote_anchor"></a>
</ol>
</div>
</body>
Expand Down

0 comments on commit bcb8e53

Please sign in to comment.