module

Emojis::Cache

On-disk cache of emoji SVGs that aren't part of the curated set embedded at compile time. Lets the consumer extend coverage to the full Twemoji catalogue (~4000 SVG, ~18 MB) without bloating every binary that depends on this shard.

Two ways to populate the cache :

  1. From your own Crystal app, via the API (no CLI needed) :

require "emojis"

Pull every Twemoji SVG into the user-level cache.

Emojis::Cache.pull

…or override the source (private mirror, NAS, Nexus, etc.)

Emojis::Cache.pull(source: "https://nas.aloli.local/twemoji/svg")

…or write to a system-wide cache (needs root, useful for

multi-user setups, e.g. a FreeBSD server provisioned via

beryl).

Emojis::Cache.pull(system: true)

Inspection

Emojis::Cache.dir # => "/Users/.../Library/Caches/emojis/svg" Emojis::Cache.size # => 4001 (number of cached SVGs) Emojis::Cache.populated? # => true once .pull has run


2. **From the command line** :

    $ emojis pull                                   # default source
    $ emojis pull --source https://example/svg/     # custom source
    $ emojis pull --system                          # system-wide

**Cache location** (XDG Base Directory + macOS convention) :

* Linux/FreeBSD : `$XDG_CACHE_HOME/emojis/svg/`
               (default `~/.cache/emojis/svg/`)
* macOS         : `~/Library/Caches/emojis/svg/`
* System-wide   : `/var/cache/emojis/svg/`
               (override via `CRYSTAL_EMOJIS_CACHE_DIR` env var)

Constants

DEFAULT_SOURCE = "https://raw.githubusercontent.com/jdecked/twemoji/main/assets/svg"

Default upstream source for SVG downloads. Switch via the source: keyword in .pull to point at a private mirror.

Class methods

dir(system : Bool = false) : String

Returns the directory where the cache is read from / written to. Honours the CRYSTAL_EMOJIS_CACHE_DIR env var if set, otherwise computes the XDG/macOS-conventional path.

Source
populated?

true once the cache has been populated at least once (any SVG present).

Source
pull(source : String = DEFAULT_SOURCE, system : Bool = false) : Int32

Downloads every Twemoji SVG into the cache directory.

The default source is the upstream Twemoji repository on GitHub. Override with source: to fetch from a private mirror (your NAS, your Nexus, an S3 bucket, …).

The cache lookup itself is dumb : whatever <key>.svg files are present in the cache directory will be served by .svg. So you can also populate the cache by other means (rsync, tar -xf, etc.) — .pull is just one provided way.

Returns the number of SVGs successfully downloaded.

Source
size

Counts the SVG files currently in the cache directory. Returns 0 when the cache directory does not exist.

Source
svg(key : String) : String | Nil

Returns the cached SVG for key (lowercase-hex codepoint key, e.g. "1f984" for 🦄), or nil when not cached.

Source