https://github.com/sogaiu/janet-usages
https://github.com/sogaiu/janet-usages
examples janet testing usages
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/sogaiu/janet-usages
- Owner: sogaiu
- Created: 2021-10-12T04:36:34.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2021-11-09T06:00:53.000Z (over 4 years ago)
- Last Synced: 2024-12-28T10:52:20.608Z (over 1 year ago)
- Topics: examples, janet, testing, usages
- Homepage:
- Size: 59.6 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- Support: support/build.janet
Awesome Lists containing this project
README
= janet-usages - Verifiable Usage Examples
:toc:
== Aim
Encourage the creation of verifiable usage examples to help potential
users form appropriate mental models.
== Status and Warnings
This is an early stage project. Be sure to examine the
link:doc/warning.adoc[fine print].
== How
* Within `comment` blocks, put expressions / forms to be verified along
with brief records of expected values:
+
[source,janet]
----
(comment
(- 1 1)
# => 0
)
----
+
Note the use of a single line comment and `=>` to express an
expected return value.
+
One might call the combination of the form and the comment with the expected
value a "comment block test".
+
See link:doc/tips.adoc[Usage Writing Tips] for more details.
* Once some setup steps are followed, usage examples can be run by:
`jpm test`
== Setup
Setting things up is mostly a matter of copying a single file.
Suppose there's a project directory like:
----
.
├── my-src-dir
│ └── fun.janet
├── project.janet
└── test
└── test.janet
----
Copy the file
https://gitlab.com/sogaiu/janet-usages/-/raw/master/test/usages.janet[test/usages.janet]
from this repository to the target project's `test` subdirectory.
Alternatively, from the target project's `test` subdirectory this might work:
----
curl -O https://gitlab.com/sogaiu/janet-usages/-/raw/master/test/usages.janet
----
Now it should look something like:
----
.
├── my-src-dir
│ └── fun.janet
├── project.janet
└── test
├── test.janet
└── usages.janet <-- copied this file into place
----
If `jpm test` is executed and there isn't already a `usages` directory,
it will be created along with a `sample.janet` file:
----
.
├── my-src-dir
│ └── fun.janet
├── project.janet
├── test
│ ├── test.janet
│ └── usages.janet
└── usages <-- created this directory
└── sample.janet <-- created this file
----
`sample.janet` is just an example. Please feel free to modify it or
erase it after examining it.
See link:doc/details.adoc[Details] for additional information regarding the
various files and directories.
== Usage
To run the tests and get a report: `jpm test`
Add more usage examples by creating more comment block tests in files
that live in the `usages` directory.
== Samples
This repository also has a `usages` directory with some examples.
== Acknowledgments
* andrewchambers - suggestion and explanation
* bakpakin - janet, jpm, helper.janet, path.janet, peg for janet, etc.
* pepe - discussion, One-Shot Power Util Solver ™ motivation, and naming
* pyrmont - discussion and exploration
* Saikyun - discussion and testing