Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
| Comment: | Updates to the matrix generator so that it outputs prototype evidence comments for easy cut-and-paste into test cases. Rewrite the CASE section of the SQL expression documentation. |
|---|---|
| Downloads: | Tarball | ZIP archive |
| Timelines: | family | ancestors | descendants | both | trunk |
| Files: | files | file ages | folders |
| SHA1: |
01a939084b7a1b050185e1fb770c287b |
| User & Date: | drh 2009-12-12 18:29:41.000 |
Context
|
2009-12-12
| ||
| 23:58 | Continuing improvements to the SQL language documentation. (check-in: f9931b6e49 user: drh tags: trunk) | |
| 18:29 | Updates to the matrix generator so that it outputs prototype evidence comments for easy cut-and-paste into test cases. Rewrite the CASE section of the SQL expression documentation. (check-in: 01a939084b user: drh tags: trunk) | |
| 15:32 | Fix some requirements markings. Changes the evidence scanner to understand that requirement text that begins with "--" is comment, not actual requirement text. (check-in: 88da6668cb user: drh tags: trunk) | |
Changes
Changes to matrix.tcl.
| ︙ | ︙ | |||
107 108 109 110 111 112 113 114 115 116 117 118 119 120 |
(reqno, reqtext, origtext, reqimage,srcfile,srcseq)
VALUES($reqno,$req, $orig, 1, $srcfile,$seqno);
}
}
}
}
db eval COMMIT
########################################################################
# Header output routine adapted from wrap.tcl. Keep the two in sync.
#
# hd_putsin4 is like puts except that it removes the first 4 indentation
# characters from each line. It also does variable substitution in
# the namespace of its calling procedure.
| > > > > > > > > > > > > > > > > > > | 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 |
(reqno, reqtext, origtext, reqimage,srcfile,srcseq)
VALUES($reqno,$req, $orig, 1, $srcfile,$seqno);
}
}
}
}
db eval COMMIT
set cnt [db one {SELECT count(*) FROM requirement}]
set evcnt [db one {
SELECT count(*) FROM requirement WHERE reqno IN (SELECT reqno FROM evidence)
}]
set evpct [format {%.1f%%} [expr {$evcnt*100.0/$cnt}]]
puts "Found $cnt testable statements. Evidence exists for $evcnt or $evpct"
# Report all evidence for which there is no corresponding requirement.
# Such evidence is probably "stale" - the requirement text has changed but
# the evidence text did not.
#
db eval {
SELECT reqno, srcfile, srcline FROM evidence
WHERE reqno NOT IN (SELECT reqno FROM requirement)
} {
puts "ERROR: stale evidence at $srcfile:$srcline - $reqno"
}
########################################################################
# Header output routine adapted from wrap.tcl. Keep the two in sync.
#
# hd_putsin4 is like puts except that it removes the first 4 indentation
# characters from each line. It also does variable substitution in
# the namespace of its calling procedure.
|
| ︙ | ︙ | |||
207 208 209 210 211 212 213 214 215 216 217 218 219 220 |
}
</style>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
}
puts $fd {</head>}
putsin4 $fd {<body>
<div><!-- container div to satisfy validator -->
<a href="${path}index.html">
<img class="logo" src="${path}images/SQLite.gif" alt="SQLite Logo"
border="0"></a>
<div><!-- IE hack to prevent disappearing logo--></div>
| > > > > > | < < < < < | 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 |
}
</style>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
}
puts $fd {</head>}
if {[file exists DRAFT]} {
set tagline {<font size="6" color="red">*** DRAFT ***</font>}
} else {
set tagline {Small. Fast. Reliable.<br>Choose any three.}
}
putsin4 $fd {<body>
<div><!-- container div to satisfy validator -->
<a href="${path}index.html">
<img class="logo" src="${path}images/SQLite.gif" alt="SQLite Logo"
border="0"></a>
<div><!-- IE hack to prevent disappearing logo--></div>
<div class="tagline">${tagline}</div>
<table width=100% style="clear:both"><tr><td>
<div class="se"><div class="sw"><div class="ne"><div class="nw">
<div class="toolbar">
<a href="${path}about.html">About</a>
<a href="${path}sitemap.html">Sitemap</a>
<a href="${path}docs.html">Documentation</a>
<a href="${path}download.html">Download</a>
<a href="${path}copyright.html">License</a>
<a href="${path}news.html">News</a>
<!-- <a href="${path}dev.html">Developers</a> -->
<a href="${path}support.html">Support</a>
</div></div></div></div></div>
</td></tr></table>
}
}
# End of code copied out of wrap.tcl
##############################################################################
# Generate the requirements traceability matrix.
#
puts "Generating requirements matrix..."
|
| ︙ | ︙ | |||
282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 |
}
regsub -all {[^a-zA-Z0-9]} [file tail [file root $srcfile]] _ docid
puts $out "<td><a href=\"matrix_s$docid.html\">summary</a></td>"
puts $out "<td><a href=\"matrix_d$docid.html\">details</a></td></tr>\n"
}
puts $out </table>
close $out
# Detail matrixes for each document.
#
foreach srcfile $srclist {
regsub -all {[^a-zA-Z0-9]} [file tail [file root $srcfile]] _ docid
set fn matrix_d$docid.html
set matrixname($srcfile) $fn
set out [open doc/matrix/$fn w]
regsub {^doc/} $srcfile {} basename
write_header ../ $out "SQLite Requirement Matrix: [file tail $srcfile]"
puts $out "<h1 align=center>SQLite Requirement Matrix Details<br>"
puts $out "[file tail $srcfile]</h1>"
puts $out "<h2><a href=\"matrix.html\">Index</a>"
| > > > > > > > > > > > > > > > > > | | > | | | 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 |
}
regsub -all {[^a-zA-Z0-9]} [file tail [file root $srcfile]] _ docid
puts $out "<td><a href=\"matrix_s$docid.html\">summary</a></td>"
puts $out "<td><a href=\"matrix_d$docid.html\">details</a></td></tr>\n"
}
puts $out </table>
close $out
# Split a long string of text at spaces so that no line exceeds 70
# characters. Send the result to $out.
#
proc wrap_in_comment {out prefix txt} {
while {[string length $txt]>70} {
set break [string last { } $txt 70]
if {$break == 0} {
set break [string first { } $txt]
}
puts $out "$prefix [string range $txt 0 [expr {$break-1}]]"
set txt [string trim [string range $txt $break end]]
}
puts $out "$prefix $txt"
}
# Detail matrixes for each document.
#
foreach srcfile $srclist {
regsub -all {[^a-zA-Z0-9]} [file tail [file root $srcfile]] _ docid
set fn matrix_d$docid.html
set matrixname($srcfile) $fn
set out [open doc/matrix/$fn w]
regsub {^doc/} $srcfile {} basename
write_header ../ $out "SQLite Requirement Matrix: [file tail $srcfile]"
puts $out "<h1 align=center>SQLite Requirement Matrix Details<br>"
puts $out "[file tail $srcfile]</h1>"
puts $out "<h2><a href=\"matrix.html\">Index</a>"
puts $out "<a href=\"matrix_s$docid.html\">Summary</a>"
puts $out "<a href=\"$basename\">Markup</a>"
puts $out "<a href=\"../$basename\">Original</a></h2>"
db eval {
SELECT reqno, reqimage, origtext, reqtext
FROM requirement
WHERE srcfile=$srcfile
ORDER BY srcseq
} {
puts $out "<hr><a name=\"$reqno\"></a>"
puts $out "<p><a href=\"$basename#$reqno\">$reqno</a>"
set ev(tcl) 0
set ev(th3) 0
set ev(src) 0
db eval {
SELECT count(*) AS cnt, srcclass
|
| ︙ | ︙ | |||
329 330 331 332 333 334 335 |
set cx evok
incr proof($reqno)
} else {
set cx evnil
}
puts $out "<cite class=$cx>$srcclass</cite>"
}
| | | > > > > > > > > > | > > | | > | 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 |
set cx evok
incr proof($reqno)
} else {
set cx evnil
}
puts $out "<cite class=$cx>$srcclass</cite>"
}
puts $out "</p>"
puts $out "<p>$origtext</p>"
set sep <p>
db eval {
SELECT srccat || '/' || srcfile || ':' || srcline AS x, url
FROM evidence
WHERE reqno=$reqno
ORDER BY x;
} {
if {$url!=""} {
puts $out "$sep<a href=\"$url\">$x</a>"
} else {
puts $out "$sep$x"
}
set sep " "
}
# Generate text suitable for copy-paste into source documents as
# evidence that the requirement is satisfied.
#
set abbrev [string range $reqno 0 12]
puts $out "<pre>/* IMP: $abbrev */</pre>"
if {[regexp {^syntax diagram } $reqtext]} {
puts $out "<pre># EVIDENCE-OF: $abbrev -- $reqtext</pre>"
} else {
puts $out "<pre>"
wrap_in_comment $out # "EVIDENCE-OF: $abbrev $reqtext"
puts $out "</pre>"
}
}
close $out
}
# Summary matrixes for each document.
#
foreach srcfile $srclist {
set has_req($srcfile) 1
|
| ︙ | ︙ |
Changes to pages/lang.in.
| ︙ | ︙ | |||
1445 1446 1447 1448 1449 1450 1451 | <p>^(The BETWEEN operator is equivalent to a pair of comparisons. "<i>a</i> <b>BETWEEN</b> <i>b</i> <b>AND</b> <i>c</i>" is equivalent to "<i>a</i><b>>=</b><i>b</i> <b>AND</b> <i>a</i><b><=</b><i>c</i>".)^ ^The precedence of the BETWEEN operator is the same as the precedence as operators <b>==</b> and <b>!=</b> and <b>LIKE</b> and groups left to right. | | | | < < < | < | < < < | | > > | | < | > | | > > > | | | | | > > > > | | | | | > | | 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 |
<p>^(The BETWEEN operator is equivalent to a pair of comparisons.
"<i>a</i> <b>BETWEEN</b> <i>b</i> <b>AND</b> <i>c</i>" is
equivalent to
"<i>a</i><b>>=</b><i>b</i> <b>AND</b> <i>a</i><b><=</b><i>c</i>".)^
^The precedence of the BETWEEN operator is the same as the precedence
as operators <b>==</b> and <b>!=</b> and <b>LIKE</b> and groups left to right.
<tcl>hd_fragment case {CASE expression}</tcl>
<h3>The CASE expression</h3>
<p>A CASE expression serves a role similar to IF-THEN-ELSE in other
programming languages. ^WHEN expressions are evaluated from left to
right until one is found that is true and the corresponding THEN term
becomes the result. ^If no WHEN expression is true then the ELSE
clause determines the result or the result is NULL if there is no ELSE clase.
</p>
<p>The optional expression that occurs in between the CASE keyword and the
first WHEN keyword is the "base" expression. ^There are two basic forms
of a CASE expression: those with and without a base expression.
^In a CASE without a base expression, each WHEN expression is evaluted
as a boolean and the overall result is determined by first WHEN expression
that is true.
^In a CASE with a base expression, the base expression is evaluted just
once and the result is compared against each WHEN expression until a
match is found.
^When comparing a base expression against a WHEN expression, the same
collating sequence, affinity, and NULL-handling rules apply as if the
base expression and WHEN expression are respectively the left- and
right-hand operands of an <big><b>=</b></big> operator.</p>
<p>^(Assuming the subexpressions have no side-effects, the following
two expressions are equivalent:</p>
<ul>
<li>CASE x WHEN w1 THEN r1 WHEN w2 THEN r2 ELSE r3 END
<li>CASE WHEN x=w1 THEN r1 WHEN x=w2 THEN r2 ELSE r3 END
</ul>)^
<p>^The only difference between the two CASE expressions shown above
is that the <i>x</i> expression is evaluated
exactly once in the first example but might be evaluated multiple times
in the second.</p>
<p>^A NULL result is considered false when evaluating WHEN terms.
^If the base expression is NULL then the result of the CASE is the
result of the ELSE expression if it exists, or NULL if the ELSE clause
is omitted.</p>
<h3>Table Column Names</h3>
<p>^A column name can be any of the names defined in the [CREATE TABLE]
statement or one of the following special identifiers: "<b>ROWID</b>",
|
| ︙ | ︙ |