# The Sidef Programming Language

<div align="center">

```
            **   **         ****   *           *********   *********
          * * ** * *        ****   **          ** ** **    ** ** **
           **   **          ****   ***         *********   *  *  *
  **        **        **    ****   *  *        ******      ******
* * *     * * *     * * *   ****   ** **       ** **       ** **
 **        **        **     ****   ******      ******      *  *
       **   **              ****   *  *  *     *********   ***
     * * ** * *             ****   ** ** **    ** ** **    **
      **   **               ****   *********   *********   *
```

**A modern, high-level programming language for versatile general-purpose applications**

[Website](https://github.com/trizen/sidef) • [Tutorial](https://github.com/trizen/sidef/blob/master/SIDEF_BEGINNER_GUIDE.md) • [Documentation](https://trizen.gitbook.io/sidef-lang/) • [Try Online](https://tio.run/#sidef) • [Discussions](https://github.com/trizen/sidef/discussions)

[![CPAN](https://img.shields.io/badge/CPAN-Sidef-blue)](https://metacpan.org/release/Sidef)
[![Perl](https://img.shields.io/badge/Perl-5.18%2B-blue)](https://www.perl.org/)
[![License](https://img.shields.io/badge/License-Artistic%202.0-green.svg)](https://www.perlfoundation.org/artistic-license-20.html)

</div>

---

## 🌟 What is Sidef?

Sidef is a modern, expressive programming language that combines the elegance of Ruby, the versatility of Raku, and the mathematical power of a built-in computer algebra system. It features **exact rational arithmetic by default**, an extensive **number theory library** (1,000+ functions), and seamless **Perl module integration** — making it equally at home for scripting, mathematical research, and general-purpose programming.

```ruby
# Exact rational arithmetic — no floating-point surprises
say (1/3 + 1/6)         #=> 1/2

# Built-in number theory
say (2**127 - 1)        #=> 170141183460469231731687303715884105727 (Mersenne prime)
say factor(2**128 + 1)  #=> [59649589127497217, 5704689200685129054721]

# Expressive, concise syntax
say 29.primes.map{.square}     #=> [4, 9, 25, 49, 121, 169, 289, 361, 529, 841]
```

## 🎯 Who is Sidef for?

Sidef is an excellent choice for:

- Mathematical research and experimentation
- Computational number theory and cryptography
- Project Euler and competitive programming
- Scientific computing and computer algebra
- Rapid scripting and general-purpose automation
- Algorithm prototyping
- Perl developers seeking a higher-level language

## 🏆 Why choose Sidef?

| Feature | Sidef | Python | Ruby |
|---|:---:|:---:|:---:|
| Exact rational arithmetic by default | ✅ | ❌ | ❌ |
| Arbitrary-precision integers | ✅ | ✅ | ✅ |
| Extensive built-in number theory | ✅ | ❌ | ❌ |
| Computer algebra features | ✅ | ❌ | ❌ |
| Multiple dispatch | ✅ | ❌ | Limited |
| Perl interoperability | ✅ | ❌ | ❌ |

## ✨ Featured Capabilities

- 🔢 Exact arithmetic by default
- 🧮 Built-in computer algebra
- 🔬 1,000+ number theory functions
- ♾ Lazy evaluation and infinite sequences
- 🧠 Pattern matching and multiple dispatch
- 📐 Matrices, polynomials and Gaussian integers
- ⚡ Arbitrary-precision arithmetic via GMP/MPFR/MPC
- 📦 Seamless Perl module interoperability
- 🖥 Interactive REPL with built-in help


## 🚀 Quick Start

### Prerequisites

Sidef requires **Perl 5.18+** and the following C libraries:

| Library | Purpose |
|---------|---------|
| [GMP](https://gmplib.org/) | Big integers and rationals |
| [MPFR](https://www.mpfr.org/) | Arbitrary-precision floats |
| [MPC](https://www.multiprecision.org/mpc/) | Arbitrary-precision complex numbers |

**Debian/Ubuntu:**
```bash
sudo apt-get install libgmp-dev libmpfr-dev libmpc-dev
```

**Arch Linux:**
```bash
sudo pacman -S gmp mpfr libmpc
```

**Termux:**
```bash
pkg install perl make clang libgmp libmpfr libmpc
```

### Installation

**Via CPAN:**
```bash
cpan Sidef
# or (skip tests for faster install):
cpan -T Sidef
# or with cpanminus:
cpanm Sidef
```

**Build from source:**
```bash
git clone https://github.com/trizen/sidef.git
cd sidef
perl Makefile.PL
make
make test
make install
```

**Via AUR:**
```bash
trizen -S sidef
```

**Platform packages:**
- **Arch Linux**: [AUR package](https://aur.archlinux.org/packages/sidef/)
- **Slackware**: [SlackBuilds](https://slackbuilds.org/repository/15.0/perl/perl-Sidef/)
- **Other systems**: See [pkgs.org](https://pkgs.org/download/perl-Sidef)

### Hello World

```ruby
say "Hello, World!"
```

```bash
sidef hello.sf
sidef -E 'say "Hello, World!"'
sidef -i            # start the REPL
```

### Try It Online

Experiment with Sidef instantly at **[Try It Online](https://tio.run/#sidef)** without any installation.

## 🔤 Language at a Glance

### Variables and Types

```ruby
var name   = "Sidef"               # String
var num    = 42                    # Number (exact integer)
var ratio  = 3/7                   # Number (exact rational)
var arr    = [1, 2, 3]             # Array
var hash   = Hash(a => 1, b => 2)  # Hash
var block  = {|n| n.is_prime }     # Block
```

### Functions and Pattern Matching

```ruby
func greet(name) { "Hello, #{name}!" }
say greet("world")    #=> Hello, world!

# Multi-dispatch / pattern matching
func fib({|n| n == 0 }) { 0 }
func fib({|n| n == 1 }) { 1 }
func fib(n) { fib(n-1) + fib(n-2) }

say fib(10)    #=> 55
```

### Object-Oriented Programming

```ruby
class Animal(name, sound) {
    method speak { say "#{name} says #{sound}!" }
}

class Dog(name, sound="woof") < Animal {
    method fetch { say "#{name} fetches the ball!" }
}

var d = Dog("Rex")
d.speak    #=> Rex says woof!
d.fetch    #=> Rex fetches the ball!
```

### Functional Programming

```ruby
var nums = 1..10   # RangeNumber object

# Map, filter, reduce
var evens   = nums.grep { .is_even }              #=> [2, 4, 6, 8, 10]
var squares = nums.map  { |n| n**2 }              #=> [1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
var total   = nums.reduce { |a, b| a + b }        #=> 55

say evens
say squares
say total
```

### Number Theory

```ruby
say primes(50, 100)          # array of primes in range [50, 100]
say prime_count(10**9)       # number of primes up to 10^9
say prime(100)               # 100th prime => 541
say 12.divisors              # [1, 2, 3, 4, 6, 12]
say euler_phi(100)           # Euler's totient => 40
say gcd(48, 18)              # => 6
say is_prime(2**521 - 1)     # Mersenne prime check => true
```

### Lazy Evaluation

```ruby
# Infinite lazy list of primes
var lazy_primes = (2..Inf -> lazy.grep { .is_prime })
say lazy_primes.first(10)    #=> [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
```

## ⌨️ Command-Line Reference

```
sidef [options] [script.sf] [script-arguments]
```

| Flag | Description |
|------|-------------|
| `-E 'code'` | Execute a one-line program |
| `-e 'code'` | Alias for `-E` |
| `-i [file]` | Start the interactive REPL (optionally loading a file) |
| `-c` | Compile script to a stand-alone Perl program |
| `-C` | Check syntax only (parse without execution) |
| `-r` | Deparse program back to Sidef code |
| `-R lang` | Deparse to another language (`perl`, `sidef`) |
| `-P int` | Set floating-point precision in bits (default: 192) |
| `-O level` | Optimization level: `0` (none), `1` (recommended), `2` (max) |
| `-s` | Enable precompilation (cache compiled code) |
| `-t` | Test mode: treat all arguments as script files |
| `-D` | Dump the Abstract Syntax Tree (AST) |
| `-H` | Interactive help mode for exploring documentation |

**Examples:**
```bash
sidef -E 'say 10.of { |i| i**2 }'            # one-liner
sidef -i                                     # start REPL
sidef -i script.sf                           # run script in REPL
sidef -C script.sf                           # syntax check
sidef -c -o output.pl script.sf              # compile to Perl
sidef -P 400 -E 'say sqrt(2)'                # 400-bit precision
sidef -O1 script.sf                          # with optimization
sidef -r script.sf                           # deparse to Sidef
sidef -t tests/*.sf                          # run test files
```

## 🖥️ Interactive Mode (REPL)

Start the REPL with `sidef -i`:

```
$ sidef -i
sidef> say "Hello!"
Hello!
sidef> x = 2**64
18446744073709551616
sidef> x.is_prime
false
sidef> is_prime(2**127 - 1)
true
sidef> 1..10 -> map { .square }.sum
385
sidef> quit
```

Use `-H` to open interactive documentation help:
```bash
sidef -H
```

## 🎯 Code Examples

### Classes and Inheritance

```ruby
class Shape {
    method area { die "Not implemented" }
    method describe { say "I am a #{self.class} with area #{self.area}" }
}

class Circle(r) < Shape {
    method area { Num.pi * r**2 }
}

class Rectangle(w, h) < Shape {
    method area { w * h }
}

Circle(5).describe        #=> I am a Circle with area 78.539...
Rectangle(4, 6).describe  #=> I am a Rectangle with area 24
```

### Functional Array Processing

```ruby
# FizzBuzz in one line
say (1..20 -> map { |n|
    n%%15 ? "FizzBuzz" : (n%%3 ? "Fizz" : (n%%5 ? "Buzz" : n))
})

# Pipeline style
(1..50).grep { .is_prime } \
       .map  { .square } \
       .first(5) \
       .say    #=> [4, 9, 25, 49, 121]
```

### Number Theory One-Liners

```ruby
say 100.by { .is_prime }              # first 100 primes
say sum(1..100)                       #=> 5050
say prod(1..10)                       #=> 3628800  (10!)
say { .euler_phi }.map(1..10)         #=> [1, 1, 2, 2, 4, 2, 6, 4, 6, 4]
```

### The Y Combinator

Demonstrating functional programming with the [Y combinator](https://en.wikipedia.org/wiki/Fixed-point_combinator#Fixed-point_combinators_in_lambda_calculus):

```ruby
var y = ->(f) {->(g) {g(g)}(->(g) { f(->(*args) {g(g)(args...)})})}

var fac = ->(f) { ->(n) { n < 2 ? 1 : (n * f(n-1)) } }
say 10.of { |i| y(fac)(i) }     #=> [1, 1, 2, 6, 24, 120, 720, 5040, 40320, 362880]

var fib = ->(f) { ->(n) { n < 2 ? n : (f(n-2) + f(n-1)) } }
say 10.of { |i| y(fib)(i) }     #=> [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
```

### Sierpinski Triangle

ASCII generation of the [Sierpinski triangle](https://en.wikipedia.org/wiki/Sierpinski_triangle):

```ruby
func sierpinski_triangle(n) {
    var triangle = ['*']
    { |i|
        var sp = (' ' * 2**i)
        triangle = (triangle.map {|x| sp + x + sp} +
                    triangle.map {|x| x + ' ' + x})
    } * n
    triangle.join("\n")
}

say sierpinski_triangle(4)
```

<details>
<summary>Show Output</summary>

```text
               *
              * *
             *   *
            * * * *
           *       *
          * *     * *
         *   *   *   *
        * * * * * * * *
       *               *
      * *             * *
     *   *           *   *
    * * * *         * * * *
   *       *       *       *
  * *     * *     * *     * *
 *   *   *   *   *   *   *   *
* * * * * * * * * * * * * * * *
```
</details>

### Mandelbrot Set

ASCII visualization of the [Mandelbrot set](https://en.wikipedia.org/wiki/Mandelbrot_set):

```ruby
func mandelbrot(z, r=20) {
    var c = z
    r.times {
        z = (z*z + c)
        return true if (z.abs > 2)
    }
    return false
}

for y in (1 `downto` -1 `by` 0.05) {
    for x in (-2 `upto` 0.5 `by` 0.0315) {
        print(mandelbrot(Complex(x, y)) ? ' ' : '#')
    }
    print "\n"
}
```

<details>
<summary>Show Output</summary>

```text

                                                            #
                                                        #  ###  #
                                                        ########
                                                       #########
                                                         ######
                                             ##    ## ############  #
                                              ### ###################      #
                                              #############################
                                              ############################
                                          ################################
                                           ################################
                                         #################################### #
                          #     #        ###################################
                          ###########    ###################################
                           ###########   #####################################
                         ############## ####################################
                        ####################################################
                     ######################################################
#########################################################################
                     ######################################################
                        ####################################################
                         ############## ####################################
                           ###########   #####################################
                          ###########    ###################################
                          #     #        ###################################
                                         #################################### #
                                           ################################
                                          ################################
                                              ############################
                                              #############################
                                              ### ###################      #
                                             ##    ## ############  #
                                                         ######
                                                       #########
                                                        ########
                                                        #  ###  #
                                                            #

```
</details>

## ⚡ Performance

Although Sidef is a high-level language, its numerical core is powered by highly optimized native libraries including [GMP](https://gmplib.org/), [MPFR](https://www.mpfr.org/), [MPC](https://www.multiprecision.org/mpc/), and [Math::Prime::Util::GMP](https://metacpan.org/pod/Math::Prime::Util::GMP). This allows computations with extremely large integers and high-precision arithmetic while keeping programs concise and expressive.

## 📚 Documentation & Learning Resources

| Resource | Description |
|----------|-------------|
| 📘 [Sidef GitBook](https://trizen.gitbook.io/sidef-lang/) | The complete language reference — covers everything |
| 📄 [Beginner's Guide](https://github.com/trizen/sidef/blob/master/SIDEF_BEGINNER_GUIDE.md) | Start here if you're new to Sidef |
| 📝 [Advanced Guide](https://github.com/trizen/sidef/blob/master/SIDEF_ADVANCED_GUIDE.md) | Comprehensive language tutorial |
| 📕 [Full PDF Documentation](https://github.com/trizen/sidef/releases/download/26.08/sidef-documentation.pdf) | Offline PDF version of the complete language documentation |
| 📑 [Number Theory Cheatsheet](https://github.com/trizen/sidef/blob/master/NUMBER_THEORY_CHEATSHEET.md) | Quick reference for Sidef's number theory functions |
| 📚 [Number Theory Guide](https://github.com/trizen/sidef/blob/master/NUMBER_THEORY_GUIDE.md) | Deep dive into Sidef's mathematical superpowers |
| 🔢 [Number Theory Reference](https://github.com/trizen/sidef/blob/master/NUMBER_THEORY_REFERENCE.md) | Complete function reference for number theory |

### Code Examples

| Resource | Description |
|----------|-------------|
| 📂 [sidef-scripts](https://github.com/trizen/sidef-scripts) | Hundreds of real Sidef programs — the best way to learn by reading |
| 🌹 [RosettaCode — Sidef](https://rosettacode.org/wiki/Sidef) | Classic programming tasks solved in Sidef, side-by-side with other languages |

## 🎨 Design Philosophy

Sidef combines expressive modern programming constructs with exact mathematics and symbolic computation. The language is designed to make advanced algorithms concise, readable, and practical while remaining fully interoperable with the Perl ecosystem.

## 💬 Community & Support

Have questions or need help? Join the conversation:

- **[Discussion Forum](https://github.com/trizen/sidef/discussions/categories/q-a)** - Q&A and community discussions
- **[GitHub Issues](https://github.com/trizen/sidef/issues)** - Bug reports and feature requests

## 📦 Distribution Availability

| Platform | Package | Link |
|----------|---------|------|
| **CPAN** | `Sidef` | [metacpan.org](https://metacpan.org/release/Sidef) |
| **Package Search** | Multiple distributions | [pkgs.org](https://pkgs.org/download/perl-Sidef) |
| **Arch Linux** | `sidef` (AUR) | [AUR Package](https://aur.archlinux.org/packages/sidef/) |
| **Slackware** | `perl-Sidef` | [SlackBuilds.org](https://slackbuilds.org/repository/15.0/perl/perl-Sidef/) |

## 🤝 Contributing

Contributions of all kinds are welcome — bug reports, feature suggestions, documentation improvements, and pull requests. Please read **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines on:

- Reporting bugs and suggesting features
- Setting up a development environment
- Code style and commit message conventions
- The pull request review process

## 📄 License and Copyright

**Copyright © 2013-2026 Daniel Șuteu, Ioana Fălcușan**

This program is free software; you can redistribute it and/or modify it under the terms of the **Artistic License (2.0)**.

**Full license**: [perlfoundation.org/artistic-license-20.html](https://www.perlfoundation.org/artistic-license-20.html)

---

<div align="center">

**Made with ❤️ by the Sidef community**

[⭐ Star us on GitHub](https://github.com/trizen/sidef) • [📖 Read the docs](https://trizen.gitbook.io/sidef-lang/) • [💬 Join discussions](https://github.com/trizen/sidef/discussions)

</div>
