The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Sidef-24.05
River stage one • 1 direct dependent • 1 total dependent
8 ++
/ bin/sidef

NAME

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

SYNOPSIS

Usage: sidef [switches] [--] [programfile] [arguments]

  -c            compile the code into a Perl program
  -C            check syntax only
  -D            dump the syntax tree of a program
  -E program    one line of program
  -H            interactive help
  -i file       execute a program in interactive mode
  -k            keep track of potentially incorrect parser interpretations
  -M mode       set the rounding mode of floating-point numbers
                valid modes: [near], zero, inf, +inf, -inf, faith
  -N options    modify class-variables inside the Number class
                valid format: 'VERBOSE=1; USE_YAFU=1; USE_PRIMECOUNT=1'
  -o file       file where to dump the output
  -O level      perform code optimizations before execution
                valid levels: [0], 1, 2
  -P int        set the precision of floating-point numbers (default: 48)
  -r            parse and deparse a Sidef program
  -R lang       parse and deparse a Sidef program into a given language
                valid values: sidef, perl
  -s            save compiled code in a database to reduce boot-time
  -t            treat all command-line arguments as scripts
  -v            print version number and exit
  -w            enable warnings with stack backtrace
  -W            make warnings fatal (with stack backtrace)

Run 'sidef' for entering the interactive mode.

HELLO WORLD

A Sidef script can be written in any text editor and, by convention, it has the .sf extension.

The content of a simple Hello World program looks like this:

    say "Hello, 世界"

If we save the content in a new file called hello.sf, we can execute the code by running:

    sidef hello.sf

ONE LINE OF PROGRAM

The -E code command will execute the code specified as a command-line argument:

    sidef -E "say 'hello world'"

Outputs:

    hello world

ITERACTIVE MODE

The interactive mode (a.k.a. REPL) is available by simply executing the sidef command, or by specifying the -i command-line switch:

    $ sidef -i
    Sidef 24.05, running on Linux, using Perl v5.38.2.
    Type "help", "copyright" or "license" for more information.
    > n = 41
    #1 = 41
    > n**2 + n - 1
    #2 = 1721
    > is_prime(#2)
    #3 = true
    >

SPECIAL REPL COMMANDS

The REPL supports the following special commands:

  • Display the duration it took to execute the previous command:

        > ##

  • Refer to a previous output value, using the #n syntax (a negative value for n is also supported):

        > 3+4
    #1 = 7
    > sqrt(#1)

  • Load a Sidef file inside the REPL, line by line:

        > # load filename.sf

  • Execute a Sidef file inside the REPL:

        > # exec filename.sf

  • Save the code from the REPL inside a file:

        > # save filename.sf

  • Reset the REPL:

        > reset

  • Close the REPL:

        > quit

OPTIMIZATION

The -O level command-line option controls the level of optimization before the execution begins.

Currently, there are three levels of optimization available:

    0 -- Does nothing. (default)
    1 -- Does constant folding on the AST. (recommended)
    2 -- Does constant folding, after which it deparses the AST into Sidef code, parses the code again and does more constant folding on the new AST.

In the end, the code is translated to Perl and is ready to be executed. In the translation process, several other optimizations are also performed.

NUMBER OPTIONS

The -N option can be used for changing the class-variables in the Number class:

    sidef -N 'PREC = 192'               # precision for floating-point numbers
    sidef -N 'ROUND = 0'                # rounding mode for floating-point numbers
    sidef -N 'VERBOSE = false'          # true to enable verbose/debug mode
    sidef -N 'USE_YAFU = false'         # true to use YAFU for factoring large integers
    sidef -N 'USE_PFGW = false'         # true to use PFGW64 as a primality pretest for large enough n
    sidef -N 'USE_PARI_GP = false'      # true to use PARI/GP in several methods
    sidef -N 'USE_FACTORDB = false'     # true to use factordb.com for factoring large integers
    sidef -N 'USE_PRIMESUM = false'     # true to use Kim Walisch's primesum in prime_sum(n)
    sidef -N 'USE_PRIMECOUNT = false'   # true to use Kim Walisch's primecount in prime_count(n)
    sidef -N 'USE_CONJECTURES = false'  # true to use conjectured methods for better performance
    sidef -N 'SPECIAL_FACTORS = true'   # true to try to find factors of special form in factor(n)

Multiple options can be separated with ;, as in:

    sidef -N 'VERBOSE = true; USE_FACTORDB = true' -E 'say factor(2**256 + 1)'

The -P option can be used for changing the precision of floating-point numbers:

    sidef -P 1024 -E 'say sqrt(2)'

The -M option can be used for changing the rounding-mode for floating-point numbers:

    sidef -M 'near'     # round to nearest (default)
    sidef -M 'zero'     # round towards zero
    sidef -M 'inf'      # round away from zero
    sidef -M '+inf'     # round towards +Infinity
    sidef -M '-inf'     # round towards -Infinity
    sidef -M 'faith'    # faithful rounding

PARSER WARNINGS

Sidef provides the -k option which will keep track of all the possible incorrect parser interpretations.

For example, if we declare the following function, but we misspell its name when we call it, Sidef will interpret it as a method call, which is probably not what we want:

    func foo(n) { say n }
    fo(42)                   # will get interpreted as `42.fo`

When the command-line option -k is specified, the following warning is produced:

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

DEPARSING

Deparsing is the reverse process of parsing, which translates the AST back into code. Currently, Sidef supports deparsing into two languages with the -R lang command-line switch:

-R perl

Deparses the AST into valid Perl code.

-R sidef

Deparses the AST into valid Sidef code.

Example:

    sidef -Rperl script.sf | perl

The -Rsidef switch (or simply -r) is useful for verifying how the code is parsed:

    sidef -r -E '1 + 2/3'

outputs:

    (1)->+((2)->/(3));

DUMPING THE AST

The -D command-line option dumps the abstract syntax tree (AST) of a given Sidef program:

    sidef -D script.sf      # will dump the AST of script.sf

PRECOMPILATION

Sidef supports experimental precompilation by saving compiled code inside a database, which is updated automatically and sanitized periodically.

This method reduces significantly the boot-time of very large Sidef scripts, and it works as following:

  • it checks the database with the MD5 of the code

  • if the MD5 exists inside the database, it returns the executable code

otherwise:

  • parses the code and generates the executable code

  • stores the executable code inside the database with the MD5 of the code

Next time when the same code is executed, Sidef will simply retrieve the executable code from the database, without generating it again:

    sidef -s script.sf             # may load slow the first time
    sidef -s script.sf             # will load much faster the second time

COMPILATION

A Sidef script can be compiled to a stand-alone Perl program by using the -c command-line option:

    sidef -o out.pl -c script.sf

The above command will compile the file script.sf into the Perl script out.pl, which will include the entire implementation code of Sidef.

Currently, Sidef code that contains eval() cannot be compiled correctly to Perl, as it requires some parse-time information for run-time evaluation, which is lost in the compilation process.

WWW

You can find more info about Sidef, by clicking on the following links:

LICENSE AND COPYRIGHT

Copyright (C) 2013-2024 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). 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.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

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.