aboutsummaryrefslogtreecommitdiff
path: root/documentation
diff options
context:
space:
mode:
authorEduardo Julian2021-08-19 04:59:06 -0400
committerEduardo Julian2021-08-19 04:59:06 -0400
commitd772fe99d5d4990c6774481fb64d12280cdb6aae (patch)
tree209a2ce3b8e896be15db40bc58db830a5304b4f9 /documentation
parente00ba096c8837abe85d366e0c1293c09dbe84d81 (diff)
Enabled compile-time code evaluation (i.e. "eval" function).
Diffstat (limited to 'documentation')
-rw-r--r--documentation/book/the_lux_programming_language/chapter_15.md2
-rw-r--r--documentation/book/the_lux_programming_language/chapter_16.md172
-rw-r--r--documentation/bookmark/Compilation.md4
-rw-r--r--documentation/bookmark/algorithm.md4
-rw-r--r--documentation/bookmark/compilation.md8
-rw-r--r--documentation/bookmark/composition.md4
-rw-r--r--documentation/bookmark/database.md2
-rw-r--r--documentation/bookmark/database/key_value.md4
-rw-r--r--documentation/bookmark/floating_point.md1
-rw-r--r--documentation/bookmark/incremental_computing.md5
-rw-r--r--documentation/bookmark/inspiration.md1
-rw-r--r--documentation/bookmark/specification.md4
-rw-r--r--documentation/bookmark/spreadsheet.md4
-rw-r--r--documentation/bookmark/type_theory/dependent_types.md1
-rw-r--r--documentation/bookmark/user_interface/human_computer_interaction.md4
-rw-r--r--documentation/bookmark/web_framework.md1
16 files changed, 216 insertions, 5 deletions
diff --git a/documentation/book/the_lux_programming_language/chapter_15.md b/documentation/book/the_lux_programming_language/chapter_15.md
index d03014f42..c87494929 100644
--- a/documentation/book/the_lux_programming_language/chapter_15.md
+++ b/documentation/book/the_lux_programming_language/chapter_15.md
@@ -89,5 +89,5 @@ These data-structures are very easy to use and offer decent performance, so you'
The next chapter is going to be slightly different, in that we're going to be learning not how to write programs, but how to test them.
-See you in the next chapter!
+See you in [the next chapter](chapter_16.md)!
diff --git a/documentation/book/the_lux_programming_language/chapter_16.md b/documentation/book/the_lux_programming_language/chapter_16.md
new file mode 100644
index 000000000..929188f35
--- /dev/null
+++ b/documentation/book/the_lux_programming_language/chapter_16.md
@@ -0,0 +1,172 @@
+# Chapter 16: Testing
+
+_Where you will learn how to avoid annoying bug reports._
+
+---
+
+Automated testing is a fundamental aspect of modern software development.
+
+Long gone are the days of manual, ad-hoc testing.
+
+With modern testing tools and frameworks, it's somewhat easy to increase the quality of programs by implementing comprehensive test suites that can cover large percentages of a program's functionality and behavior.
+
+Lux doesn't stay behind and includes a testing module as part of its standard library.
+
+The `library/lux/test` module contains the machinery you need to write unit-testing suites for your programs.
+
+Not only that, but the _Aedifex_ build tool for Lux also includes a command for testing: `lux test`
+
+How do you set that up?
+Let's take a look at the `project.lux` file for the Lux standard library itself.
+
+```
+{#identity ["com.github.luxlang" "stdlib" "0.6.0"]
+
+#deploy_repositories {"snapshots" "https://oss.sonatype.org/content/repositories/snapshots/"
+ "releases" "https://oss.sonatype.org/service/local/staging/deploy/maven2/"}
+
+#repositories ["https://oss.sonatype.org/content/repositories/snapshots/"
+ "https://oss.sonatype.org/service/local/staging/deploy/maven2/"]
+
+#compiler ["com.github.luxlang" "lux-jvm" "0.6.0" "jar"]
+#description "Standard library for the Lux programming language."
+#test "test/lux"}
+```
+
+The `#test` parameter is similar to the `#program` parameter in that it specifies the name of a Lux module.
+
+Here is a summary of the file:
+
+```
+(.module:
+ [library
+ ["/" lux #*
+ [program (#+ program:)]
+ ["_" test (#+ Test)]
+ [control
+ ["." io]]
+ ...
+ ]])
+
+(program: args
+ (io.io (_.run! (_.times 100 ..test))))
+
+```
+
+A test suit consists of a `Test` (or a composite of as many `Test`s as you want), which is then `run!`.
+The `times` combinator allows you to execute `Test`s several times.
+This can be very useful when using random data generation within your tests, as each run of the tests will lead to the generation of different sorts of data.
+This will help you cover many possible scenarios within the same test run, and perhaps uncover tricky corner cases you wouldn't have thought of.
+
+But where do those tests come from?
+Nothing is being defined here.
+
+Let's take a look at the tests defined in a simpler module.
+
+Well, the run macro, from lux/test pulls in all the tests from the imported modules to run them later once the program starts.
+
+To know how tests work, let's take a look at one of those modules.
+
+ From `test/lux/data/collection/stack`.
+
+```
+(.module:
+ [library
+ [lux #*
+ ["_" test (#+ Test)]
+ [abstract
+ [monad (#+ do)]
+ [\\specification
+ ["$." equivalence]
+ ["$." functor (#+ Injection)]]]
+ [control
+ ["." maybe]]
+ [data
+ ["." bit ("#\." equivalence)]]
+ [math
+ ["." random]
+ [number
+ ["n" nat]]]]]
+ [\\library
+ ["." /]])
+
+(def: (injection value)
+ (Injection /.Stack)
+ (/.top value /.empty))
+
+(def: .public test
+ Test
+ (<| (_.covering /._)
+ (_.for [/.Stack])
+ (do random.monad
+ [size (\ random.monad map (n.% 100) random.nat)
+ sample (random.stack size random.nat)
+ expected_top random.nat]
+ ($_ _.and
+ (_.for [/.equivalence]
+ ($equivalence.spec (/.equivalence n.equivalence) (random.stack size random.nat)))
+ (_.for [/.functor]
+ ($functor.spec ..injection /.equivalence /.functor))
+
+ (_.cover [/.size]
+ (n.= size (/.size sample)))
+ (_.cover [/.empty?]
+ (bit\= (n.= 0 (/.size sample))
+ (/.empty? sample)))
+ (_.cover [/.empty]
+ (/.empty? /.empty))
+ (_.cover [/.value]
+ (case (/.value sample)
+ #.None
+ (/.empty? sample)
+
+ (#.Some _)
+ (not (/.empty? sample))))
+ (_.cover [/.next]
+ (case (/.next sample)
+ #.None
+ (/.empty? sample)
+
+ (#.Some [top remaining])
+ (\ (/.equivalence n.equivalence) =
+ sample
+ (/.top top remaining))))
+ (_.cover [/.top]
+ (case (/.next (/.top expected_top sample))
+ (#.Some [actual_top actual_sample])
+ (and (same? expected_top actual_top)
+ (same? sample actual_sample))
+
+ #.None
+ false))
+ ))))
+
+```
+
+There's a lot going on here.
+
+First of all, by using the `covering` macro, you can tell the test suit to track the coverage that your test suite has of a given module.
+That way, if your tests miss some _exported_, the report you'll get after running the tests will tell you, so you can judiciously choose to either expand your coverage, or skip covering them.
+The `for` and `cover` macros then signal whenever one or more definitions are being covered by a given test.
+
+Lux also defines some _specifications_, which are basically parameterizable tests, which implement consistent testing for various interfaces in the standard library.
+That way, when testing an implementation of those interfaces, instead of having to copy-paste, or re-invent the testing every time, the specification is imported.
+This enables consistent testing of implementations.
+
+`and` allows you to _sequentially_ compose `Test`s into a larger `Test`.
+
+You can also see an example of how to use randomness to generate sample data for testing.
+
+---
+
+If you want to learn more about how to write tests, feel free to check out the test-suite for the Lux standard library.
+It's very comprehensive and filled with good examples.
+
+---
+
+Without tests, the reliability of programs becomes a matter of faith, not engineering.
+
+Automated tests can be integrated into processes of continuous delivery and integration to increase the confidence of individuals and teams that real value is being delivered, and that the customer won't be dissatisfied by buggy software.
+
+Now that you know how to test your programs, you know everything you need to know to be a Lux programmer.
+
diff --git a/documentation/bookmark/Compilation.md b/documentation/bookmark/Compilation.md
deleted file mode 100644
index 2249ebdc3..000000000
--- a/documentation/bookmark/Compilation.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# Demand-driven
-
-1. [Queries: demand-driven compilation](https://github.com/rust-lang/rustc-guide/blob/master/src/query.md)
-
diff --git a/documentation/bookmark/algorithm.md b/documentation/bookmark/algorithm.md
new file mode 100644
index 000000000..43d3ad8ae
--- /dev/null
+++ b/documentation/bookmark/algorithm.md
@@ -0,0 +1,4 @@
+# Reference
+
+1. [There and Back Again](https://www.brics.dk/RS/01/39/BRICS-RS-01-39.pdf)
+
diff --git a/documentation/bookmark/compilation.md b/documentation/bookmark/compilation.md
new file mode 100644
index 000000000..ddd165e6e
--- /dev/null
+++ b/documentation/bookmark/compilation.md
@@ -0,0 +1,8 @@
+# Extensibility & control
+
+1. [Compilation Strategies as Objects](https://www.researchgate.net/publication/2273387_Compilation_Strategies_as_Objects)
+
+# Demand-driven
+
+1. [Queries: demand-driven compilation](https://github.com/rust-lang/rustc-guide/blob/master/src/query.md)
+
diff --git a/documentation/bookmark/composition.md b/documentation/bookmark/composition.md
new file mode 100644
index 000000000..85c6daba3
--- /dev/null
+++ b/documentation/bookmark/composition.md
@@ -0,0 +1,4 @@
+# Reference
+
+1. [Open, extensible composition models](http://www.vpri.org/pdf/tr2011002_oecm.pdf)
+
diff --git a/documentation/bookmark/database.md b/documentation/bookmark/database.md
index 3ef227087..0e27f89cf 100644
--- a/documentation/bookmark/database.md
+++ b/documentation/bookmark/database.md
@@ -90,6 +90,8 @@
# Storage
+1. [Database Internals: A deep-dive into how distributed data systems work](https://www.oreilly.com/library/view/database-internals/9781492040330/)
+1. [B-Trees: More Than I Thought I'd Want to Know](https://benjamincongdon.me/blog/2021/08/17/B-Trees-More-Than-I-Thought-Id-Want-to-Know/)
1. [Understanding LSM Trees: What Powers Write-Heavy Databases](https://yetanotherdevblog.com/lsm/)
1. http://www.benstopford.com/2015/02/14/log-structured-merge-trees/
1. A Comparison of Adaptive Radix Trees and Hash Tables
diff --git a/documentation/bookmark/database/key_value.md b/documentation/bookmark/database/key_value.md
new file mode 100644
index 000000000..3943ad31b
--- /dev/null
+++ b/documentation/bookmark/database/key_value.md
@@ -0,0 +1,4 @@
+# Reference
+
+1. [Fast key-value stores: An idea whose time has come and gone](https://storage.googleapis.com/pub-tools-public-publication-data/pdf/03de87e2856b06a94ffae7dca218db2d4b9afd39.pdf)
+
diff --git a/documentation/bookmark/floating_point.md b/documentation/bookmark/floating_point.md
index 47527b43e..509990dd1 100644
--- a/documentation/bookmark/floating_point.md
+++ b/documentation/bookmark/floating_point.md
@@ -30,5 +30,6 @@
# Algorithm
+1. [Speeding up atan2f by 50x](https://mazzo.li/posts/vectorized-atan2.html)
1. [Kahan summation algorithm](https://en.wikipedia.org/wiki/Kahan_summation_algorithm)
diff --git a/documentation/bookmark/incremental_computing.md b/documentation/bookmark/incremental_computing.md
new file mode 100644
index 000000000..9daa63439
--- /dev/null
+++ b/documentation/bookmark/incremental_computing.md
@@ -0,0 +1,5 @@
+# Reference
+
+1. [Incremental computing](https://en.wikipedia.org/wiki/Incremental_computing)
+1. [A theory of changes for higher-order languages](https://www.researchgate.net/publication/269126515_A_theory_of_changes_for_higher-order_languages)
+
diff --git a/documentation/bookmark/inspiration.md b/documentation/bookmark/inspiration.md
index 5331f9a0b..1a99e455f 100644
--- a/documentation/bookmark/inspiration.md
+++ b/documentation/bookmark/inspiration.md
@@ -16,6 +16,7 @@
# Tool
+1. [Building Developer Tools](https://explog.in/notes/devtools/index.html)
1. [Toward the next generation of programming tools: Programmers have built great tools for others. It’s time they built some for themselves.](https://www.oreilly.com/radar/toward-the-next-generation-of-programming-tools/)
# Software engineering
diff --git a/documentation/bookmark/specification.md b/documentation/bookmark/specification.md
new file mode 100644
index 000000000..cac3f547a
--- /dev/null
+++ b/documentation/bookmark/specification.md
@@ -0,0 +1,4 @@
+# Reference
+
+1. [Announcing Spectacle – A language for Writing and Checking Formal Specifications in Haskell](https://awakesecurity.com/blog/spectacle-a-language-for-writing-and-checking-formal-specifications-in-haskell/)
+
diff --git a/documentation/bookmark/spreadsheet.md b/documentation/bookmark/spreadsheet.md
new file mode 100644
index 000000000..74bb1311f
--- /dev/null
+++ b/documentation/bookmark/spreadsheet.md
@@ -0,0 +1,4 @@
+# Reference
+
+1. [HyperFormula](https://handsontable.github.io/hyperformula/)
+
diff --git a/documentation/bookmark/type_theory/dependent_types.md b/documentation/bookmark/type_theory/dependent_types.md
index 6feb91d99..2ba13222b 100644
--- a/documentation/bookmark/type_theory/dependent_types.md
+++ b/documentation/bookmark/type_theory/dependent_types.md
@@ -5,6 +5,7 @@
# Reference
+1. [A Language Agnostic Introduction to Dependent Types](https://www.shuangrimu.com/posts/language-agnostic-intro-to-dependent-types.html)
1. [The Gentle Art of Levitation](http://lambda-the-ultimate.org/node/5526)
1. [Programming up to Congruence](http://www.cs.yale.edu/homes/vilhelm/papers/popl15congruence.pdf)
1. [From Scheme to Dependent Types in 100 lines by Gershom Bazerman (Part 1)](https://vimeo.com/134561872)
diff --git a/documentation/bookmark/user_interface/human_computer_interaction.md b/documentation/bookmark/user_interface/human_computer_interaction.md
new file mode 100644
index 000000000..1eb2ce86d
--- /dev/null
+++ b/documentation/bookmark/user_interface/human_computer_interaction.md
@@ -0,0 +1,4 @@
+# Reference
+
+1. [Formality Considered Harmful: Experiences, Emerging Themes, and Directions on the Use of Formal Representations in Interactive Systems](https://andymatuschak.org/files/papers/Shipman%20and%20Marshall%20-%201999%20-%20Formality%20Considered%20Harmful%20Experiences,%20Emergin.pdf)
+
diff --git a/documentation/bookmark/web_framework.md b/documentation/bookmark/web_framework.md
index 7e8a36a48..406a770a2 100644
--- a/documentation/bookmark/web_framework.md
+++ b/documentation/bookmark/web_framework.md
@@ -152,6 +152,7 @@
# Rendering
+1. [The Virtual DOM is slow. Meet the Memoized DOM](https://www.freecodecamp.org/news/the-virtual-dom-is-slow-meet-the-memoized-dom-bb19f546cc52/)
1. [Incrementally Improving The DOM](https://blog.functorial.com/posts/2018-04-08-Incrementally-Improving-The-DOM.html)
1. https://medium.com/@ryansolid/the-fastest-way-to-render-the-dom-e3b226b15ca3
1. https://github.com/Famous/engine