Merge pull request #504 from Alex-Fischman/readme

Move README docs into documentation

README.md

@@ -93,66 +93,3 @@ env RUST_LOG=error samply record ./target/profiling/egglog --dont-print-messages
 
 To view documentation, run `cargo doc --open`.
 
-
-
-TODO migrate the following documentation to cargo doc:
-### Sort: i64
-
-Signed 64-bit integers supporting these primitives:
-
-```
-+ - * / %           ; arithmetic
-& | ^ << >> not-i64 ; bit-wise operations
-< > <= >=           ; comparisons
-min max log2
-to-f64
-to-string
-```
-
-### Sort: f64
-
-64-bit floating point numbers supporting these primitives:
-
-```
-+ - * / %           ; arithmetic
-< > <= >=           ; comparisons
-min max neg
-to-i64
-to-string
-```
-
-### Sort: map
-
-A map from a key type to a value type supporting these primitives:
-
-```
-empty
-insert
-get
-not-contains
-contains
-set-union
-set-diff
-set-intersect
-map-remove
-```
-
-### Sort: rational
-
-Rational numbers (fractions) with 64-bit precision for numerator and denominator with these primitives:
-
-```
-+ - * /         ; arithmetic
-min max neg abs floor ceil round
-rational        ; construct from a numerator and denominator
-numer denom     ; get numerator and denominator
-pow log sqrt
-< > <= >=       ; comparisons
-```
-
-These primitives are only defined when the result itself is a pure rational.
-
-### Sort: string
-
-Use double quotes to get a quote: `"Foo "" Bar"` is `Foo " Bar`.
-No primitives defined.

src/sort/bigrat.rs

@@ -13,6 +13,13 @@ lazy_static! {
     static ref RATS: Mutex<IndexSet<Q>> = Default::default();
 }
 
+/// Rational numbers supporting these primitives:
+/// - Arithmetic: `+`, `-`, `*`, `/`, `neg`, `abs`
+/// - Exponential: `pow`, `log`, `sqrt`, `cbrt`
+/// - Rounding: `floor`, `ceil`, `round`
+/// - Con/Destruction: `bigrat`, `numer`, `denom`
+/// - Comparisons: `<`, `>`, `<=`, `>=`
+/// - Other: `min`, `max`, `to-f64`
 #[derive(Debug)]
 pub struct BigRatSort;
 
@@ -41,10 +48,10 @@ impl Sort for BigRatSort {
         add_primitives!(eg, "floor" = |a: Q| -> Q { a.floor() });
         add_primitives!(eg, "ceil" = |a: Q| -> Q { a.ceil() });
         add_primitives!(eg, "round" = |a: Q| -> Q { a.round() });
+
         add_primitives!(eg, "bigrat" = |a: Z, b: Z| -> Q { Q::new(a, b) });
         add_primitives!(eg, "numer" = |a: Q| -> Z { a.numer().clone() });
         add_primitives!(eg, "denom" = |a: Q| -> Z { a.denom().clone() });
-
         add_primitives!(eg, "to-f64" = |a: Q| -> f64 { a.to_f64().unwrap() });
 
         add_primitives!(eg, "pow" = |a: Q, b: Q| -> Option<Q> {

src/sort/f64.rs

@@ -2,6 +2,10 @@ use super::*;
 use crate::ast::Literal;
 use ordered_float::OrderedFloat;
 
+/// 64-bit floating point numbers supporting these primitives:
+/// - Arithmetic: `+`, `-`, `*`, `/`, `%`, `^`, `neg`, `abs`
+/// - Comparisons: `<`, `>`, `<=`, `>=`
+/// - Other: `min`, `max`, `to-i64`, `to-string`
 #[derive(Debug)]
 pub struct F64Sort;
 
@@ -25,14 +29,13 @@ impl Sort for F64Sort {
     fn register_primitives(self: Arc<Self>, eg: &mut TypeInfo) {
         type Opt<T=()> = Option<T>;
 
-        add_primitives!(eg, "neg" = |a: f64| -> f64 { -a });
-
         add_primitives!(eg, "+" = |a: f64, b: f64| -> f64 { a + b });
         add_primitives!(eg, "-" = |a: f64, b: f64| -> f64 { a - b });
         add_primitives!(eg, "*" = |a: f64, b: f64| -> f64 { a * b });
-        add_primitives!(eg, "^" = |a: f64, b: f64| -> f64 { a.powf(b) });
         add_primitives!(eg, "/" = |a: f64, b: f64| -> Opt<f64> { (b != 0.0).then(|| a / b) });
         add_primitives!(eg, "%" = |a: f64, b: f64| -> Opt<f64> { (b != 0.0).then(|| a % b) });
+        add_primitives!(eg, "^" = |a: f64, b: f64| -> f64 { a.powf(b) });
+        add_primitives!(eg, "neg" = |a: f64| -> f64 { -a });
 
         add_primitives!(eg, "<" = |a: f64, b: f64| -> Opt { (a < b).then(|| ()) });
         add_primitives!(eg, ">" = |a: f64, b: f64| -> Opt { (a > b).then(|| ()) });
@@ -43,11 +46,11 @@ impl Sort for F64Sort {
         add_primitives!(eg, "max" = |a: f64, b: f64| -> f64 { a.max(b) });
         add_primitives!(eg, "abs" = |a: f64| -> f64 { a.abs() });
 
+        // `to-f64` should be in `i64.rs`, but `F64Sort` wouldn't exist yet
         add_primitives!(eg, "to-f64" = |a: i64| -> f64 { a as f64 });
         add_primitives!(eg, "to-i64" = |a: f64| -> i64 { a as i64 });
         // Use debug instead of to_string so that decimal place is always printed
         add_primitives!(eg, "to-string" = |a: f64| -> Symbol { format!("{:?}", a).into() });
-
     }
 
     fn extract_term(

src/sort/i64.rs

@@ -2,6 +2,20 @@ use crate::{ast::Literal, constraint::AllEqualTypeConstraint};
 
 use super::*;
 
+/// Signed 64-bit integers supporting these primitives:
+/// - Arithmetic: `+`, `-`, `*`, `/`, `%`
+/// - Bitwise: `&`, `|`, `^`, `<<`, `>>`, `not-i64`
+/// - Fallible comparisons: `<`, `>`, `<=`, `>=`
+/// - Boolean comparisons: `bool-=`, `bool-<`, `bool->`, `bool-<=`, `bool->=`
+/// - Other: `min`, `max`, `to-f64`, `to-string`, `log2`
+///
+/// Note: fallible comparisons are used at the top-level of a query.
+/// For example, this rule will only match if `a` is less than `b`.
+/// ```text
+/// (rule (... (< a b)) (...))
+/// ```
+/// On the other hand, boolean comparisons will always match, and so
+/// make sense to use inside expressions.
 #[derive(Debug)]
 pub struct I64Sort;
 

src/sort/map.rs

@@ -7,6 +7,14 @@ use super::*;
 
 type ValueMap = BTreeMap<Value, Value>;
 
+/// A map from a key type to a value type supporting these primitives:
+/// - `map-empty`
+/// - `map-insert`
+/// - `map-get`
+/// - `map-contains`
+/// - `map-not-contains`
+/// - `map-remove`
+/// - `map-length`
 #[derive(Debug)]
 pub struct MapSort {
     name: Symbol,