NAME

sidef - The Sidef Programming Language interpreter

            **   **         ****   *           *********   *********
          * * ** * *        ****   **          ** ** **    ** ** **
           **   **          ****   ***         *********   *  *  *
  **        **        **    ****   *  *        ******      ******
* * *     * * *     * * *   ****   ** **       ** **       ** **
 **        **        **     ****   ******      ******      *  *
       **   **              ****   *  *  *     *********   ***
     * * ** * *             ****   ** ** **    ** ** **    **
      **   **               ****   *********   *********   *

SYNOPSIS

sidef [options] [--] [programfile] [arguments]

# Execute a script
sidef script.sf

# Interactive mode (REPL)
sidef
sidef -i

# One-line program execution
sidef -E 'say "Hello, World!"'

# Check syntax
sidef -C script.sf

# Compile to Perl
sidef -c -o output.pl script.sf

DESCRIPTION

Sidef is a modern, high-level programming language designed for writing elegant and expressive code. This is the main interpreter for executing Sidef programs, providing both script execution and an interactive Read-Eval-Print Loop (REPL) environment.

Sidef features arbitrary-precision arithmetic, functional programming constructs, object-oriented programming, powerful regex support, and extensive built-in methods for common tasks. The language emphasizes code readability and expressiveness while maintaining strong performance through optimization and optional precompilation.

OPTIONS

Execution Options

-E program

Execute a one-line program from the command line. The program is executed immediately without requiring a file. This is useful for quick calculations, text processing, or testing code snippets.

sidef -E 'say "Hello, World!"'
sidef -E '10.times { |i| say i**2 }'
sidef -E '[1,2,3,4,5].grep{.is_prime}.say'

-e program

Alias for -E. Execute a one-line program.

-i [file]

Enter interactive mode (REPL - Read-Eval-Print Loop). If a file is provided, its contents are loaded and executed line by line in the interactive session. The REPL provides immediate feedback, command history, tab completion, and persistent variable state throughout the session.

sidef -i                    # Start empty REPL
sidef -i startup.sf         # Load file into REPL
sidef -i < commands.txt     # Pipe commands

-t

Test mode. Treat all command-line arguments as script files and execute them sequentially. Useful for running test suites. Reports which scripts succeed or fail and provides a summary at the end.

sidef -t test1.sf test2.sf test3.sf
sidef -t tests/*.sf

--

End of options marker. Everything after this is treated as a program file or arguments, even if it starts with a dash. Useful when script names begin with hyphens.

sidef -- -weird-script-name.sf

Compilation and Analysis Options

-c

Compile the Sidef code into a stand-alone Perl program. The output includes all necessary Sidef runtime modules embedded in a single file, making it distributable without requiring a Sidef installation. The resulting program can be executed directly with Perl.

sidef -c -o myprogram.pl script.sf
chmod +x myprogram.pl
./myprogram.pl

Note: Code using eval() may not compile correctly as it requires parse-time information that is lost during compilation.

-C

Check syntax only. Parse the program and report any syntax errors without executing the code. Useful for validating code structure before deployment or as part of a continuous integration pipeline.

sidef -C script.sf
sidef -C *.sf               # Check all scripts

-D

Dump the Abstract Syntax Tree (AST) of the program. The AST represents the internal structure of the parsed program before execution. Useful for debugging parser behavior, understanding how code is interpreted, and developing language extensions.

sidef -D script.sf > ast.dump
sidef -D -E '1 + (2 * 3)' | less

Requires the Data::Dump Perl module.

-r

Parse and deparse the program back to Sidef code. This shows how the parser interpreted your code and can help identify parsing ambiguities, verify operator precedence, and understand method call transformations.

sidef -r script.sf
sidef -r -E '1 + 2/3'       # Shows: (1)->+((2)->/(3));

-R language

Parse and deparse the program into the specified target language. This translates Sidef code into equivalent code in another language while preserving semantics. Valid values are:

sidef - Deparse to Sidef code (same as -r)
perl - Translate to Perl code with Sidef runtime

sidef -Rperl script.sf > script.pl
perl script.pl

sidef -Rsidef script.sf    # Normalize code style

Optimization Options

-O level

Perform code optimizations before execution. Higher optimization levels can significantly improve runtime performance for computation-heavy scripts by evaluating constant expressions at compile time. Valid levels:

0 - No optimization (default). Code is executed as parsed.
1 - Constant folding on AST (recommended for production). Pure expressions with constant operands are evaluated at compile time, reducing runtime computation.
2 - Aggressive optimization with deparse and reparse. Performs constant folding, deparses to Sidef code, reparses, and does additional constant folding on the new AST. Increases compile time but may provide additional optimizations.

sidef -O0 script.sf         # Default, no optimization
sidef -O1 script.sf         # Recommended
sidef -O2 compute.sf        # Maximum optimization

Example optimization:

# Source code
var x = (2 + 3*4)

# After -O1 optimization
var x = 14

-s

Enable precompilation caching. Compiled code is saved in a database indexed by MD5 hash of the source code. On subsequent runs of the same code, the compiled version is loaded from cache, significantly reducing startup time for large programs.

sidef -s large_script.sf    # Slow first run (compiles and caches)
sidef -s large_script.sf    # Fast subsequent runs (loads from cache)

The cache is automatically maintained and periodically sanitized. Cache location: ~/.sidef/cache/

Number Configuration Options

Sidef provides arbitrary-precision arithmetic through the GMP and MPFR libraries. These options control precision and behavior of numeric operations.

-P digits

Set the precision of floating-point numbers in decimal digits. Higher precision allows more accurate calculations but increases memory usage and computation time. Default is approximately 58 decimal digits (192 bits).

sidef -P 50 -E 'say sqrt(2)'          # 50 decimal digits
sidef -P 100 -E 'say sqrt(2)'         # 100 decimal digits
sidef -P 1000 -E 'say Num.pi'         # 1000 decimal digits

-M mode

Set the rounding mode for floating-point operations. Different rounding modes are useful for different numerical applications (financial calculations, scientific computing, interval arithmetic, etc.). Valid modes:

near - Round to nearest (default). Standard rounding mode.
zero - Round towards zero (truncate). Discards fractional part.
inf - Round away from zero. Rounds up for positive, down for negative.
+inf - Round towards positive infinity (ceiling). Always rounds up.
-inf - Round towards negative infinity (floor). Always rounds down.
faith - Faithful rounding. Result is one of the two nearest floating-point numbers.

sidef -M near -E 'say 7/3'            # 2.333... (nearest)
sidef -M zero -E 'say 7/3'            # 2.333... (towards zero)
sidef -M +inf -E 'say 7/3'            # 2.334... (ceiling)
sidef -M -inf -E 'say 7/3'            # 2.333... (floor)

-N options

Configure Number class variables for fine-grained control over numeric computation behavior. Multiple options can be separated by semicolons. Format: 'NAME1=VALUE1; NAME2=VALUE2'

Available options:

PREC - Floating-point precision in decimal digits (same as -P)
ROUND - Rounding mode as integer: 0=near, 1=zero, 2=inf, 3=+inf, 4=-inf, 5=faith
VERBOSE - Enable verbose/debug mode (true/false). Prints detailed information about numeric operations.
USE_YAFU - Use YAFU (Yet Another Factorization Utility) for factoring large integers (true/false). Requires YAFU installed.
USE_PFGW - Use PFGW64 (PrimeForm/GW) as a primality pretest for large numbers (true/false). Requires PFGW64 installed.
USE_PARI_GP - Use PARI/GP for various number theory operations (true/false). Requires PARI/GP installed.
USE_FACTORDB - Use factordb.com web service for factoring large integers (true/false). Requires internet connection.
USE_PRIMESUM - Use Kim Walisch's primesum for computing sum of primes (true/false). Requires primesum installed.
USE_PRIMECOUNT - Use Kim Walisch's primecount for computing prime counting function π(n) (true/false). Requires primecount installed.
USE_CONJECTURES - Use conjectured (unproven but likely correct) methods for better performance (true/false).
SPECIAL_FACTORS - Try to find factors of special form (Fermat, Mersenne, etc.) when factoring (true/false).

Examples:

# Enable verbose mode and external factorization
sidef -N 'VERBOSE=true; USE_FACTORDB=true' -E 'say factor(2**512 + 1)'

# High precision with specific rounding
sidef -N 'PREC=400; ROUND=3' script.sf

# Use all available external tools
sidef -N 'USE_YAFU=true; USE_PARI_GP=true; USE_PRIMECOUNT=true' script.sf

Debugging and Warning Options

-k

Keep track of potentially incorrect parser interpretations. Enables warnings when the parser makes assumptions that might not match your intent. This is especially useful for catching typos in function names that get interpreted as method calls.

sidef -k script.sf

Example warning:

func foo(n) { say n }
fo(42)                      # Typo in function name

# With -k:
[INFO] `fo` is parsed as a prefix method-call at script.sf line 2

Common cases flagged:

Method calls without an explicit receiver
Ambiguous operator precedence interpretations
Potential variable/function name confusion

-w

Enable warnings with stack backtrace. When a warning occurs, displays a complete call stack showing the sequence of function/method calls that led to the warning. Useful for debugging complex code paths.

-W

Make warnings fatal (with stack backtrace). The program terminates immediately on the first warning, showing a full stack trace. This is useful for strict error checking during development or testing.

Output Options

-o file

Specify output file for compiled or deparsed code. By default, output goes to STDOUT. This option is typically used with -c, -r, or -R.

sidef -c -o program.pl script.sf        # Compile to file
sidef -R perl -o script.pl script.sf    # Deparse to file
sidef -D -o ast.txt script.sf           # Dump AST to file

Help and Information Options

-H

Enter interactive help mode. Provides access to documentation for Sidef objects, methods, and modules. You can enter any expression that evaluates to an object, and the help system will display its documentation.

sidef -H
help> Array()
help> Hash()
help> Number()
help> quit

-h

Display help message with usage information and available options, then exit.

-v

Print version information and exit. Shows the Sidef version number.

INTERACTIVE MODE (REPL)

When invoked without a script file, Sidef enters interactive mode, providing a Read-Eval-Print Loop (REPL) for exploring the language, testing code snippets, and rapid prototyping.

Starting the REPL

$ sidef
Sidef 26.01, running on Linux, using Perl v5.42.0.
Type "help", "copyright" or "license" for more information.
>

Or explicitly with the -i option:

$ sidef -i
$ sidef -i startup.sf       # Load file first

REPL Features

Persistent Variables

All variables, functions, and classes defined in the REPL persist throughout the session.
```
> var x = 42
#1 = 42
> var y = x + 10
#2 = 52
> func double(n) { n * 2 }
> double(x)
#3 = 84
```
Result History

Every expression result is stored and can be referenced using #n notation, where n is the result number. Negative indices count from the end.
```
> 3 + 4
#1 = 7
> #1 * 2                    # Reference first result
#2 = 14
> #-1                       # Last result (same as #2)
#3 = 14
```
Multiline Input

End lines with backslash (\) to continue on the next line, or the REPL will automatically continue incomplete expressions. The prompt changes from > to to indicate continuation mode.
```
> func factorial(n) {
    n == 0 ? 1 : n*factorial(n-1)
  }
> factorial(10)
#2 = 3628800
```
Tab Completion

Press Tab to complete variable/function names, show available methods on objects, and navigate command history.
Command History

Use Up/Down arrow keys to navigate previous commands. History persists between sessions (saved to ~/.sidef/sidef_history.txt).

Special REPL Commands

##

Display execution time of the last command. Useful for benchmarking and performance analysis.

> factor(2**128 + 1)
#1 = [59649589127497217, 5704689200685129054721]
> ##
  ***   last result computed in 0.364332 seconds

# load filename

Load and execute a Sidef file line by line in the REPL. Each line is executed as if typed into the REPL.

> # load mylib.sf

# exec filename

Execute an entire Sidef file in the current REPL session. Unlike # load, this executes the file as a complete unit, but within the REPL environment where variables persist.

> # exec script.sf

# save filename

Save all valid commands from the REPL session to a file. This creates a replayable script containing all successfully executed code.

> # save session.sf
** Created file: session.sf

reset

Reset the REPL environment, clearing all variables, functions, and definitions. Result history is also cleared.

help

Enter interactive help mode to explore documentation.

copyright

Display copyright information.

license

Display license information (Artistic License 2.0).

quit, exit, q

Exit the REPL and return to the shell. Alternatively, press Ctrl+D (EOF).

EXAMPLES

Basic Execution

# Execute a script
sidef script.sf

# With command-line arguments
sidef script.sf arg1 arg2

# Read from STDIN
cat script.sf | sidef -
sidef script.sf < input.txt

One-Liner Examples

Mathematical calculations:

# Sum of squares
sidef -E '100.of { |i| i**2 }.sum.say'

# First 20 primes
sidef -E '20.pn_primes.say'

# Check if number is prime
sidef -E 'say (2**127 - 1 -> is_prime)'

# High-precision pi
sidef -P 100 -E 'say Num.pi'

Text processing:

# Convert to uppercase
echo "hello" | sidef -E 'STDIN.slurp.uc.print'

# Filter lines matching pattern
sidef -E 'STDIN.lines.grep(/pattern/).each{.say}' < file.txt

# Number lines
sidef -E 'STDIN.lines.each_kv{|i,v| say "#{i+1}: #{v}"}' < file.txt

Development Workflow

Check syntax before running:

sidef -C script.sf && sidef script.sf

Optimize and execute:

sidef -O1 script.sf                     # Recommended
sidef -O2 computation.sf                # Aggressive

Debug with parser warnings:

sidef -k -w script.sf                   # Warnings with traces
sidef -k -W script.sf                   # Fatal warnings

Enable precompilation for large scripts:

sidef -s large_project.sf               # Cache compiled code

Combine options for maximum performance:

sidef -O1 -s script.sf                  # Optimize and cache

Compilation Examples

Compile to standalone Perl program:

sidef -c -o myapp.pl script.sf
chmod +x myapp.pl
./myapp.pl

Translate to Perl for inspection:

sidef -R perl script.sf | less

Normalize Sidef code style:

sidef -r script.sf > normalized.sf

Number Theory with External Tools

# Factor with YAFU
sidef -N 'USE_YAFU=true' -E 'say factor(2**256 + 1)'

# Count primes with primecount
sidef -N 'USE_PRIMECOUNT=true' -E 'say prime_count(10**12)'

# Use FactorDB
sidef -N 'USE_FACTORDB=true' -E 'say factor(2**512 + 1)'

ENVIRONMENT

SIDEF_CACHE_DIR

Override default cache directory for precompiled code. Default: ~/.sidef/cache/

export SIDEF_CACHE_DIR=/tmp/sidef_cache

SIDEF_INC

Additional directories to search for Sidef modules, separated by colons (Unix) or semicolons (Windows).

export SIDEF_INC=/usr/local/lib/sidef:/opt/sidef/modules

SIDEF_OPT

Default options applied to every invocation. Useful for setting project-wide defaults.

export SIDEF_OPT="-O1 -P 100"

FILES

~/.sidef/: User configuration directory. Created automatically on first run.
~/.sidef/sidef_history.txt: REPL command history. Persists across sessions.
~/.sidef/cache/: Precompiled code cache directory. Used when -s flag is enabled.
/usr/local/lib/sidef/: System-wide module directory (typical location).
*.sf: Sidef source files (conventional extension). Can use any extension or none.

EXIT STATUS

0: Successful execution. Program ran without errors.
1: General error. Includes syntax errors, runtime errors, unhandled exceptions, file not found, and permission denied.
2: No input provided when expected.

DIAGNOSTICS

Common error messages and their meanings:

Can't open sidef script "filename": No such file or directory: The specified script file does not exist or is not readable. Check file name spelling and permissions.
Syntax error at line N: Parser encountered invalid syntax at the specified line. Use -k for more detailed diagnostics.
Invalid precision: <<value>> (expected a positive integer): The value provided to -P must be a positive integer.
No code specified for -E: The -E option requires a code argument.
Invalid format: <<option>>!: The -N option format is incorrect. Expected format: 'NAME1=VALUE1; NAME2=VALUE2'
"Data::Dump" is not installed!: The -D option requires the Perl module Data::Dump. Install with: cpan Data::Dump or cpanm Data::Dump
Variable 'name' is not declared in the current scope: Attempting to use an undeclared variable. Declare with var, global, const, or define.

BUGS AND LIMITATIONS

Known Limitations

Code using eval() may not compile correctly with -c
Very large precision (>100,000 digits) may cause performance issues
Precompilation cache can grow large with many unique scripts
Some REPL features may not work identically to script execution

Reporting Bugs

Report bugs on GitHub: https://github.com/trizen/sidef/issues

Please include:

Sidef version (sidef -v), OS, and Perl version (perl -v)
Complete error message with stack trace
Minimal code example reproducing the issue
Expected behavior vs. actual behavior

AUTHORS

Daniel Șuteu - Primary author and maintainer
Ioana Fălcușan - Contributor

For a complete list of contributors, see: https://github.com/trizen/sidef/graphs/contributors

ACKNOWLEDGMENTS

Sidef builds upon:

Perl programming language and ecosystem
GMP (GNU Multiple Precision Arithmetic Library)
MPFR (Multiple Precision Floating-Point Reliable Library)
MPC (Multiple Precision for Complex Arithmetic Library)
Various CPAN modules
Open source community contributions

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License (2.0). You may obtain a copy of the full license at:

https://www.perlfoundation.org/artistic-license-20.html

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

To install Sidef, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Sidef

CPAN shell

perl -MCPAN -e shell
install Sidef

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

Execution Options

Compilation and Analysis Options

Optimization Options

Number Configuration Options

Debugging and Warning Options

Output Options

Help and Information Options

INTERACTIVE MODE (REPL)

Starting the REPL

REPL Features

Special REPL Commands

EXAMPLES

Basic Execution

One-Liner Examples

Development Workflow

Compilation Examples

Number Theory with External Tools

ENVIRONMENT

FILES

EXIT STATUS

DIAGNOSTICS

BUGS AND LIMITATIONS

Known Limitations

Reporting Bugs

SEE ALSO

Official Resources

Module Documentation

AUTHORS

ACKNOWLEDGMENTS

LICENSE AND COPYRIGHT

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

Execution Options

Compilation and Analysis Options

Optimization Options

Number Configuration Options

Debugging and Warning Options

Output Options

Help and Information Options

INTERACTIVE MODE (REPL)

Starting the REPL

REPL Features

Special REPL Commands

EXAMPLES

Basic Execution

One-Liner Examples

Development Workflow

Compilation Examples

Number Theory with External Tools

ENVIRONMENT

FILES

EXIT STATUS

DIAGNOSTICS

BUGS AND LIMITATIONS

Known Limitations

Reporting Bugs

SEE ALSO

Official Resources

Related Tools

Module Documentation

AUTHORS

ACKNOWLEDGMENTS

LICENSE AND COPYRIGHT

Module Install Instructions