This is a good time to start writing some unit tests. You can create a skeleton with
"github.tutorial" scaffold-tests
You will find a generated file under
work/github/tutorial/tutorial-tests.factor, that you can open with
"github.tutorial" edit-tests. Notice the line
USING: tools.test github.tutorial ;
that imports the unit testing module as well as your own. We will only test the public
prime? function.
Tests are written using the
unit-test word, which expects two quotations: the first one containing the expected outputs, and the second one containing the words to run in order to get that output. Add these lines to
github.tutorial-tests:
{ t } [ 2 prime? ] unit-test
{ t } [ 13 prime? ] unit-test
{ t } [ 29 prime? ] unit-test
{ f } [ 15 prime? ] unit-test
{ f } [ 377 prime? ] unit-test
{ f } [ 1 prime? ] unit-test
{ t } [ 20750750228539 prime? ] unit-test
You can now run the tests with
"github.tutorial" test. You will see that we have actually made a mistake, and pressing
F3 will show more details. It seems that our assertions fails for
2.
In fact, if you manually try to run our functions for
2, you will see that our definition of
[2..b] returns
{ 2 } for
2 sqrt, due to the fact that the square root of two is less than two, so we get a descending interval. Try making a fix so that the tests now pass.
There are a few more words to test errors and inference of stack effects. Using
unit-test suffices for now, but later on you may want to check the main documentation on
Unit testing.
We can also add some documentation to our vocabulary. Autogenerated documentation is always available for user-defined words (even in the listener), but we can write some useful comments manually, or even add custom articles that will appear in the online help. Predictably, we start with
"github.tutorial" scaffold-docs and
"github.tutorial" edit-docs.
The generated file
work/github/tutorial-docs.factor imports
help.
markup and
help.
syntax. These two vocabularies define words to generate documentation. The actual help page is generated by the
HELP: parsing word.
The arguments to
HELP: are nested array of the form
{ $directive content... }. In particular, you see here the directives
$values and
$description, but a few more exist, such as
$errors,
$examples and
$see-also.
Notice that the type of the output
? has been inferred to be boolean. Change the first lines to look like
USING: help.markup help.syntax kernel math ;
IN: github.tutorial
HELP: prime?
{ $values
{ "n" fixnum }
{ "?" boolean }
}
{ $description "Tests if n is prime. n is assumed to be a positive integer." } ;
and refresh the
github.tutorial vocabulary. If you now look at the help for
prime?, for instance with
\ prime? help, you will see the updated documentation.
You can also render the directives in the listener for quicker feedback. For instance, try writing
{ $values
{ "n" integer }
{ "?" boolean }
} print-content
The help markup contains a lot of possible directives, and you can use them to write stand-alone articles in the help system. Have a look at some more with
"element-types" help.