Skip to content

Commit

Permalink
Merge pull request gelisam#178 from gelisam/gelisam/primitives-docume…
Browse files Browse the repository at this point in the history 
…ntation

bare minimum documentation for everything in prelude.kl
  • Loading branch information
@gelisam
gelisam authored Dec 5, 2022
2 parents 0181004 + 161dfdb commit 8fc5e8a
Show file tree
Hide file tree
Showing 3 changed files with 321 additions and 0 deletions.
50 changes: 50 additions & 0 deletions examples/primitives-documentation.golden
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
(pair "open-syntax" #<closure>) : (Pair String (Syntax → (Syntax-Contents Syntax)))
(pair "close-syntax" #<closure>) : (Pair String (Syntax → (Syntax → ((Syntax-Contents Syntax) → Syntax))))
(pair "+" #<closure>) : (Pair String (Integer → (Integer → Integer)))
(pair "-" #<closure>) : (Pair String (Integer → (Integer → Integer)))
(pair "*" #<closure>) : (Pair String (Integer → (Integer → Integer)))
(pair "/" #<closure>) : (Pair String (Integer → (Integer → Integer)))
(pair "abs" #<closure>) : (Pair String (Integer → Integer))
(pair "negate" #<closure>) : (Pair String (Integer → Integer))
(pair ">" #<closure>) : (Pair String (Integer → (Integer → Bool)))
(pair ">=" #<closure>) : (Pair String (Integer → (Integer → Bool)))
(pair "<" #<closure>) : (Pair String (Integer → (Integer → Bool)))
(pair "<=" #<closure>) : (Pair String (Integer → (Integer → Bool)))
(pair "=" #<closure>) : (Pair String (Integer → (Integer → Bool)))
(pair "/=" #<closure>) : (Pair String (Integer → (Integer → Bool)))
(pair "integer->string" #<closure>) : (Pair String (Integer → String))
(pair "string-append" #<closure>) : (Pair String (String → (String → String)))
(pair "substring" #<closure>) : (Pair String (Integer → (Integer → (String → (Maybe String)))))
(pair "string-length" #<closure>) : (Pair String (String → Integer))
(pair "string=?" #<closure>) : (Pair String (String → (String → Bool)))
(pair "string/=?" #<closure>) : (Pair String (String → (String → Bool)))
(pair "string<?" #<closure>) : (Pair String (String → (String → Bool)))
(pair "string<=?" #<closure>) : (Pair String (String → (String → Bool)))
(pair "string>?" #<closure>) : (Pair String (String → (String → Bool)))
(pair "string>=?" #<closure>) : (Pair String (String → (String → Bool)))
(pair "string-upcase" #<closure>) : (Pair String (String → String))
(pair "string-downcase" #<closure>) : (Pair String (String → String))
(pair "string-titlecase" #<closure>) : (Pair String (String → String))
(pair "string-foldcase" #<closure>) : (Pair String (String → String))
(pair "pure-IO" #<closure>) : ∀(α : *). (Pair String (α → (IO α)))
(pair "bind-IO" #<closure>) : ∀(α : *) (β : *). (Pair String ((IO α) → ((α → (IO β)) → (IO β))))
(flip) : ScopeAction
(add) : ScopeAction
(remove) : ScopeAction
(unit) : Unit
(true) : Bool
(false) : Bool
(module) : Problem
(declaration) : Problem
(type) : Problem
(pattern) : Problem
(type-pattern) : Problem
(nothing) : ∀(α : *). (Maybe α)
(nil) : ∀(α : *). (List α)
make-introducer : (Macro (ScopeAction → (Syntax → Syntax)))
which-problem : (Macro Problem)
(pair "id" #<closure>) : ∀(α : *). (Pair String (α → α))
(pair "const" #<closure>) : ∀(α : *) (β : *). (Pair String (α → (β → α)))
(pair "compose" #<closure>) : ∀(α : *) (β : *) (γ : *). (Pair String ((α → β) → ((γ → α) → (γ → β))))
(pair "stdout" #<output port>) : (Pair String Output-Port)
(pair "write" #<closure>) : (Pair String (Output-Port → (String → (IO Unit))))
268 changes: 268 additions & 0 deletions examples/primitives-documentation.kl
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,268 @@
#lang "prelude.kl"

(import "pair-datatype.kl")

-- This file acts as a bare minimum form of documentation for all the
-- primitives from "prelude.kl". May we one day have nice prose explaining all
-- of it!
--
-- Until then, values are listed as (example (pair "expr" expr)) so that the
-- "primitives-documentation.golden" file lists both their name and their type
-- signature.
-- For types, their kind is given in a comment.
--
-- Macros don't have types, but sometimes behave as if they have one, in the
-- sense that using them properly requires giving them a certain number of
-- arguments of the right type, and doing so will result in a value of a given
-- output type. A common example is data constructors, which are macros in Klister.
-- In those cases, the type is given in a comment, with the arguments tupled-up
-- to indicate the lack of currying.
-- Otherwise, using the macro properly requires an input which matches a
-- particular shape, so an example is given.


-- primitive module macros
--
-- #%module : Macro (#%module
-- (define x 42)
-- (define y 43))

-- primitive declaration macros
--
-- define : Macro (define x 42)
-- datatype : Macro (datatype (List A)
-- (nil)
-- (:: A (List A)))
-- define-macros : Macro (define-macros
-- ([my-macro1
-- (lambda (stx)
-- (pure '42))]
-- [my-macro2
-- (lambda (stx)
-- (pure '43))]))
-- example : Macro (example 42)
-- run : Macro (run (write stdout "hello world!\n"))
-- import : Macro (import "list.kl")
-- (import (shift "prelude.kl" 1))
-- (import (rename (shift "prelude.kl" 1)
-- [#%module prelude-module]
-- [define prelude-define]))
-- export : Macro (export List nil ::)
-- (export (rename ([List ConsList]
-- [:: cons])
-- List nil ::))
-- meta : Macro (meta
-- (define x 42)
-- (define y 43))
-- group : Macro (group
-- (define x 42)
-- (define y 43))

-- primitive types
--
-- Syntax : Type
(example (pair "open-syntax" open-syntax))
(example (pair "close-syntax" close-syntax))
--
-- -> : Type -> Type -> Type
--
-- Integer : Type
(example (pair "+" +))
(example (pair "-" -))
(example (pair "*" *))
(example (pair "/" /))
(example (pair "abs" abs))
(example (pair "negate" negate))
(example (pair ">" >))
(example (pair ">=" >=))
(example (pair "<" <))
(example (pair "<=" <=))
(example (pair "=" =))
(example (pair "/=" /=))
(example (pair "integer->string" integer->string))
--
-- Macro : Type -> Type
--
-- Type : Type
--
-- String : Type
(example (pair "string-append" string-append))
(example (pair "substring" substring))
(example (pair "string-length" string-length))
(example (pair "string=?" string=?))
(example (pair "string/=?" string/=?))
(example (pair "string<?" string<?))
(example (pair "string<=?" string<=?))
(example (pair "string>?" string>?))
(example (pair "string>=?" string>=?))
(example (pair "string-upcase" string-upcase))
(example (pair "string-downcase" string-downcase))
(example (pair "string-titlecase" string-titlecase))
(example (pair "string-foldcase" string-foldcase))
--
-- IO : Type -> Type
(example (pair "pure-IO" pure-IO))
(example (pair "bind-IO" bind-IO))

-- primitive datatypes
--
-- ScopeAction : Type
(example (flip))
(example (add))
(example (remove))
--
-- Unit : Type
(example unit)
--
-- Bool : Type
(example true)
(example false)
--
-- Problem : Type
(example (module))
(example (declaration))
(example (type))
-- expression : Type -> Problem
(example (pattern))
(example (type-pattern))
--
-- Maybe : Type -> Type
(example nothing)
-- just : A -> Maybe A
--
-- List : Type -> Type
(example (nil))
-- :: : (A, List A) -> List A
--
-- Syntax-Contents : Type -> Type
-- list-contents : List A -> Syntax-Contents A
-- integer-contents : Integer -> Syntax-Contents A
-- string-contents : String -> Syntax-Contents A
-- identifier-contents : String -> Syntax-Contents A

-- primitive expression macros
--
-- error : Syntax -> A
-- the : ((A : Type), A) -> A
-- let : Macro (let [x 42]
-- (+ x x))
-- flet : Macro (flet [fact (n)
-- (if (= n 0)
-- 1
-- (* n (fact (- n 1))))]
-- (fact 10))
-- lambda : Macro (lambda (x) (+ x 1))
-- #%app : Macro (#%app + 2 2)
-- #%integer-literal : Integer -> Integer
-- #%string-literal : String -> String
-- pure : A -> Macro A
-- >>= : (Macro A, A -> Macro B) -> Macro B
-- syntax-error : Syntax -> Macro A
-- bound-identifier=? : (Syntax, Syntax) -> Macro Bool
-- free-identifier=? : (Syntax, Syntax) -> Macro Bool
-- quote : Macro '(+ 2 2)
-- ident-syntax : Macro (ident-syntax 'bar 'loc)
-- empty-list-syntax : Syntax -> Syntax
-- cons-list-syntax : Macro (cons-list-syntax '1 '(2 3 4) 'loc)
-- list-syntax : Macro (list-syntax ('1 '2 '3 '4) 'loc))
-- integer-syntax : (Integer, Syntax) -> Syntax
-- string-syntax : (String, Syntax) -> Syntax
-- replace-loc : (Syntax, Syntax) -> Syntax
-- syntax-case : Macro (syntax-case 'bar
-- [(ident x)
-- (list 'foo x 'baz)])
-- (syntax-case '2
-- [(integer x)
-- (list 1 x 3)])
-- (syntax-case '"bar"
-- [(string x)
-- (list "foo" x "baz")])
-- (syntax-case '(2 3 5)
-- [(list (x y z))
-- (list '1 x y '4 z '6)])
-- (syntax-case '(2 4 5)
-- [(cons x xs)
-- (cons-list-syntax '1
-- (cons-list-syntax x
-- (cons-list-syntax '3
-- xs
-- 'loc)
-- 'loc)
-- 'loc)])
-- (syntax-case '(1 2 3 4)
-- [()
-- 'zero]
-- [(list (_))
-- 'one]
-- [(list (_ _))
-- 'two]
-- [_
-- 'more])
-- let-syntax : Macro (let-syntax [my-macro
-- (lambda (stx)
-- (pure '2))]
-- (+ (my-macro a b c) 2))
-- log : Syntax -> Macro Unit
(example (make-introducer))
(example (which-problem))
-- case : Macro (case (list 1 2 3)
-- [(nil)
-- (nothing)]
-- [(:: x _)
-- (just x)])
-- (case (list 1 2 3)
-- [(list x _ _)
-- x])
-- type-case : Macro (>>= (which-problem)
-- (lambda (problem)
-- (case problem
-- [(expression tp)
-- (type-case tp
-- [String
-- (pure "string")]
-- [(-> A B)
-- (pure "arrow")])])))

-- primitive patterns
--
-- else : Pattern (case (list 1 2 3 4)
-- [(nil)
-- (nil)]
-- [(list x)
-- (list x)]
-- [(list x y)
-- (list x y)]
-- [(else x)
-- x])

-- primitive universal macros
--
-- with-unknown-type : Macro (with-unknown-type [A]
-- (the (-> A A)
-- (lambda (x) x)))

-- non-primitive declaration macros
--
-- defun : Macro (defun fact (n)
-- (if (= n 0)
-- 1
-- (* n (fact (- n 1)))))

-- non-primitive expression macros
--
-- unquote : Macro `(1 2 3 ,(integer-syntax (+ 2 2) 'loc))
-- quasiquote : Macro `(1 2 3 4)
-- quasiquote/loc : Macro (quasiquote/loc 'loc (1 2 3 4))

-- non-primitive expressions
--
-- if : Macro (if true 1 0)
(example (pair "id" id))
(example (pair "const" const))
(example (pair "compose" compose))

-- IO primitives
--
-- Output-Port : Type
(example (pair "stdout" stdout))
(example (pair "write" write))
3 changes: 3 additions & 0 deletions stdlib/prelude.kl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@
(define const (lambda (x y) x))
(define compose (lambda (f g x) (f (g x))))

-- When adding an export to this file, please remember to add a corresponding
-- entry to "examples/primitives-documentation.kl", so that we at least have
-- its type signature as a bare minimum form of documentation.
(export -- primitive module macros
#%module

Expand Down

0 comments on commit 8fc5e8a

Please sign in to comment.