crdoc

Crystal API docs and cheat sheets in the terminal, in the spirit of Ruby's ri.

crdoc reads the same JSON that crystal docs produces. The standard library comes from https://crystal-lang.org/api/<version>/, where the version defaults to the installed compiler. Shards are built locally and kept as separate sources.

Installation

shards build --release --no-debug
cp bin/crdoc ~/bin/

The first lookup downloads the stdlib docs (about 1.3 MB) and caches them.

Usage

Lookups

Query	Shows
crdoc String	Type doc and one-line member summaries
crdoc --full String	Type doc and every member in full
crdoc 'String#size', crdoc String@size	One instance method, all overloads
crdoc String.new	Constructors, class methods and macros with that name
crdoc size	Every method named size, in columns
crdoc '#to_i', crdoc @to_i	Instance methods named to_i on any type
crdoc .new	Non-instance methods named new on any type
crdoc 'String#to_*'	Glob over member (or type) names
crdoc Memory	Types whose name ends in Memory
crdoc 'IO::Memory#puts'	Inherited members resolve through ancestors

--signatures prints one line per matching method overload, such as Random#rand(max : Float64) : Float64. It works with method queries, --find and --regex, and fails for a query that names a type, constant or topic.

@ means the same as # and needs no shell quoting. Several queries can be given at once. An unknown query prints suggestions and exits 1.

Search

crdoc --find size                  # whole word, case-insensitive
crdoc --regex '^to_[iu]\d+$' --names
crdoc --find deadlock --docs --kind method

--kind takes a comma-separated list: type, method, instance, macro, const, member, or a specific kind such as class, struct, enum, constructor or class_method.

Cheat sheets

crdoc concurrency                  # also: threads, parallel, fibers
crdoc --topics

Topics are lowercase. A lowercase query that names a topic shows the topic and lists any symbols it could also mean. A capitalized query that matches a symbol shows the symbol, so crdoc enum is the cheat sheet and crdoc Enum is the type.

Sources

crdoc --add-shard github:kemalcr/kemal
crdoc --add-shard github:plambert/guard.cr@v1.0.0
crdoc --add-shard ../my-shard
crdoc --from-lock                  # every shard in ./shard.lock, from ./lib
crdoc --sources
crdoc --refresh shard:kemal        # or --refresh stdlib
crdoc --remove-source kemal

crdoc -s 'shard:*' get             # only shard docs
crdoc -x 'shard:*' --find route    # everything but shard docs
crdoc --api-version 1.20.3 String  # another stdlib version

Adding a shard clones it into a temporary directory, installs its runtime dependencies, and runs crystal docs --format json. Only the JSON is kept.

Output

Output goes through $PAGER (default less -R) when it is taller than the terminal. --no-pager and --color=auto|always|never override this, and NO_COLOR is honored.

Files

Path	Contents
$XDG_CACHE_HOME/crdoc/stdlib/<version>/	Stdlib docs, re-fetchable
$XDG_DATA_HOME/crdoc/shards/<name>/	Shard docs and origin metadata

XDG_CACHE_HOME defaults to ~/.cache, and XDG_DATA_HOME defaults to ~/.local/share. Released stdlib versions are never refetched. master expires after a day.

Development

shards install
crystal spec -v --error-trace                  # all specs
crystal spec -v --error-trace -- --tag ~slow   # skip cheat-sheet compile checks

Specs run against fixtures in spec/fixtures/ and do not use the network. Cheat sheets live in src/crdoc/cheats/*.md, and every Crystal snippet in them must compile on its own.

Contributors

• Paul M. Lambert - creator and maintainer