Automatic validation of Crystal code samples
1.3.0 Latest release released
31 1 2

crystal-examples Build Status

crystal examples checker

Supported Literals

In addition to the standard crystal literals, the following literals may be used for comments.

x # raises FooError
x # => 10.00:00:00.000010000
x # => UUID(ba714f86-cac6-42c7-8956-bcf5105e1b81)
x # => 2016-02-15 04:35:50.0 UTC
x # => NaN
x # => #<Foo>
x # => Foo(@a=1, @b=1.0)


  • crystal-examples : linux x86_64 static binary is available
  • docker compose


First, specify a working directory and initialize or upgrade. Be careful when specifying an existing directory, as files such as Makefiles will be overwritten.

$ crystal-examples setup .
Setting up working directory in ./
  ok         /tmp/work
  create     Makefile
  create     config.toml
  create     compose.yaml
  create     examples.db
  create     crystal-examples # 0.3.1 [51d73b1] (2019-03-20)
  not found  crystal/src
  not found  ./crystal/bin/crystal # (compiled compiler)


Second, prepare source directory. In general, run as follows.

$ git clone

Here, crsytal/src should be in subdir because compiler will work in docker container which mounts "./".


Then, prepare crystal compiler. There are three choices.

1. use compiled compiler (default)

Build ./crystal/.build/crystal if it's first time for the ./crystal src.

$ make crystal
2. use system compiler

Update the value of bin to just crystal.

$ vi config.toml
bin     = "crystal"               # use system compiler
3. use custom compiler

Same above, you can use any compiler by updating bin in config.toml. Note that it will be used in docker container.

Web interface

make web runs web server at in docker container.

$ make web
[production] Kemal is ready to lead at

If you want to change setting like listen port, edit config.toml.



a relative path from crystal src dir to the src file. For example,, http/

Example model

one code block written in src as comment.

  • src : its src
  • seq : sequence number of the comment blocks in the src
  • line : line number of the comment block in the src
  • type : type of comment block (ex. json, crystal)
  • code : content of the comment block
[] of Int32 # same as Array(Int32)
[]          # syntax error
  • sha1 : SHA1 message digest for the code
  • compiled : status cache about compiling
  • tested : status cache about testing

CompileCache model

compile cache of Example

  • src, seq : the primary key for the Example
  • exit_code : exit code of compiling process
  • log : stdout and stderr of compiling

TestCache model

test cache of Example

  • src, seq : the primary key for the Example
  • exit_code : exit code of testing process
  • log : stdout and stderr of testing

Heuritstic model

Accumulated heuristics for example code execution.

  • action : heuristic type (require, compile, test)
  • target : heuristic target (file name or SHA1 of the code)
  • by : heuristic argument

It is serialized into the following string.

compile 081fe59b04... by:pseudo ...
require digest/ by:digest ...
test fa5a9799... by:random ...

See: bundled/heuristic.jnl



There are various types of sample code.

lib LibTicker
  fun on_tick(callback : (Int32, Void* ->), data : Void*)
FileUtils.ln("/usr/bin/vim", "/usr/bin/emacs")

Is this pseudo code? Is this the real code we should test? Ideally the sample code should be annotated at this point.

# @[Test]
# ```crystal
# [:foo, :bar].size # => 2
# ```

At present, we are responding each time by accumulating empirical knowledge by manual housekeeping in bundled/heuristic.jnl.

API breaking changes

Crystal often broke the stdlib API compatibility, especially Time, at each release. For example, we have an example code like this.

time = Time.utc(2016, 2, 15, 10, 20, 30)
time.to_s # => 2016-02-15 10:20:30 UTC

Our inner module CommentSpec convert this as follows.

time.to_s.should eq( Time.parse("2016-02-15 10:20:30 UTC", "%F %T %z") )

However, there is no guarantee that Time.parse and will work with the current crystal version, and there is no alias for backwards compatibility.

This is preventing the use within CI and automation.


docker compose is needed in development too.

$ make


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


  • maiha maiha - creator, maintainer
  github: maiha/crystal-examples
  version: ~> 1.3.0
License MIT
Crystal none


Dependencies 12

Development Dependencies 0

Dependents 0

Last synced .
search fire star recently