~jojo/Carth

ref: 58f475edcf63ad30f0aafd711da977e4ba317bf2 Carth/REFERENCE.org -rw-r--r-- 2.6 KiB
58f475edJoJo Literate programming: Compile .org by untangling carth src blocks 2 years ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
#+TITLE: The Carth Reference

This document is the primary reference for the Carth programming
language. It is updated on a best-effort basis. It should be valid and
complete, but it may not be.

* TODO Introduction

** TODO How to use this document

** TODO Contributing

** TODO Influences

** TODO Glossary

* TODO Lexical structure

* TODO Macros

* TODO Packages, modules, and source files

* TODO Items

** TODO Global variable definitions

** TODO Type definitions

* TODO Expressions

** Type ascriptions
   Type ascriptions are primarily used to:
   - increase readability when the type of an expression is not obvious;
   - assert at compile-time that an expression is of or can specialize to the given type;
   - or specialize the type of a generic expression, restricting its usage.

*** Syntax
    #+BEGIN_SRC bnf
    type ascription = "(", ":", expression, type, ")" ;
    #+END_SRC

*** Example
    #+BEGIN_SRC scheme
    (: x Int)
    #+END_SRC

* TODO Patterns

* TODO Type system

* TODO Memory model

* TODO Linkage

* TODO Unsafety

* TODO Compile time evaluation

* TODO Runtime
* TODO Literate Carth
  :PROPERTIES:
  :CUSTOM_ID: Literate-Carth
  :END:
  Carth has native support for literate programming with Org
  mode. Either use Emacs with Babel in Org-mode for an interactive
  session, or interpret/compile the file with ~carth~ just like a
  normal ~.carth~ file!

** Example
   Consider a file ~cool.org~ with the following content:

   #+BEGIN_SRC org

   ,#+TITLE: Literate Programming Rules!

   Literate programming is just really cool!

   ~carth~ will assume ~tangle~ = ~yes~ by default, but setting it
   explicitly won't hurt.

   ,#+BEGIN_SRC carth :tangle yes
   (define (main _)
     (printInt (id 1337)))
   ,#+END_SRC

   ,* The ~id~ function
     ~id~ is the identity function. It returns its argument unchanged.

     ,#+BEGIN_SRC carth
     (define (id x) x)
     ,#+END_SRC

   ,* How not to use ~id~
     Here is an example of how not to use ~id~. Note that this won't
     compile. We show this in a SRC block to get syntax highlighting etc,
     but as ~tangle~ is ~no~, this source block will be ignored by carth.

     ,#+BEGIN_SRC carth :tangle no
     (printInt id)
     ,#+END_SRC

   #+END_SRC

   When e.g. interpreting this file with ~carth i cool.org~, the Carth
   source will untangled from the rest of the document. Line numbers
   are preserved. The result of the untangling stage will be the
   following:

   #+BEGIN_SRC carth









   (define (main _)
     (printInt (id 1337)))






   (define (id x) x)











   #+END_SRC

   And for completeness, the result of interpreting that will be ~1337~.