[jackhill/mal.git] / lib / README.md

This directory contains general-purpose reusable code that does not
fit in the process like `cond`, `gensym`, `inc`, `not` and `or`.

The split in small files is motivated by implementations too limited
to load a single big file, but MAL has no proper module management.

However, here are some guidelines.

- Begin with an one-line ;; short description

- End with `nil`, so that the result of `load-file` is conveniently
  short when loading manually and predictilbe for automatic testing

- Describe the restrictions on each parameter in comments.

- Define private symbols in hidden environments when possible. If this
  is not possible, for example for macros, give them a name starting
  with an underscore.

- Support successive imports safely by giving the same definitions
  again.

If a module provides tests, you may run against an implementation IMPL
with these commands.
```
make IMPL^stepA
cd tests
python ../runtest.py lib/MODULE.mal ../IMPL/run
```
Commit	Line	Data
3e9b89d4 NB	1	This directory contains general-purpose reusable code that does not
	2	fit in the process like `cond`, `gensym`, `inc`, `not` and `or`.
	3
	4	The split in small files is motivated by implementations too limited
	5	to load a single big file, but MAL has no proper module management.
	6
	7	However, here are some guidelines.
	8
	9	- Begin with an one-line ;; short description
	10
	11	- End with `nil`, so that the result of `load-file` is conveniently
	12	short when loading manually and predictilbe for automatic testing
	13
	14	- Describe the restrictions on each parameter in comments.
	15
	16	- Define private symbols in hidden environments when possible. If this
	17	is not possible, for example for macros, give them a name starting
	18	with an underscore.
	19
	20	- Support successive imports safely by giving the same definitions
	21	again.
83665b4f NB	22
	23	If a module provides tests, you may run against an implementation IMPL
	24	with these commands.
	25	```
	26	make IMPL^stepA
	27	cd tests
	28	python ../runtest.py lib/MODULE.mal ../IMPL/run
	29	```