-----------------------------------------------------------------------------

-----------------------------------------------------------------------------

-- SPDX-License-Identifier: BSD-3-Clause

-- |
-- Module      :  Disco.Doc
-- Copyright   :  disco team and contributors
-- Maintainer  :  byorgey@gmail.com
--
-- Built-in documentation.
module Disco.Doc (
  primDoc,
  primReference,
  otherDoc,
  otherReference,
) where

import Data.Map (Map)
import qualified Data.Map as M

import Disco.Syntax.Operators
import Disco.Syntax.Prims
import Disco.Util ((==>))

-- | A map from some primitives to a short descriptive string,
--   to be shown by the :doc command.
primDoc :: Map Prim String
primDoc :: Map Prim String
primDoc =
  forall k a. Ord k => [(k, a)] -> Map k a
M.fromList
    [ UOp -> Prim
PrimUOp UOp
Neg forall a b. a -> b -> (a, b)
==> String
"Arithmetic negation."
    , BOp -> Prim
PrimBOp BOp
Add forall a b. a -> b -> (a, b)
==> String
"The sum of two numbers, types, or graphs."
    , BOp -> Prim
PrimBOp BOp
Sub forall a b. a -> b -> (a, b)
==> String
"The difference of two numbers."
    , BOp -> Prim
PrimBOp BOp
SSub forall a b. a -> b -> (a, b)
==> String
"The difference of two numbers, with a lower bound of 0."
    , BOp -> Prim
PrimBOp BOp
Mul forall a b. a -> b -> (a, b)
==> String
"The product of two numbers, types, or graphs."
    , BOp -> Prim
PrimBOp BOp
Div forall a b. a -> b -> (a, b)
==> String
"Divide two numbers."
    , BOp -> Prim
PrimBOp BOp
IDiv forall a b. a -> b -> (a, b)
==> String
"The integer quotient of two numbers, rounded down."
    , BOp -> Prim
PrimBOp BOp
Mod forall a b. a -> b -> (a, b)
==> String
"a mod b is the remainder when a is divided by b."
    , BOp -> Prim
PrimBOp BOp
Exp forall a b. a -> b -> (a, b)
==> String
"Exponentiation.  a ^ b is a raised to the b power."
    , UOp -> Prim
PrimUOp UOp
Fact forall a b. a -> b -> (a, b)
==> String
"n! computes the factorial of n, that is, 1 * 2 * ... * n."
    , Prim
PrimFloor forall a b. a -> b -> (a, b)
==> String
"floor(x) is the largest integer which is <= x."
    , Prim
PrimCeil forall a b. a -> b -> (a, b)
==> String
"ceiling(x) is the smallest integer which is >= x."
    , Prim
PrimAbs forall a b. a -> b -> (a, b)
==> String
"abs(x) is the absolute value of x.  Also written |x|."
    , UOp -> Prim
PrimUOp UOp
Not forall a b. a -> b -> (a, b)
==> String
"Logical negation: not(true) = false and not(false) = true."
    , BOp -> Prim
PrimBOp BOp
And forall a b. a -> b -> (a, b)
==> String
"Logical conjunction (and): true /\\ true = true; otherwise x /\\ y = false."
    , BOp -> Prim
PrimBOp BOp
Or forall a b. a -> b -> (a, b)
==> String
"Logical disjunction (or): false \\/ false = false; otherwise x \\/ y = true."
    , BOp -> Prim
PrimBOp BOp
Impl forall a b. a -> b -> (a, b)
==> String
"Logical implication (implies): true -> false = false; otherwise x -> y = true."
    , BOp -> Prim
PrimBOp BOp
Iff forall a b. a -> b -> (a, b)
==> String
"Biconditional (if and only if)."
    , BOp -> Prim
PrimBOp BOp
Eq forall a b. a -> b -> (a, b)
==> String
"Equality test.  x == y is true if x and y are equal."
    , BOp -> Prim
PrimBOp BOp
Neq forall a b. a -> b -> (a, b)
==> String
"Inequality test.  x /= y is true if x and y are unequal."
    , BOp -> Prim
PrimBOp BOp
Lt forall a b. a -> b -> (a, b)
==> String
"Less-than test. x < y is true if x is less than (but not equal to) y."
    , BOp -> Prim
PrimBOp BOp
Gt forall a b. a -> b -> (a, b)
==> String
"Greater-than test. x > y is true if x is greater than (but not equal to) y."
    , BOp -> Prim
PrimBOp BOp
Leq forall a b. a -> b -> (a, b)
==> String
"Less-than-or-equal test. x <= y is true if x is less than or equal to y."
    , BOp -> Prim
PrimBOp BOp
Geq forall a b. a -> b -> (a, b)
==> String
"Greater-than-or-equal test. x >= y is true if x is greater than or equal to y."
    , BOp -> Prim
PrimBOp BOp
CartProd forall a b. a -> b -> (a, b)
==> String
"Cartesian product, i.e. the collection of all pairs.  Also works on bags and sets."
    , Prim
PrimPower forall a b. a -> b -> (a, b)
==> String
"Power set, i.e. the set of all subsets.  Also works on bags."
    , BOp -> Prim
PrimBOp BOp
Union forall a b. a -> b -> (a, b)
==> String
"Union of two sets (or bags)."
    , BOp -> Prim
PrimBOp BOp
Inter forall a b. a -> b -> (a, b)
==> String
"Intersection of two sets (or bags)."
    , BOp -> Prim
PrimBOp BOp
Diff forall a b. a -> b -> (a, b)
==> String
"Difference of two sets (or bags)."
    ]

-- | A map from some primitives to their corresponding page in the
--   Disco language reference
--   (https://disco-lang.readthedocs.io/en/latest/reference/index.html).
primReference :: Map Prim String
primReference :: Map Prim String
primReference =
  forall k a. Ord k => [(k, a)] -> Map k a
M.fromList
    [ BOp -> Prim
PrimBOp BOp
Add forall a b. a -> b -> (a, b)
==> String
"addition"
    , BOp -> Prim
PrimBOp BOp
Sub forall a b. a -> b -> (a, b)
==> String
"subtraction"
    , BOp -> Prim
PrimBOp BOp
SSub forall a b. a -> b -> (a, b)
==> String
"subtraction"
    , BOp -> Prim
PrimBOp BOp
Mul forall a b. a -> b -> (a, b)
==> String
"multiplication"
    , BOp -> Prim
PrimBOp BOp
Div forall a b. a -> b -> (a, b)
==> String
"division"
    , BOp -> Prim
PrimBOp BOp
IDiv forall a b. a -> b -> (a, b)
==> String
"integerdiv"
    , BOp -> Prim
PrimBOp BOp
Mod forall a b. a -> b -> (a, b)
==> String
"mod"
    , BOp -> Prim
PrimBOp BOp
Exp forall a b. a -> b -> (a, b)
==> String
"exponentiation"
    , UOp -> Prim
PrimUOp UOp
Fact forall a b. a -> b -> (a, b)
==> String
"factorial"
    , Prim
PrimFloor forall a b. a -> b -> (a, b)
==> String
"round"
    , Prim
PrimCeil forall a b. a -> b -> (a, b)
==> String
"round"
    , Prim
PrimAbs forall a b. a -> b -> (a, b)
==> String
"abs"
    , UOp -> Prim
PrimUOp UOp
Not forall a b. a -> b -> (a, b)
==> String
"logic-ops"
    , BOp -> Prim
PrimBOp BOp
And forall a b. a -> b -> (a, b)
==> String
"logic-ops"
    , BOp -> Prim
PrimBOp BOp
Or forall a b. a -> b -> (a, b)
==> String
"logic-ops"
    , BOp -> Prim
PrimBOp BOp
Impl forall a b. a -> b -> (a, b)
==> String
"logic-ops"
    , BOp -> Prim
PrimBOp BOp
Iff forall a b. a -> b -> (a, b)
==> String
"logic-ops"
    , BOp -> Prim
PrimBOp BOp
CartProd forall a b. a -> b -> (a, b)
==> String
"cp"
    , Prim
PrimPower forall a b. a -> b -> (a, b)
==> String
"power"
    , BOp -> Prim
PrimBOp BOp
Union forall a b. a -> b -> (a, b)
==> String
"set-ops"
    , BOp -> Prim
PrimBOp BOp
Inter forall a b. a -> b -> (a, b)
==> String
"set-ops"
    , BOp -> Prim
PrimBOp BOp
Diff forall a b. a -> b -> (a, b)
==> String
"set-ops"
    , BOp -> Prim
PrimBOp BOp
Eq forall a b. a -> b -> (a, b)
==> String
"compare"
    , BOp -> Prim
PrimBOp BOp
Neq forall a b. a -> b -> (a, b)
==> String
"compare"
    , BOp -> Prim
PrimBOp BOp
Lt forall a b. a -> b -> (a, b)
==> String
"compare"
    , BOp -> Prim
PrimBOp BOp
Gt forall a b. a -> b -> (a, b)
==> String
"compare"
    , BOp -> Prim
PrimBOp BOp
Leq forall a b. a -> b -> (a, b)
==> String
"compare"
    , BOp -> Prim
PrimBOp BOp
Geq forall a b. a -> b -> (a, b)
==> String
"compare"
    ]

otherDoc :: Map String String
otherDoc :: Map String String
otherDoc =
  forall k a. Ord k => [(k, a)] -> Map k a
M.fromList
    [ String
"N" forall a b. a -> b -> (a, b)
==> String
docN
    , String
"ℕ" forall a b. a -> b -> (a, b)
==> String
docN
    , String
"Nat" forall a b. a -> b -> (a, b)
==> String
docN
    , String
"Natural" forall a b. a -> b -> (a, b)
==> String
docN
    , String
"Z" forall a b. a -> b -> (a, b)
==> String
docZ
    , String
"ℤ" forall a b. a -> b -> (a, b)
==> String
docZ
    , String
"Int" forall a b. a -> b -> (a, b)
==> String
docZ
    , String
"Integer" forall a b. a -> b -> (a, b)
==> String
docZ
    , String
"F" forall a b. a -> b -> (a, b)
==> String
docF
    , String
"𝔽" forall a b. a -> b -> (a, b)
==> String
docF
    , String
"Frac" forall a b. a -> b -> (a, b)
==> String
docF
    , String
"Fractional" forall a b. a -> b -> (a, b)
==> String
docF
    , String
"Q" forall a b. a -> b -> (a, b)
==> String
docQ
    , String
"ℚ" forall a b. a -> b -> (a, b)
==> String
docQ
    , String
"Rational" forall a b. a -> b -> (a, b)
==> String
docQ
    , String
"Bool" forall a b. a -> b -> (a, b)
==> String
docB
    , String
"Boolean" forall a b. a -> b -> (a, b)
==> String
docB
    , String
"Unit" forall a b. a -> b -> (a, b)
==> String
"The unit type, i.e. a type with only a single value."
    , String
"Prop" forall a b. a -> b -> (a, b)
==> String
"The type of propositions."
    , String
"Set" forall a b. a -> b -> (a, b)
==> String
"The type of finite sets."
    , String
"|~|" forall a b. a -> b -> (a, b)
==> String
"Absolute value, or the size of a collection."
    , String
"{?" forall a b. a -> b -> (a, b)
==> String
"{? ... ?} is a case expression, for choosing a result based on conditions."
    ]
 where
  docN :: String
docN = String
"The type of natural numbers: 0, 1, 2, ..."
  docZ :: String
docZ = String
"The type of integers: ..., -2, -1, 0, 1, 2, ..."
  docF :: String
docF = String
"The type of fractional numbers p/q >= 0."
  docQ :: String
docQ = String
"The type of rational numbers p/q."
  docB :: String
docB = String
"The type of Booleans (true or false)."

otherReference :: Map String String
otherReference :: Map String String
otherReference =
  forall k a. Ord k => [(k, a)] -> Map k a
M.fromList
    [ String
"N" forall a b. a -> b -> (a, b)
==> String
"natural"
    , String
"ℕ" forall a b. a -> b -> (a, b)
==> String
"natural"
    , String
"Nat" forall a b. a -> b -> (a, b)
==> String
"natural"
    , String
"Natural" forall a b. a -> b -> (a, b)
==> String
"natural"
    , String
"Z" forall a b. a -> b -> (a, b)
==> String
"integer"
    , String
"ℤ" forall a b. a -> b -> (a, b)
==> String
"integer"
    , String
"Int" forall a b. a -> b -> (a, b)
==> String
"integer"
    , String
"Integer" forall a b. a -> b -> (a, b)
==> String
"integer"
    , String
"F" forall a b. a -> b -> (a, b)
==> String
"fraction"
    , String
"𝔽" forall a b. a -> b -> (a, b)
==> String
"fraction"
    , String
"Frac" forall a b. a -> b -> (a, b)
==> String
"fraction"
    , String
"Fractional" forall a b. a -> b -> (a, b)
==> String
"fraction"
    , String
"Q" forall a b. a -> b -> (a, b)
==> String
"rational"
    , String
"ℚ" forall a b. a -> b -> (a, b)
==> String
"rational"
    , String
"Rational" forall a b. a -> b -> (a, b)
==> String
"rational"
    , String
"Bool" forall a b. a -> b -> (a, b)
==> String
"bool"
    , String
"Boolean" forall a b. a -> b -> (a, b)
==> String
"bool"
    , String
"Unit" forall a b. a -> b -> (a, b)
==> String
"unit"
    , String
"Prop" forall a b. a -> b -> (a, b)
==> String
"prop"
    , String
"Set" forall a b. a -> b -> (a, b)
==> String
"set"
    , String
"|~|" forall a b. a -> b -> (a, b)
==> String
"size"
    , String
"{?" forall a b. a -> b -> (a, b)
==> String
"case"
    ]