/ 
Sidef-26.01
River stage one • 1 direct dependent • 1 total dependent
⭐ Starred 115 GitHub stars
/ Sidef::Variable::GetOpt

NAME

Sidef::Variable::GetOpt - Command-line argument parsing for Sidef's MAIN function

DESCRIPTION

This class implements command-line argument parsing for Sidef programs using the special MAIN function. The GetOpt class provides an interface to Perl's Getopt::Long module, automatically mapping command-line arguments to function parameters based on their types and names.

The GetOpt class is not typically used directly. Instead, it is invoked automatically when a Sidef program defines a MAIN function that accepts parameters. The command-line arguments passed to the script are parsed and matched against the MAIN function's parameter signature.

SYNOPSIS

#!/usr/bin/sidef

# Simple MAIN function with string parameter
func MAIN(name) {
    say "Hello, #{name}!"
}

# Execute: sidef script.sf --name=World
# Output: Hello, World!

THE MAIN FUNCTION

The MAIN function is a special function in Sidef that serves as the entry point for command-line scripts. When defined, it automatically receives command-line arguments through the GetOpt parsing mechanism.

Parameter Types

The GetOpt class recognizes parameter types and generates appropriate option specifications:

  • Number - Accepts numeric values (mapped to =f in Getopt::Long)

  • Bool - Accepts boolean flags (mapped to ! in Getopt::Long)

  • String (default) - Accepts string values (mapped to =s in Getopt::Long)

  • Slurpy parameters - Captures remaining arguments as an array

EXAMPLES

Basic String Parameter

func MAIN(file) {
    say "Processing file: #{file}"
}

# Execute: sidef script.sf --file=input.txt
# Output: Processing file: input.txt

Typed Parameters

func MAIN(Number count, Bool verbose) {
    say "Count: #{count}"
    say "Verbose mode: #{verbose}"
}

# Execute: sidef script.sf --count=42 --verbose
# Output:
# Count: 42
# Verbose mode: true

Mixed Parameters

func MAIN(String input, String output, Number limit = 100) {
    say "Input: #{input}"
    say "Output: #{output}"
    say "Limit: #{limit}"
}

# Execute: sidef script.sf --input=data.txt --output=result.txt --limit=50

Slurpy Parameters

Slurpy parameters capture all remaining command-line arguments that don't match named options:

func MAIN(Bool verbose, *files) {
    say "Verbose: #{verbose}"
    say "Processing files: #{files.join(', ')}"
}

# Execute: sidef script.sf --verbose file1.txt file2.txt file3.txt
# Output:
# Verbose: true
# Processing files: file1.txt, file2.txt, file3.txt

Multiple MAIN Function Signatures

Sidef supports multiple MAIN function signatures through function overloading. The GetOpt class will try each signature until it finds one that matches the provided arguments:

func MAIN(String action, String file) {
    say "Action: #{action}, File: #{file}"
}

func MAIN(Number count) {
    say "Count mode: #{count}"
}

func MAIN {
    say "No arguments provided"
}

# The appropriate function will be called based on the arguments

ARGUMENT PARSING BEHAVIOR

Option Names

Option names are derived from the parameter names in the MAIN function. Each parameter becomes a command-line option with the same name:

func MAIN(input_file, output_file) { ... }

# Accepts: --input_file=in.txt --output_file=out.txt

Boolean Options

Boolean parameters accept the following forms:

--verbose       # Sets to true
--no-verbose    # Sets to false
--verbose=1     # Sets to true
--verbose=0     # Sets to false

Numeric Options

Numeric parameters accept any numeric value:

--count=42
--limit=3.14
--size=1e6

String Options

String parameters accept any string value:

--name=value
--file="path with spaces"

Error Handling

If the command-line arguments don't match any defined MAIN function signature, the GetOpt class will try all available signatures. If none match, an error message is displayed indicating an unknown command-line argument.

INTERNAL IMPLEMENTATION

The GetOpt class works by:

1. Receiving the command-line arguments (argv) and the MAIN function block
2. Iterating through each possible MAIN function signature
3. Building option specifications based on parameter types:

  • param_name=f for Number parameters

  • param_name! for Bool parameters

  • param_name=s for String parameters (or untyped parameters)

4. Using Getopt::Long::GetOptionsFromArray to parse arguments
5. Converting parsed values to appropriate Sidef types
6. Creating NamedParam objects for each parsed option
7. Calling the matching MAIN function with the parsed parameters

METHODS

new

GetOpt->new(argv, block)

Creates a new GetOpt object and immediately processes the command-line arguments.

  • argv - Array reference containing command-line arguments

  • block - The MAIN function block(s) to process

Returns the result of calling the matching MAIN function.

This method is called automatically by the Sidef compiler and should not be invoked directly in user code.

TYPE CONVERSION

The GetOpt class automatically converts parsed command-line arguments to appropriate Sidef types:

  • Numeric values become Sidef::Types::Number::Number objects

  • Boolean flags become Sidef::Types::Bool::Bool objects

  • String values become Sidef::Types::String::String objects

  • Unmatched arguments (captured by slurpy parameters) become arrays of Sidef::Types::String::String objects

NAMED PARAMETERS

All command-line options are passed to the MAIN function as named parameters (Sidef::Variable::NamedParam objects). This allows the MAIN function to receive arguments by name rather than by position.

LIMITATIONS

  • All command-line options must be explicitly named (e.g., --option=value)

  • Short option forms (e.g., -o instead of --option) are not directly supported

  • Complex option types (arrays, hashes) must be handled manually through string parsing

  • The GetOpt class suppresses warnings from Getopt::Long during parsing

INTEGRATION WITH PERL

The GetOpt class uses Perl's Getopt::Long module for the actual parsing. This provides:

  • Robust option parsing

  • Support for various option styles

  • Automatic type checking

  • Flexible option specifications

SEE ALSO

AUTHOR

Daniel Șuteu (trizen)

COPYRIGHT AND LICENSE

Copyright (C) 2013-2025 Daniel Șuteu

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