-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathspadstyleguide.html
268 lines (259 loc) · 13.5 KB
/
spadstyleguide.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>SPAD Style Guide — FriCAS</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="_static/classic.css?v=514cf933" />
<link rel="stylesheet" href="_static/style.css" type="text/css" />
<script src="_static/documentation_options.js?v=a44cb687"></script>
<script src="_static/doctools.js?v=888ff710"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Contributors" href="contributors.html" />
<link rel="prev" title="Development" href="development.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="contributors.html" title="Contributors"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="development.html" title="Development"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">FriCAS</a> »</li>
<li class="nav-item nav-item-1"><a href="development.html" accesskey="U">Development</a> »</li>
<li class="nav-item nav-item-this"><a href="">SPAD Style Guide</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="spad-style-guide">
<h1>SPAD Style Guide<a class="headerlink" href="#spad-style-guide" title="Link to this heading">¶</a></h1>
<section id="maximum-line-length">
<h2>Maximum line length<a class="headerlink" href="#maximum-line-length" title="Link to this heading">¶</a></h2>
<p>No firm rule, but use about 70 characters unless that causes problems.
Try to avoid lines longer than 78 characters.</p>
</section>
<section id="file-splitting-during-compilation">
<h2>File splitting during compilation<a class="headerlink" href="#file-splitting-during-compilation" title="Link to this heading">¶</a></h2>
<p>There is a script <a class="reference external" href="https://github.com/fricas/fricas/blob/master/src/scripts/unpack_file">src/scripts/unpack_file</a> that splits
<code class="docutils literal notranslate"><span class="pre">.spad</span></code> source files at <code class="docutils literal notranslate"><span class="pre">)abbrev</span></code> boundaries. As a result,
everything before the first <code class="docutils literal notranslate"><span class="pre">)abbrev</span></code> will be discarded.</p>
<p>In particular, it means that there cannot be a global macro definition
for the whole <code class="docutils literal notranslate"><span class="pre">.spad</span></code> file.</p>
</section>
<section id="literate-documentation">
<h2>Literate documentation<a class="headerlink" href="#literate-documentation" title="Link to this heading">¶</a></h2>
<p><a class="reference external" href="http://wiki.fricas.org/ProgrammingSPAD">SPAD</a> files can contain LaTeX parts.
Such documentation must be included into blocks of the form:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>)if LiterateDoc
...
)endif
</pre></div>
</div>
<p>These parts must form a proper LaTeX document. The code parts are
included and typeset via the
<a class="reference external" href="https://www.ctan.org/pkg/listings/">listings package</a>.</p>
<p>To support a weak form of literate programming, the two files</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/fricas/fricas/blob/master/src/doc/literatedoc.sty">src/doc/literatedoc.sty</a></p></li>
<li><p><a class="reference external" href="https://github.com/fricas/fricas/blob/master/src/doc/literatedoc.awk">src/doc/literatedoc.awk</a></p></li>
</ul>
<p>are provided.</p>
<p>The file <a class="reference external" href="https://github.com/fricas/fricas/blob/master/src/algebra/fmt.spad">fmt.spad</a> can be taken as an example.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd fricas
awk -f src/doc/literatedoc.awk src/algebra/fmt.spad > fmt.tex
TEXINPUTS=:src/doc pdflatex fmt.tex
</pre></div>
</div>
</section>
<section id="whitespace">
<h2>Whitespace<a class="headerlink" href="#whitespace" title="Link to this heading">¶</a></h2>
<p>Do not use tabs, but rather explicit spaces.</p>
<section id="block-indentation">
<h3>Block indentation<a class="headerlink" href="#block-indentation" title="Link to this heading">¶</a></h3>
<p>4 spaces (no tabs)</p>
</section>
<section id="whitespaces-around-punctuation">
<h3>Whitespaces around punctuation<a class="headerlink" href="#whitespaces-around-punctuation" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p>“:” space before and after</p></li>
<li><p>“,” space after (but not before)</p></li>
<li><p>“;” space after (but not before)</p></li>
<li><p>‘+’ spaces optional for most arithmetic infix operations</p></li>
<li><p>“-” no space after for unary operations</p></li>
</ul>
</section>
</section>
<section id="continuation-lines">
<h2>Continuation lines<a class="headerlink" href="#continuation-lines" title="Link to this heading">¶</a></h2>
<p>Use explicit <code class="docutils literal notranslate"><span class="pre">_</span></code> (underscore) even when not required</p>
</section>
<section id="function-signature">
<h2>Function signature<a class="headerlink" href="#function-signature" title="Link to this heading">¶</a></h2>
<p>Use explicit types, that is:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>func(a : Integer) : Integer ==
</pre></div>
</div>
<p>rather than:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>func(a) ==
</pre></div>
</div>
</section>
<section id="empty-list">
<h2>Empty list<a class="headerlink" href="#empty-list" title="Link to this heading">¶</a></h2>
<p>use []$T rather than empty()$T</p>
</section>
<section id="early-exit">
<h2>=> (early exit)<a class="headerlink" href="#early-exit" title="Link to this heading">¶</a></h2>
<p>The ternary operator <code class="docutils literal notranslate"><span class="pre">cond</span> <span class="pre">?</span> <span class="pre">a</span> <span class="pre">:</span> <span class="pre">b</span></code> known from the C programming
language can be encoded in SPAD as follows.</p>
<p>Either:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>e := (v > 0 => 1; -1)
</pre></div>
</div>
<p>or:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>e := if v > 0 then 1 else -1
</pre></div>
</div>
</section>
<section id="dangling-else">
<h2>Dangling <code class="docutils literal notranslate"><span class="pre">else</span></code><a class="headerlink" href="#dangling-else" title="Link to this heading">¶</a></h2>
<p>If there is space then the best option is all on one line</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>if .... then .... else ....
</pre></div>
</div>
<p>Otherwise it should be like this</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>if ... then
...
else
...
</pre></div>
</div>
</section>
<section id="elt-vs-qelt">
<h2>elt vs. qelt<a class="headerlink" href="#elt-vs-qelt" title="Link to this heading">¶</a></h2>
<p>We encourage better error messages over speed, i.e., use <code class="docutils literal notranslate"><span class="pre">elt</span></code>.
<code class="docutils literal notranslate"><span class="pre">qelt</span></code> should only be used in cases where it is clear from the
context that no index error can happen.</p>
</section>
<section id="vs">
<h2>_+ vs. “+”<a class="headerlink" href="#vs" title="Link to this heading">¶</a></h2>
<p>Prefer the escaped version of an operator instead of letting it look
like a string, i.e. use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>_+(a : %, b : %) : Boolean ==
</pre></div>
</div>
<p>instead of</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>"+"(a : %, b : %) : Boolean ==
</pre></div>
</div>
</section>
<section id="boolean-valued-functions">
<h2>Boolean valued functions<a class="headerlink" href="#boolean-valued-functions" title="Link to this heading">¶</a></h2>
<p>Functions that return boolean values have names that end in <code class="docutils literal notranslate"><span class="pre">?</span></code>.
Define:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>positive? : Integer -> Boolean
</pre></div>
</div>
<p>instead of:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>isPositive : Integer -> Boolean
</pre></div>
</div>
</section>
<section id="destructive-operations">
<h2>Destructive operations<a class="headerlink" href="#destructive-operations" title="Link to this heading">¶</a></h2>
<p>Identifiers of functions that modify their arguments should be ended
with an exclamation mark (<code class="docutils literal notranslate"><span class="pre">!</span></code>) to remind other programmers that they
should be very careful in using such functions.</p>
<p>Compare <code class="docutils literal notranslate"><span class="pre">reverse</span></code> with <code class="docutils literal notranslate"><span class="pre">reverse!</span></code>.</p>
</section>
<section id="non-public-constructors">
<h2>Non-public constructors<a class="headerlink" href="#non-public-constructors" title="Link to this heading">¶</a></h2>
<p>Constructors starting with “Inner” are meant for library developers
but not for end-users.</p>
</section>
<section id="calling-unary-functions">
<h2>Calling unary functions<a class="headerlink" href="#calling-unary-functions" title="Link to this heading">¶</a></h2>
<p>Use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>foo arg
</pre></div>
</div>
<p>instead of</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>foo(arg)
</pre></div>
</div>
<p>for unary functions if the argument is simple.</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="api/index.html">FriCAS API</a></li>
<li class="toctree-l1"><a class="reference internal" href="features.html">Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="download.html">Download</a></li>
<li class="toctree-l1"><a class="reference internal" href="help.html">Help</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="development.html">Development</a></li>
<li class="toctree-l1"><a class="reference internal" href="citation.html">Citation</a></li>
<li class="toctree-l1"><a class="reference internal" href="history.html">History</a></li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/spadstyleguide.rst.txt"
rel="nofollow">Show Source</a></li>
<li><a href="https://github.com/fricas/fricas/blob/master/src/doc/sphinx/source/spadstyleguide.rst"
rel="nofollow">Show on GitHub</a></li>
<li><a href="https://github.com/fricas/fricas/edit/master/src/doc/sphinx/source/spadstyleguide.rst"
rel="nofollow">Edit on GitHub</a></li>
</ul>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="contributors.html" title="Contributors"
>next</a> |</li>
<li class="right" >
<a href="development.html" title="Development"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">FriCAS</a> »</li>
<li class="nav-item nav-item-1"><a href="development.html" >Development</a> »</li>
<li class="nav-item nav-item-this"><a href="">SPAD Style Guide</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2007-2024, FriCAS Team.
</div>
</body>
</html>