From: Ben Pfaff <blp@cs.stanford.edu>
Date: Tue, 6 May 2025 15:25:57 +0000 (-0700)
Subject: work on manual
X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=46fc9bf88075f4946fbfb340449ebd7000e93a4b;p=pspp

work on manual
---

diff --git a/rust/doc/src/SUMMARY.md b/rust/doc/src/SUMMARY.md
index d2b7594fc9..a4071ce82d 100644
--- a/rust/doc/src/SUMMARY.md
+++ b/rust/doc/src/SUMMARY.md
@@ -25,6 +25,11 @@
 - [Files Used by PSPP](language/files/index.md)
   - [File Handles](language/files/file-handles.md)
 - [Syntax Diagrams](language/syntax-diagrams.md)
+- [Expressions](language/expressions/index.md)
+  - [Boolean Values](language/expressions/boolean-values.md)
+  - [Missing Values in Expressions](language/expressions/missing-values.md)
+  - [Grouping Operators](language/expressions/grouping.md)
+  - [Arithmetic Operators](language/expressions/arithmetic.md)
 
 # Developer Documentation
 
diff --git a/rust/doc/src/language/expressions/arithmetic.md b/rust/doc/src/language/expressions/arithmetic.md
new file mode 100644
index 0000000000..1f4db7d9a0
--- /dev/null
+++ b/rust/doc/src/language/expressions/arithmetic.md
@@ -0,0 +1,27 @@
+# Arithmetic Operators
+
+The arithmetic operators take numeric operands and produce numeric
+results.
+
+* `A + B`  
+  The sum of `A` and `B`.
+
+* `A - B`  
+  The difference when `B` is subtracted from `A`.
+
+* `A * B`  
+  The product of `A` and `B`.  If either `A` or `B` is 0, then the result is
+  0, even if the other operand is missing.
+
+* `A / B`  
+  The quotient of `A` divided by `B`.  If `A` is 0, then the result is 0,
+  even if `B` is missing.  If `B` is zero, the result is system-missing.
+
+* `A ** B`  
+  Yields the result of raising `A` to the power `B`.  If `A` is
+  negative and `B` is not an integer, the result is system-missing.
+  `0**0` is also system-missing.
+
+* `- A`  
+  Reverses the sign of `A`.
+
diff --git a/rust/doc/src/language/expressions/boolean-values.md b/rust/doc/src/language/expressions/boolean-values.md
new file mode 100644
index 0000000000..11cf592171
--- /dev/null
+++ b/rust/doc/src/language/expressions/boolean-values.md
@@ -0,0 +1,14 @@
+# Boolean Values
+
+Some PSPP operators and expressions work with Boolean values, which
+represent true/false conditions.  Booleans have only three possible
+values: 0 (false), 1 (true), and system-missing (unknown).
+System-missing is neither true nor false and indicates that the true
+value is unknown.
+
+   Boolean-typed operands or function arguments must take on one of
+these three values.  Other values are considered false, but provoke a
+warning when the expression is evaluated.
+
+   Strings and Booleans are not compatible, and neither may be used in
+place of the other.
diff --git a/rust/doc/src/language/expressions/grouping.md b/rust/doc/src/language/expressions/grouping.md
new file mode 100644
index 0000000000..c777321eb6
--- /dev/null
+++ b/rust/doc/src/language/expressions/grouping.md
@@ -0,0 +1,8 @@
+# Grouping Operators
+
+Parentheses (`()`) are the grouping operators.  Surround an expression
+with parentheses to force early evaluation.
+
+   Parentheses also surround the arguments to functions, but in that
+situation they act as punctuators, not as operators.
+
diff --git a/rust/doc/src/language/expressions/index.md b/rust/doc/src/language/expressions/index.md
new file mode 100644
index 0000000000..e764aca3c8
--- /dev/null
+++ b/rust/doc/src/language/expressions/index.md
@@ -0,0 +1,12 @@
+# Mathematical Expressions
+
+Expressions share a common syntax each place they appear in PSPP
+commands.  Expressions are made up of "operands", which can be numbers,
+strings, or variable names, separated by "operators".  There are five
+types of operators: grouping, arithmetic, logical, relational, and
+functions.
+
+   Every operator takes one or more operands as input and yields exactly
+one result as output.  Depending on the operator, operands accept
+strings or numbers as operands.  With few exceptions, operands may be
+full-fledged expressions in themselves.
diff --git a/rust/doc/src/language/expressions/missing-values.md b/rust/doc/src/language/expressions/missing-values.md
new file mode 100644
index 0000000000..6830e403b0
--- /dev/null
+++ b/rust/doc/src/language/expressions/missing-values.md
@@ -0,0 +1,17 @@
+# Missing Values in Expressions
+
+Most numeric operators yield system-missing when given any
+system-missing operand.  A string operator given any system-missing
+operand typically results in the empty string.  Exceptions are listed
+under particular operator descriptions.
+
+   String user-missing values are not treated specially in expressions.
+
+   User-missing values for numeric variables are always transformed into
+the system-missing value, except inside the arguments to the `VALUE` and
+`SYSMIS` functions.
+
+   The missing-value functions can be used to precisely control how
+missing values are treated in expressions.  *Note Missing Value
+Functions::, for more details.
+