documenting the library

lib/prelude/Predef.gf

@@ -1,11 +1,15 @@
--- predefined functions for concrete syntax, defined in AppPredefined.hs
+--1 Predefined functions for concrete syntax
+
+-- The definitions of these constants are hard-coded in GF, and defined
+-- in [AppPredefined.hs ../src/GF/Grammar/AppPredefined.hs]. Applying
+-- them to run-time variables leads to compiler errors that are often
+-- only detected at the code generation time.
 
 resource Predef = {
 
-  -- this type is for internal use only
-  param PBool = PTrue | PFalse ;
+-- This type of booleans is for internal use only.
 
-  -- these operations have their proper definitions in AppPredefined.hs
+  param PBool = PTrue | PFalse ;
 
   oper Int  : Type = variants {} ;                     -- the type of integers
   oper Ints : Int -> Type = variants {} ;              -- the type of integers from 0 to n
@@ -25,7 +29,7 @@ resource Predef = {
   oper read   : (P : Type) -> Tok -> P = variants {} ; -- convert string to param
   oper toStr  : (L : Type) -> L -> Str = variants {} ; -- find the "first" string
   oper mapStr : (L : Type) -> (Str -> Str) -> L -> L = variants {} ; 
-               -- map all strings in a data structure
+               -- map all strings in a data structure; experimental ---
 
-  } ;
+} ;
 

lib/prelude/Prelude.gf

@@ -1,9 +1,13 @@
--- language-independent prelude facilities
+--1 The GF Prelude
+
+-- This file defines some prelude facilities usable in all grammars.
 
 resource Prelude = open (Predef=Predef) in {
 
 oper
--- to construct records and tables
+
+--2 Strings, records, and tables
+
   SS  : Type = {s : Str} ;
   ss  : Str -> SS = \s -> {s = s} ;
   ss2 : (_,_ : Str) -> SS = \x,y -> ss (x ++ y) ;
@@ -18,37 +22,46 @@ oper
   SP1 : Type -> Type = \P -> {s : Str ; p : P} ;
   sp1 : (A : Type) -> Str -> A -> SP1 A = \_,s,a -> {s = s ; p = a} ;
 
+  constTable : (A,B : Type) -> B -> A => B = \_,_,b -> \\_ => b ;
+  constStr   : (A : Type) -> Str -> A => Str = \A -> constTable A Str ;
+
+-- Discontinuous constituents.
+
+  SD2 = {s1,s2 : Str} ;
+  sd2 : (_,_ : Str) -> SD2 = \x,y -> {s1 = x ; s2 = y} ;
+
+
+--2 Optional elements
+
+-- Missing form.
+
   nonExist : Str = variants {} ;
 
+-- Optional string with preference on the string vs. empty.
+ 
   optStr : Str -> Str = \s -> variants {s ; []} ;
   strOpt : Str -> Str = \s -> variants {[] ; s} ;
 
-  constTable : (A,B : Type) -> B -> A => B = \_,_,b -> \\_ => b ;
-  constStr   : (A : Type) -> Str -> A => Str = \A -> constTable A Str ;
+-- Free order between two strings.
+
+  bothWays : Str -> Str -> Str = \x,y -> variants {x ++ y ; y ++ x} ;
+
+-- Parametric order between two strings.
+
+  preOrPost : Bool -> Str -> Str -> Str = \pr,x,y -> 
+    if_then_Str pr (x ++ y) (y ++ x) ;
+
+--2 Infixes. prefixes, and postfixes
+
+-- Fixes with precedences are defined in [Precedence Precedence.html].
 
   infixSS   : Str  -> SS -> SS -> SS = \f,x,y -> ss (x.s ++ f ++ y.s) ;
   prefixSS  : Str        -> SS -> SS = \f,x   -> ss (f ++ x.s) ;
   postfixSS : Str        -> SS -> SS = \f,x   -> ss (x.s ++ f) ;
   embedSS   : Str -> Str -> SS -> SS = \f,g,x -> ss (f ++ x.s ++ g) ;
 
-  id : (A : Type) -> A -> A = \_,a -> a ;
 
--- discontinuous
-  SD2 = {s1,s2 : Str} ;
-  sd2 : (_,_ : Str) -> SD2 = \x,y -> {s1 = x ; s2 = y} ;
-
--- parentheses
-  paren : Str -> Str = \s -> "(" ++ s ++ ")" ;
-  parenss : SS -> SS = \s -> ss (paren s.s) ;
-
--- free order between two strings
-  bothWays : Str -> Str -> Str = \x,y -> variants {x ++ y ; y ++ x} ;
-
--- parametric order between two strings
-  preOrPost : Bool -> Str -> Str -> Str = \pr,x,y -> 
-    if_then_Str pr (x ++ y) (y ++ x) ;
-
--- Booleans
+--2 Booleans
 
  param Bool = True | False ;
 
@@ -70,7 +83,53 @@ oper
     _ => nonExist
     } ;
 
--- zero, one, two, or more (elements in a list etc)
+-- Interface to internal booleans
+
+  pbool2bool : Predef.PBool -> Bool = \b -> case b of {
+    Predef.PFalse => False ; Predef.PTrue => True
+    } ;
+
+  init : Tok -> Tok = Predef.tk 1 ;
+  last : Tok -> Tok = Predef.dp 1 ;
+
+--2 High-level acces to Predef operations
+
+  isNil : Tok -> Bool = \b -> pbool2bool (Predef.eqStr [] b) ;
+
+  ifTok : (A : Type) -> Tok -> Tok -> A -> A -> A = \A,t,u,a,b -> 
+    case Predef.eqStr t u of {Predef.PTrue => a ; Predef.PFalse => b} ;
+
+--2 Lexer-related operations
+
+-- Bind together two tokens in some lexers, either obligatorily or optionally
+
+  oper 
+    glue : Str -> Str -> Str = \x,y -> x ++ BIND ++ y ;
+    glueOpt : Str -> Str -> Str = \x,y -> variants {glue x y ; x ++ y} ;
+    noglueOpt : Str -> Str -> Str = \x,y -> variants {x ++ y ; glue x y} ;
+
+-- Force capitalization of next word in some unlexers
+
+    capitalize : Str -> Str = \s -> CAPIT ++ s ;
+
+-- These should be hidden, and never changed since they are hardcoded in (un)lexers
+
+    BIND : Str = "&+" ;
+    PARA : Str = "&-" ;
+    CAPIT : Str = "&|" ;
+
+--2 Miscellaneous
+
+-- Identity function
+
+  id : (A : Type) -> A -> A = \_,a -> a ;
+
+-- Parentheses
+
+  paren : Str -> Str = \s -> "(" ++ s ++ ")" ;
+  parenss : SS -> SS = \s -> ss (paren s.s) ;
+
+-- Zero, one, two, or more (elements in a list etc)
 
 param
   ENumber = E0 | E1 | E2 | Emore ;
@@ -79,34 +138,5 @@ oper
   eNext : ENumber -> ENumber = \e -> case e of {
     E0 => E1 ; E1 => E2 ; _ => Emore} ;
 
-  -- these were defined in Predef before
-  isNil : Tok -> Bool = \b -> pbool2bool (Predef.eqStr [] b) ;
 
-  ifTok : (A : Type) -> Tok -> Tok -> A -> A -> A = \A,t,u,a,b -> 
-    case Predef.eqStr t u of {Predef.PTrue => a ; Predef.PFalse => b} ;
-
-  -- so we need an interface
-  pbool2bool : Predef.PBool -> Bool = \b -> case b of {
-    Predef.PFalse => False ; Predef.PTrue => True
-    } ;
-
-  init : Tok -> Tok = Predef.tk 1 ;
-  last : Tok -> Tok = Predef.dp 1 ;
-
-
--- bind together two tokens in some lexers, either obligatorily or optionally
-
-  oper 
-    glue : Str -> Str -> Str = \x,y -> x ++ BIND ++ y ;
-    glueOpt : Str -> Str -> Str = \x,y -> variants {glue x y ; x ++ y} ;
-    noglueOpt : Str -> Str -> Str = \x,y -> variants {x ++ y ; glue x y} ;
-
--- force capitalization of next word in some unlexers
-
-    capitalize : Str -> Str = \s -> CAPIT ++ s ;
-
--- these should be hidden, and never changed since it's hardcoded in (un)lexers
-    BIND : Str = "&+" ;
-    PARA : Str = "&-" ;
-    CAPIT : Str = "&|" ;
-} ;
+}