Crystal: Ruby Syntax, C Speed

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# hello.cr
puts "Hello, Crystal!"

# String interpolation — identical to Ruby
name = "world"
puts "Hello, #{name}!"

# Types are inferred — no annotation needed here
x = 42
y = 3.14
puts typeof(x)  # => Int32
puts typeof(y)  # => Float64

1
2
3
4

crystal run hello.cr
# or compile to a binary:
crystal build hello.cr -o hello
./hello

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# Blocks and iterators
[1, 2, 3, 4, 5].each do |n|
  puts n * 2
end

# Block with curly braces (single expression)
[1, 2, 3].map { |n| n ** 2 }  # => [1, 4, 9]

# select / reject / reduce
evens = (1..10).select { |n| n.even? }
total = evens.reduce(0) { |sum, n| sum + n }
puts total  # => 30

# Named arguments
def greet(name : String, greeting : String = "Hello")
  "#{greeting}, #{name}!"
end

puts greet(name: "Alice")                 # => Hello, Alice!
puts greet(name: "Bob", greeting: "Hi")  # => Hi, Bob!

# Symbols
status = :ok
puts status  # => ok

# String interpolation with expressions
n = 10
puts "#{n} squared is #{n ** 2}"

# Multi-line strings
message = <<-HEREDOC
  Line one
  Line two
  HEREDOC
puts message

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# This is fine — Crystal infers x as Int32
x = 42
x = 100  # still Int32

# This is a compile error — x cannot become a String
# x = "hello"  # Error: type must be Int32, not String

# If you need a variable that holds Int32 or String, declare the union explicitly:
x : Int32 | String = 42
x = "hello"  # now this is fine

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

class Proxy
  macro method_missing(call)
    puts "Called: #{{{call.name}}}"
  end
end

p = Proxy.new
p.anything   # prints: Called: anything
p.whatever   # prints: Called: whatever
# These are generated at compile time based on usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Duck typing in Ruby: any object with a .name method works
# In Crystal: express this as a union or use responds_to?

def print_name(obj : String | Symbol)
  puts obj.to_s
end

# Or use responds_to? (checked at compile time):
def process(obj)
  if obj.responds_to?(:upcase)
    puts obj.upcase
  else
    puts obj.to_s
  end
end

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

# Non-nilable String — cannot be nil
name : String = "Alice"

# Nilable String — might be nil
maybe_name : String? = nil
maybe_name = "Bob"

# The compiler forces you to handle nil before calling String methods
def greet(name : String?)
  # This would be a compile error:
  # puts name.upcase  # Error: undefined method 'upcase' for Nil

  # Correct: guard with if
  if name
    puts name.upcase  # safe — inside the if, name is String
  else
    puts "No name given"
  end
end

greet("alice")  # ALICE
greet(nil)      # No name given

# Compact: nil-check with &. (safe navigation operator, like Ruby 2.3+)
puts maybe_name&.upcase  # prints "BOB" or nothing if nil

# Or use not_nil! to assert non-nil (raises at runtime if nil)
puts maybe_name.not_nil!.upcase

# Try: returns nil instead of raising on failure
def find_user(id : Int32) : String?
  id == 1 ? "Alice" : nil
end

user = find_user(2)
puts user.try(&.upcase) || "not found"  # not found

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

# Classes are reference types (heap allocated)
class Animal
  getter name : String
  getter sound : String

  def initialize(@name : String, @sound : String)
  end

  def speak
    "#{@name} says #{@sound}"
  end
end

# Structs are value types (stack allocated, copied on assignment)
struct Point
  getter x : Float64
  getter y : Float64

  def initialize(@x : Float64, @y : Float64)
  end

  def distance_to(other : Point) : Float64
    Math.sqrt((x - other.x) ** 2 + (y - other.y) ** 2)
  end
end

# Modules as mixins
module Serializable
  def to_json_string : String
    # simplified example
    "{\"class\": \"#{self.class.name}\"}"
  end
end

class Dog < Animal
  include Serializable

  def initialize(name : String)
    super(name, "woof")
  end
end

dog = Dog.new("Rex")
puts dog.speak           # Rex says woof
puts dog.to_json_string  # {"class": "Dog"}

p1 = Point.new(0.0, 0.0)
p2 = Point.new(3.0, 4.0)
puts p1.distance_to(p2)  # 5.0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# The compiler infers all of these:
x = 42            # Int32
y = 42_i64        # Int64
z = 3.14          # Float64
s = "hello"       # String
b = true          # Bool
arr = [1, 2, 3]   # Array(Int32)
h = {"a" => 1}    # Hash(String, Int32)

# Method return types are also inferred:
def add(a, b)
  a + b
end

result = add(1, 2)        # Int32
result2 = add(1.0, 2.0)  # Float64

# But you can (and often should at public API boundaries) be explicit:
def add_ints(a : Int32, b : Int32) : Int32
  a + b
end

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# A variable that holds Int32 or String
value : Int32 | String = 42
value = "hello"  # valid

# Methods handle unions with type narrowing:
def describe(v : Int32 | String | Bool)
  case v
  when Int32
    puts "Integer: #{v}"
  when String
    puts "String of length #{v.size}"
  when Bool
    puts "Boolean: #{v}"
  end
end

describe(42)       # Integer: 42
describe("hello")  # String of length 5
describe(true)     # Boolean: true

# Crystal infers union return types automatically:
def parse_input(s : String)
  if s == "true" || s == "false"
    s == "true"  # Bool
  elsif s.to_i?
    s.to_i       # Int32
  else
    s            # String
  end
end

# Return type is inferred as Bool | Int32 | String
result = parse_input("42")
puts typeof(result)  # Bool | Int32 | String

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

# Generic class
class Stack(T)
  def initialize
    @data = [] of T
  end

  def push(item : T) : Nil
    @data.push(item)
  end

  def pop : T
    @data.pop
  end

  def peek : T
    @data.last
  end

  def empty? : Bool
    @data.empty?
  end

  def size : Int32
    @data.size
  end
end

int_stack = Stack(Int32).new
int_stack.push(1)
int_stack.push(2)
int_stack.push(3)
puts int_stack.pop  # 3
puts int_stack.peek # 2

str_stack = Stack(String).new
str_stack.push("a")
str_stack.push("b")
puts str_stack.pop  # b

# Generic methods
def swap(a : T, b : T) : {T, T} forall T
  {b, a}
end

x, y = swap(1, 2)
puts "#{x}, #{y}"  # 2, 1

a, b = swap("hello", "world")
puts "#{a}, #{b}"  # world, hello

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# Abstract class — cannot be instantiated directly
abstract class Shape
  abstract def area : Float64
  abstract def perimeter : Float64

  def describe
    "#{self.class.name}: area=#{area.round(2)}, perimeter=#{perimeter.round(2)}"
  end
end

class Circle < Shape
  def initialize(@radius : Float64)
  end

  def area : Float64
    Math::PI * @radius ** 2
  end

  def perimeter : Float64
    2 * Math::PI * @radius
  end
end

class Rectangle < Shape
  def initialize(@width : Float64, @height : Float64)
  end

  def area : Float64
    @width * @height
  end

  def perimeter : Float64
    2 * (@width + @height)
  end
end

shapes = [Circle.new(5.0), Rectangle.new(4.0, 6.0)] of Shape
shapes.each { |s| puts s.describe }
# Circle: area=78.54, perimeter=31.42
# Rectangle: area=24.0, perimeter=20.0

# Abstract module (interface-like)
module Drawable
  abstract def draw : String
end

module Resizable
  abstract def resize(factor : Float64) : self
end

class Canvas
  include Drawable
  include Resizable

  def initialize(@width : Float64, @height : Float64)
  end

  def draw : String
    "Canvas #{@width}x#{@height}"
  end

  def resize(factor : Float64) : self
    Canvas.new(@width * factor, @height * factor)
  end
end

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# responds_to? — compile-time check, enables duck typing
def process(obj)
  {% if obj.class.has_method?(:upcase) %}
    # This branch only exists if the type has upcase at compile time
  {% end %}

  # Runtime-style usage (Crystal evaluates at compile time per type):
  if obj.responds_to?(:upcase)
    obj.upcase
  else
    obj.to_s
  end
end

# typeof — returns the type at compile time
x = 42
puts typeof(x)          # Int32
puts typeof(x + 1.0)    # Float64

arr = [1, "two", 3.0]
puts typeof(arr)         # Array(Float64 | Int32 | String)

# as — cast (raises InvalidCastException if wrong)
value : Int32 | String = 42
num = value.as(Int32)
puts num + 1  # 43

# as? — safe cast (returns nil if wrong type)
value2 : Int32 | String = "hello"
maybe_num = value2.as?(Int32)
puts maybe_num.nil?  # true
maybe_str = value2.as?(String)
puts maybe_str       # hello

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# A simple macro — expands at compile time
macro say_hello(name)
  puts "Hello, #{{{name}}}!"
end

say_hello("Crystal")  # expands to: puts "Hello, Crystal!"

# {% %} for control flow within macros
# {{ }} for AST interpolation (inserting values)
# {% %} runs at compile time but produces no output
# {{ }} produces output inserted into the generated code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

macro debug_log(message)
  {% if flag?(:debug) %}
    puts "[DEBUG] #{{{message}}}"
  {% end %}
end

debug_log("This only appears with -Ddebug flag")

# Check the type at compile time
macro print_type_info(var)
  {% puts "Variable #{var} has type #{var.class_name}" %}
end

x = 42
print_type_info(x)  # prints during compilation: Variable x has type Int32

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# Generate methods for multiple types
macro define_converters(*types)
  {% for type in types %}
    def to_{{type.id.downcase}}
      {{type}}.new(self)
    end
  {% end %}
end

class MyNumber
  def initialize(@value : Int32)
  end

  define_converters Int64, Float64, Float32
end

n = MyNumber.new(42)
# Generated methods: to_int64, to_float64, to_float32

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# record is a built-in macro that creates a simple immutable struct
record Point, x : Float64, y : Float64

p = Point.new(x: 1.0, y: 2.0)
puts p.x  # 1.0
puts p.y  # 2.0

# record generates: struct, initialize, getters, ==, to_s, clone, copy_with
p2 = p.copy_with(x: 5.0)
puts p2  # Point(@x=5.0, @y=2.0)
puts p == p2  # false

# record with methods:
record Color, r : UInt8, g : UInt8, b : UInt8 do
  def to_hex : String
    "#%02X%02X%02X" % [r, g, b]
  end

  def luminance : Float64
    0.299 * r + 0.587 * g + 0.114 * b
  end
end

red = Color.new(255, 0, 0)
puts red.to_hex     # #FF0000
puts red.luminance  # 76.245

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

class Config
  # getter — generates a reader method
  getter host : String

  # setter — generates a writer method
  setter port : Int32

  # property — generates both reader and writer
  property debug : Bool

  # getter? — generates a boolean reader with ? suffix
  getter? ssl_enabled : Bool

  def initialize
    @host = "localhost"
    @port = 8080
    @debug = false
    @ssl_enabled = false
  end
end

config = Config.new
puts config.host         # localhost
config.port = 9090
puts config.debug?       # false (would be debug without ?)
config.debug = true
puts config.ssl_enabled? # false

# Nilable with getter:
class Server
  getter? running : Bool = false
  property name : String?

  def start
    @running = true
  end
end

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# A simplified version of what JSON::Serializable does internally
macro json_fields(*fields)
  def to_json_object : Hash(String, JSON::Any::Type)
    result = {} of String => JSON::Any::Type
    {% for field in fields %}
      result[{{field.stringify}}] = @{{field}}.as(JSON::Any::Type)
    {% end %}
    result
  end

  def self.from_hash(h : Hash(String, JSON::Any::Type))
    obj = allocate
    {% for field in fields %}
      obj.@{{field}} = h[{{field.stringify}}]
    {% end %}
    obj
  end
end

# @type macro variable — refers to the current type being defined
macro inspect_type
  puts "Current type: #{@type}"
  puts "Instance vars: #{@type.instance_vars.map(&.name).join(", ")}"
end

class Person
  property name : String = ""
  property age : Int32 = 0

  inspect_type
end
# Prints during compilation:
# Current type: Person
# Instance vars: name, age

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# Build a simple DSL for defining routes
class Router
  ROUTES = {} of String => Proc(String)

  macro get(path, &block)
    ROUTES[{{path}}] = ->{ {{block.body}} }
  end

  def handle(path : String) : String
    if handler = ROUTES[path]?
      handler.call
    else
      "404 Not Found"
    end
  end
end

class MyApp < Router
  get "/hello" do
    "Hello, World!"
  end

  get "/status" do
    "OK"
  end
end

app = MyApp.new
puts app.handle("/hello")   # Hello, World!
puts app.handle("/missing") # 404 Not Found

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# spawn creates a new fiber
spawn do
  puts "Fiber 1: started"
  Fiber.yield  # yield to another fiber
  puts "Fiber 1: resumed"
end

spawn do
  puts "Fiber 2: started"
  Fiber.yield
  puts "Fiber 2: resumed"
end

# The event loop runs fibers
Fiber.yield  # give fibers a chance to run
sleep 0.1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Buffered channel
ch = Channel(Int32).new(10)

# Producer fiber
spawn do
  (1..5).each do |i|
    ch.send(i)
    puts "Sent: #{i}"
  end
  ch.close
end

# Consumer fiber
spawn do
  while value = ch.receive?
    puts "Received: #{value}"
    sleep 0.01
  end
  puts "Channel closed"
end

sleep 1  # wait for fibers to complete

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# Unbuffered (synchronous) channel — sender blocks until receiver is ready
ch = Channel(String).new

spawn do
  ch.send("ping")
  response = ch.receive
  puts "Got response: #{response}"
end

message = ch.receive
puts "Got message: #{message}"
ch.send("pong")
sleep 0.1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

require "random"

ch1 = Channel(String).new
ch2 = Channel(String).new
done = Channel(Nil).new

spawn do
  sleep Random.rand(0.1..0.3)
  ch1.send("from ch1")
end

spawn do
  sleep Random.rand(0.1..0.3)
  ch2.send("from ch2")
end

spawn do
  2.times do
    select
    when msg = ch1.receive
      puts "ch1: #{msg}"
    when msg = ch2.receive
      puts "ch2: #{msg}"
    end
  end
  done.send(nil)
end

done.receive

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

require "wait_group"

def run_worker_pool(jobs : Array(Int32), num_workers : Int32)
  job_ch = Channel(Int32).new(jobs.size)
  result_ch = Channel(String).new(jobs.size)
  wg = WaitGroup.new(num_workers)

  # Enqueue jobs
  jobs.each { |job| job_ch.send(job) }
  job_ch.close

  # Spawn workers
  num_workers.times do |worker_id|
    spawn do
      while job = job_ch.receive?
        # Simulate work
        sleep 0.01
        result_ch.send("Worker #{worker_id} processed job #{job}")
      end
      wg.done
    end
  end

  # Collect results in a separate fiber
  spawn do
    wg.wait
    result_ch.close
  end

  # Drain results
  while result = result_ch.receive?
    puts result
  end
end

run_worker_pool((1..20).to_a, 4)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

require "mutex"
require "wait_group"

# Mutex for shared state
counter = 0
mutex = Mutex.new
wg = WaitGroup.new(100)

100.times do |i|
  spawn do
    mutex.synchronize do
      counter += 1
    end
    wg.done
  end
end

wg.wait
puts "Counter: #{counter}"  # 100

# Mutex with reentrant option
class SafeCache(K, V)
  def initialize
    @data = {} of K => V
    @mutex = Mutex.new
  end

  def set(key : K, value : V) : Nil
    @mutex.synchronize { @data[key] = value }
  end

  def get(key : K) : V?
    @mutex.synchronize { @data[key]? }
  end

  def delete(key : K) : Nil
    @mutex.synchronize { @data.delete(key) }
  end
end

cache = SafeCache(String, Int32).new
cache.set("hits", 0)

1
2
3
4
5

# Compile with multi_thread support
crystal build --release -Dpreview_mt app.cr

# Or set at runtime via environment variable
CRYSTAL_WORKERS=4 ./app

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# With preview_mt, fibers can run on multiple OS threads in parallel
# The channel API remains the same — Crystal handles the synchronization

require "wait_group"

# CPU-bound parallel work
results = Array(Int64).new(8, 0_i64)
mutex = Mutex.new
wg = WaitGroup.new(8)

8.times do |i|
  spawn do
    # Heavy computation
    sum = (1..1_000_000).reduce(0_i64) { |acc, n| acc + n }
    mutex.synchronize { results[i] = sum }
    wg.done
  end
end

wg.wait
puts results.sum  # sum of all partial sums

1
2
3
4
5
6
7
8

# Standard release build
crystal build --release app.cr

# With link-time optimization (slower compile, faster binary)
crystal build --release --lto=thin app.cr

# Target-specific optimization (for the current CPU)
crystal build --release --mcpu native app.cr

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# fib.cr
def fib(n : Int64) : Int64
  return n if n <= 1
  fib(n - 1) + fib(n - 2)
end

start = Time.monotonic
result = fib(45)
elapsed = Time.monotonic - start

puts "fib(45) = #{result}"
puts "Time: #{elapsed.total_milliseconds.round(1)}ms"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# fib.rb
def fib(n)
  return n if n <= 1
  fib(n - 1) + fib(n - 2)
end

start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
result = fib(45)
elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start

puts "fib(45) = #{result}"
puts "Time: #{(elapsed * 1000).round(1)}ms"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Minimal HTTP server for benchmarking
require "http/server"

server = HTTP::Server.new do |context|
  context.response.content_type = "text/plain"
  context.response.print "Hello, World!"
end

server.bind_tcp("0.0.0.0", 8080)
puts "Listening on http://0.0.0.0:8080"
server.listen

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# This iterator chain:
result = (1..1_000_000)
  .select { |n| n % 2 == 0 }
  .map { |n| n * n }
  .first(10)

# Compiles to roughly equivalent code as this manual loop:
result2 = [] of Int32
count = 0
(1..1_000_000).each do |n|
  break if count == 10
  if n % 2 == 0
    result2 << n * n
    count += 1
  end
end

# Both produce the same binary output with --release

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

require "http/server"
require "http/client"
require "json"

# HTTP Server with routing
server = HTTP::Server.new do |ctx|
  req = ctx.request
  res = ctx.response

  case {req.method, req.path}
  when {"GET", "/"}
    res.content_type = "application/json"
    res.print({status: "ok", message: "Crystal API"}.to_json)

  when {"GET", "/users"}
    users = [{id: 1, name: "Alice"}, {id: 2, name: "Bob"}]
    res.content_type = "application/json"
    res.print(users.to_json)

  when {"POST", "/echo"}
    body = req.body.try(&.gets_to_end) || ""
    res.content_type = "text/plain"
    res.print("Echo: #{body}")

  else
    res.status = HTTP::Status::NOT_FOUND
    res.print("Not found")
  end
end

address = server.bind_tcp(8080)
puts "Listening on #{address}"
server.listen

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

require "http/client"
require "json"

# HTTP Client
response = HTTP::Client.get("https://httpbin.org/json")
puts response.status_code  # 200
puts response.body[0..100]

# With headers and timeout
HTTP::Client.new("api.example.com", tls: true) do |client|
  client.connect_timeout = 5.seconds
  client.read_timeout = 30.seconds

  response = client.get("/v1/resource",
    headers: HTTP::Headers{"Authorization" => "Bearer token123"})

  puts response.status
  puts response.body
end

# POST with JSON body
payload = {name: "Alice", age: 30}.to_json
response = HTTP::Client.post(
  "https://httpbin.org/post",
  headers: HTTP::Headers{"Content-Type" => "application/json"},
  body: payload
)
puts response.status_code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

require "json"

# Annotation-based JSON serialization (zero runtime reflection)
class User
  include JSON::Serializable

  property id : Int32
  property name : String
  property email : String

  @[JSON::Field(key: "created_at")]
  property created_at : Time

  @[JSON::Field(ignore: true)]
  property password_hash : String = ""

  def initialize(@id, @name, @email, @created_at = Time.utc)
  end
end

# Serialize to JSON
user = User.new(1, "Alice", "alice@example.com")
json_str = user.to_json
puts json_str
# {"id":1,"name":"Alice","email":"alice@example.com","created_at":"..."}

# Deserialize from JSON
json = %({ "id": 2, "name": "Bob", "email": "bob@example.com", "created_at": "2025-01-01T00:00:00Z" })
user2 = User.from_json(json)
puts user2.name  # Bob

# Array of users
json_array = "[#{json_str}, #{json_str}]"
users = Array(User).from_json(json_array)
puts users.size  # 2

# JSON::Any for dynamic JSON
raw = JSON.parse(%({ "x": 1, "y": [2, 3] }))
puts raw["x"].as_i     # 1
puts raw["y"][0].as_i  # 2

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

require "db"
require "pg"  # or sqlite3, mysql2

# Generic DB interface — works with any driver
DB.open("postgres://user:pass@localhost:5432/mydb") do |db|
  # Create table
  db.exec "CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100),
    email VARCHAR(200)
  )"

  # Insert
  db.exec "INSERT INTO users (name, email) VALUES ($1, $2)",
    "Alice", "alice@example.com"

  # Query single row
  user = db.query_one "SELECT id, name, email FROM users WHERE name = $1",
    "Alice",
    as: {Int32, String, String}
  id, name, email = user
  puts "Found: #{name} (#{email})"

  # Query multiple rows
  db.query "SELECT id, name FROM users" do |rs|
    rs.each do
      id = rs.read(Int32)
      name = rs.read(String)
      puts "  #{id}: #{name}"
    end
  end

  # With transaction
  db.transaction do |tx|
    conn = tx.connection
    conn.exec "INSERT INTO users (name, email) VALUES ($1, $2)", "Bob", "bob@example.com"
    conn.exec "INSERT INTO users (name, email) VALUES ($1, $2)", "Carol", "carol@example.com"
    # Automatically committed; rolls back on exception
  end
end

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

require "file"

# Reading and writing files
File.write("/tmp/hello.txt", "Hello, Crystal!\n")
contents = File.read("/tmp/hello.txt")
puts contents.chomp  # Hello, Crystal!

# Line by line
File.each_line("/tmp/hello.txt") do |line|
  puts line.upcase
end

# File info
info = File.info("/tmp/hello.txt")
puts "Size: #{info.size} bytes"
puts "Modified: #{info.modification_time}"

# Path manipulation
path = Path.new("/home/user/projects/app/src/main.cr")
puts path.basename        # main.cr
puts path.stem            # main
puts path.extension       # .cr
puts path.dirname         # /home/user/projects/app/src
puts path.parent          # /home/user/projects/app/src

# Directory operations
Dir.mkdir_p("/tmp/crystal_test/nested")

Dir.each_child("/tmp") do |entry|
  puts entry
end

# Glob
Dir.glob("/tmp/**/*.cr").each do |file|
  puts file
end

# Temp files
File.tempfile("crystal", ".tmp") do |f|
  f.print("temporary data")
  puts f.path
end  # automatically deleted

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

require "log"

# Configure backend
Log.setup do |config|
  backend = Log::IOBackend.new(STDOUT)
  config.bind("*", :debug, backend)
end

# Module-scoped logger
Log.for("myapp.http").info { "Server started on port 8080" }
Log.for("myapp.db").debug { "Query executed in 2ms" }

# Structured logging
Log.for("myapp").error(exception: RuntimeError.new("oops")) do |entry|
  entry.emit("Database error", query: "SELECT * FROM users", duration_ms: 500)
end

# In a class
class MyService
  Log = ::Log.for(self)

  def process(item : String)
    Log.debug { "Processing: #{item}" }
    # do work
    Log.info { "Processed: #{item}" }
  rescue ex
    Log.error(exception: ex) { "Failed to process: #{item}" }
  end
end

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# spec/user_spec.cr
require "spec"

class Calculator
  def add(a : Int32, b : Int32) : Int32
    a + b
  end

  def divide(a : Float64, b : Float64) : Float64
    raise ArgumentError.new("Division by zero") if b == 0.0
    a / b
  end
end

describe Calculator do
  subject { Calculator.new }

  describe "#add" do
    it "adds two positive numbers" do
      subject.add(2, 3).should eq(5)
    end

    it "handles negative numbers" do
      subject.add(-1, 1).should eq(0)
    end
  end

  describe "#divide" do
    it "divides correctly" do
      result = subject.divide(10.0, 4.0)
      result.should be_close(2.5, 0.001)
    end

    it "raises on division by zero" do
      expect_raises(ArgumentError, "Division by zero") do
        subject.divide(5.0, 0.0)
      end
    end
  end
end

# Run with: crystal spec

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

require "option_parser"

# Build a CLI tool with argument parsing
options = {
  host: "localhost",
  port: 8080,
  verbose: false,
  output: nil.as(String?),
}

parser = OptionParser.new do |p|
  p.banner = "Usage: myapp [options]"

  p.on("-h HOST", "--host=HOST", "Hostname to connect to") do |h|
    options = options.merge(host: h)
  end

  p.on("-p PORT", "--port=PORT", "Port number") do |port|
    options = options.merge(port: port.to_i)
  end

  p.on("-v", "--verbose", "Enable verbose output") do
    options = options.merge(verbose: true)
  end

  p.on("-o FILE", "--output=FILE", "Output file") do |f|
    options = options.merge(output: f)
  end

  p.on("--help", "Show this help") do
    puts p
    exit
  end

  p.invalid_option do |flag|
    STDERR.puts "ERROR: #{flag} is not a valid option."
    STDERR.puts p
    exit(1)
  end
end

parser.parse

puts "Connecting to #{options[:host]}:#{options[:port]}"
puts "Verbose: #{options[:verbose]}"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# Bind to C's standard library functions
@[Link("c")]
lib LibC
  # Function binding
  fun puts(s : UInt8*) : Int32
  fun strlen(s : UInt8*) : SizeT
  fun malloc(size : SizeT) : Void*
  fun free(ptr : Void*) : Void

  # Type aliases
  alias SizeT = UInt64  # on 64-bit systems

  # C struct
  struct Timespec
    tv_sec : Int64
    tv_nsec : Int64
  end

  fun clock_gettime(clk_id : Int32, tp : Timespec*) : Int32

  CLOCK_REALTIME = 0
  CLOCK_MONOTONIC = 1
end

# Use the binding
ts = LibC::Timespec.new
LibC.clock_gettime(LibC::CLOCK_MONOTONIC, pointerof(ts))
puts "Seconds: #{ts.tv_sec}, Nanoseconds: #{ts.tv_nsec}"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# sqlite3_binding.cr
@[Link("sqlite3")]
lib LibSQLite3
  alias Database = Void*
  alias Statement = Void*
  alias Callback = (Void*, Int32, UInt8**, UInt8**) -> Int32

  SQLITE_OK   = 0
  SQLITE_ROW  = 100
  SQLITE_DONE = 101

  fun open(filename : UInt8*, db : Database*) : Int32
  fun close(db : Database) : Int32
  fun prepare_v2(
    db : Database,
    sql : UInt8*,
    nbyte : Int32,
    stmt : Statement*,
    tail : UInt8**
  ) : Int32
  fun step(stmt : Statement) : Int32
  fun column_count(stmt : Statement) : Int32
  fun column_text(stmt : Statement, col : Int32) : UInt8*
  fun column_int(stmt : Statement, col : Int32) : Int32
  fun column_double(stmt : Statement, col : Int32) : Float64
  fun column_type(stmt : Statement, col : Int32) : Int32
  fun finalize(stmt : Statement) : Int32
  fun errmsg(db : Database) : UInt8*
  fun exec(
    db : Database,
    sql : UInt8*,
    callback : Callback,
    arg : Void*,
    errmsg : UInt8**
  ) : Int32

  SQLITE_INTEGER = 1
  SQLITE_FLOAT   = 2
  SQLITE_TEXT    = 3
  SQLITE_BLOB    = 4
  SQLITE_NULL    = 5
end

# Wrapper class
class SQLiteDB
  def initialize(path : String)
    @db = uninitialized LibSQLite3::Database
    rc = LibSQLite3.open(path, pointerof(@db))
    raise "Cannot open database: #{error_msg}" if rc != LibSQLite3::SQLITE_OK
  end

  def exec(sql : String) : Nil
    errmsg = Pointer(UInt8).null
    rc = LibSQLite3.exec(@db, sql, nil, nil, pointerof(errmsg))
    raise "SQL error: #{String.new(errmsg)}" if rc != LibSQLite3::SQLITE_OK
  end

  def query(sql : String) : Array(Array(String))
    stmt = uninitialized LibSQLite3::Statement
    rc = LibSQLite3.prepare_v2(@db, sql, -1, pointerof(stmt), nil)
    raise "Prepare failed: #{error_msg}" if rc != LibSQLite3::SQLITE_OK

    rows = [] of Array(String)
    while LibSQLite3.step(stmt) == LibSQLite3::SQLITE_ROW
      cols = LibSQLite3.column_count(stmt)
      row = (0...cols).map do |i|
        text = LibSQLite3.column_text(stmt, i)
        text.null? ? "NULL" : String.new(text)
      end
      rows << row
    end

    LibSQLite3.finalize(stmt)
    rows
  end

  def close
    LibSQLite3.close(@db)
  end

  private def error_msg : String
    String.new(LibSQLite3.errmsg(@db))
  end
end

# Usage
db = SQLiteDB.new(":memory:")
db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
db.exec("INSERT INTO users VALUES (1, 'Alice')")
db.exec("INSERT INTO users VALUES (2, 'Bob')")
rows = db.query("SELECT * FROM users")
rows.each { |row| puts row.join(", ") }
# 1, Alice
# 2, Bob
db.close

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# C unions in Crystal
lib LibExample
  union Number
    i : Int32
    f : Float32
    bytes : UInt8[4]
  end

  struct ComplexStruct
    flag : Int32
    data : Number
    next : ComplexStruct*  # pointer to self
  end
end

# Pointer arithmetic (use carefully)
ptr = Pointer(Int32).malloc(4)
4.times { |i| ptr[i] = i * 10 }
4.times { |i| puts ptr[i] }  # 0, 10, 20, 30
ptr.free

# Convert between Crystal String and C char*
def c_string_demo
  crystal_str = "Hello from Crystal"
  # Crystal String to C char*
  crystal_str.to_unsafe  # returns UInt8*

  # C char* to Crystal String
  c_ptr = crystal_str.to_unsafe
  back_to_crystal = String.new(c_ptr)
  puts back_to_crystal
end

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

name: my_api
version: 0.1.0
description: A Crystal API service

authors:
  - Your Name <you@example.com>

crystal: ">= 1.10.0"

license: MIT

dependencies:
  kemal:
    github: kemalcr/kemal
    version: "~> 1.3"

  jennifer:
    github: imdrasil/jennifer.cr
    version: "~> 0.12"

  pg:
    github: will/crystal-pg
    version: "~> 0.28"

  redis:
    github: stefanwille/crystal-redis
    version: "~> 2.9"

development_dependencies:
  ameba:
    github: crystal-ameba/ameba
    version: "~> 1.5"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Install dependencies
shards install

# Update dependencies
shards update

# Check for outdated shards
shards check

# Build the project
shards build

# Build a specific target
shards build my_api --release

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# shard.yml dependency: kemal
require "kemal"

# Middleware
before_all do |env|
  env.response.headers["X-Powered-By"] = "Crystal/Kemal"
end

# Routes
get "/" do
  "Hello, Kemal!"
end

get "/users/:id" do |env|
  id = env.params.url["id"].to_i
  # fetch from DB in real app
  {id: id, name: "User #{id}"}.to_json
end

post "/users" do |env|
  body = env.request.body.try(&.gets_to_end) || ""
  data = JSON.parse(body)
  # create user in real app
  env.response.status_code = 201
  {id: 999, name: data["name"]}.to_json
end

# Static files
serve_static({"gzip" => true, "dir_listing" => false})

# Error handling
error 404 do
  "Route not found"
end

error 500 do |env, err|
  env.response.content_type = "application/json"
  {error: err.message}.to_json
end

Kemal.run(port: 3000)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Lucky uses a strongly-typed routing system
# In src/actions/users/show.cr
class Users::Show < BrowserAction
  get "/users/:user_id" do
    user = UserQuery.new.id(user_id).first
    html ShowPage, user: user
  end
end

# Type-safe query builder (no string SQL)
class UserQuery < User::BaseQuery
  def admins
    role("admin")
  end

  def recently_active
    created_at.gt(1.week.ago)
  end
end

# Usage
users = UserQuery.new.admins.recently_active.select

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

require "jennifer"
require "jennifer/adapter/postgres"

Jennifer::Config.configure do |conf|
  conf.host = "localhost"
  conf.db = "myapp_development"
  conf.user = "postgres"
  conf.password = "secret"
  conf.adapter = "postgres"
end

class User < Jennifer::Model::Base
  with_timestamps

  mapping(
    id: Primary32,
    name: String,
    email: String,
    role: {type: String, default: "user"},
    created_at: Time?,
    updated_at: Time?,
  )

  has_many :posts, Post

  validates_presence :name, :email
  validates_uniqueness :email
  validates_format :email, /\A[\w+\-.]+@[a-z\d\-.]+\.[a-z]+\z/i
end

class Post < Jennifer::Model::Base
  with_timestamps

  mapping(
    id: Primary32,
    title: String,
    body: String,
    user_id: Int32,
    created_at: Time?,
    updated_at: Time?,
  )

  belongs_to :user, User
end

# Query interface
admin_users = User.where { _role == "admin" }.order(name: :asc).to_a
puts admin_users.map(&.name)

user = User.find!(1)
user.posts.where { _created_at > 1.week.ago }.each do |post|
  puts post.title
end

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

require "athena"

@[ARTA::Prefix("api/v1")]
class UserController < ATH::Controller
  @[ARTA::Get("/users")]
  def list_users : Array(User)
    UserRepository.all
  end

  @[ARTA::Get("/users/:id")]
  def show_user(id : Int32) : User
    UserRepository.find(id) || raise ATH::Exceptions::NotFound.new("User #{id} not found")
  end

  @[ARTA::Post("/users")]
  @[ATHA::View(status: HTTP::Status::CREATED)]
  def create_user(request : ATH::Request) : User
    user_data = ATH::Serializer.deserialize(UserCreateDTO, request.body.not_nil!, :json)
    UserRepository.create(user_data)
  end
end

ATH.run

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# Run directly (compiles in temp dir, slower startup, no optimization)
crystal run app.cr

# Compile to binary (debug mode, fast compile)
crystal build app.cr -o app

# Compile with optimizations (slower compile, faster binary)
crystal build --release app.cr -o app

# Show compiler progress
crystal build --progress app.cr

# Show generated LLVM IR (useful for understanding optimization)
crystal build --emit llvm-ir app.cr
cat app.ll | head -50

# Show generated assembly
crystal build --emit asm app.cr

# Link-time optimization (best for final production builds)
crystal build --release --lto=thin app.cr

# Cross-compile (generate LLVM IR for another target, link on target)
crystal build --cross-compile --target x86_64-linux-musl app.cr
# Then on the target: cc app.o -o app $(crystal env CRYSTAL_PATH)/src/ext/libcrystal.a -lpcre2-8 -lgc -lpthread -lm -levent -lrt -ldl

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# spec/calculator_spec.cr
require "spec"
require "../src/calculator"

describe Calculator do
  it "adds numbers" do
    Calculator.add(2, 3).should eq(5)
  end

  it "handles floats" do
    Calculator.add(1.5, 2.5).should be_close(4.0, 0.001)
  end

  pending "handles complex numbers" do
    # Not yet implemented
  end
end

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Run all specs
crystal spec

# Run a specific file
crystal spec spec/calculator_spec.cr

# Run a specific line
crystal spec spec/calculator_spec.cr:10

# Verbose output
crystal spec --verbose

# With release mode (rare, for performance testing)
crystal spec --release

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21