Data::SExpression(3p)

NAME
Data::SExpression -- Parse Lisp S-Expressions into perl data structures.

SYNOPSIS
    use Data::SExpression;

    my $ds = Data::SExpression->new;

    $ds->read("(foo bar baz)");          # [\*::foo, \*::bar, \*::baz]

    my @sexps;
    my $sexp;
    while(1) {
        eval {
            ($sexp, $text) = $ds->read($text);
        };
        last if $@;
        push @sexps, $sexp;
    }

    $ds = Data::SExpression->new({fold_alists => 1});

    $ds->read("((top . 4) (left . 5))");  # {\*::top => 4, \*::left => 5}

METHODS

  new [\%args]
Returns a new Data::SExpression object. Possibly args are:

fold_lists
    If true, fold lisp lists (e.g. "(1 2 3)") into Perl listrefs, e.g. [1, 2, 3]

    Defaults to true.

fold_alists
    If true, fold lisp alists into perl hashrefs. e.g.

    "((fg . red) (bg . black) (weight . bold))"

    would become

        {
            \*fg       => \*red,
            \*bg       => \*black,
            \*weight   => \*bold
        }

    Alists will only be folded if they are a list of conses, all of which have scalars as both their "car" and "cdr" (See "scalarp" in Data::SExpression::Cons)

    This option implies "fold_lists"

    Defaults to false.

symbol_case
    Can be "up", "down", or "undef", to fold symbol case to uppercase, lowercase, or to leave as-is.

    Defaults to leaving symbols alone.

use_symbol_class
    If true, symbols become instances of Data::SExpression::Symbol instead of globrefs.

    Defaults to false

fold_dashes
    If true, dash characters in symbols ("-") will be folded to the more perlish underscore, "_". This is especially convenient when symbols are being converted to globrefs.

    Defaults to false.

  read STRING
Parse an SExpression from the start of STRING, or die if the parse fails.

In scalar context, returns the expression parsed as a perl data structure; In list context, also return the part of STRING left unparsed. This means you can read all the expressions in a string with:

    my @sexps;
    my $sexp;
    while(1) {
        eval {
            ($sexp, $text) = $ds->read($text);
        };
        last if $@;
        push @sexps, $sexp;
    }

This method converts Lisp SExpressions into perl data structures by the following rules:

Numbers and Strings become perl scalars
    Lisp differentiates between the types; perl doesn't.

Symbols become globrefs in main::
    This means they become something like \*main::foo, or \*::foo for short. To convert from a string to a symbol, you can use "qualify_to_ref" in Symbol, with "main" as the package.

    But see "use_symbol_class" if you'd prefer to get back objects.

Conses become Data::SExpression::Cons objects
    See Data::SExpression::Cons for how to deal with these. See also the "fold_lists" and "fold_alists" arguments to "new".

    If "fold_lists" is false, the Lisp empty list "()" becomes the perl "undef". With "fold_lists", it turns into "[]" as you would expect.

Quotation is parsed as in scheme
    This means that "'foo" is parsed like "(quote foo)", "`foo" like "(quasiquote foo)", and ",foo" like "(unquote foo)".

LISP-LIKE CONVENIENCE FUNCTIONS
These are all generic methods to make operating on cons's easier in perl. You can ask for any of these in the export list, e.g.

    use Data::SExpression qw(cons consp);

  cons CAR CDR
Convenience method for Data::SExpression::Cons->new(CAR, CDR)

  consp THING
Returns true iff "THING" is a reference to a "Data::SExpression::Cons"

  scalarp THING
Returns true iff "THING" is a scalar -- i.e. a string, symbol, or number

Data::SExpression::Parser callbacks
These are for internal use only, and are used to generate the data structures returned by "read".

  new_cons CAR CDR
Returns a new cons with the given CAR and CDR

  new_symbol NAME
Returns a new symbol with the given name

  new_string CONTENT
Returns a new string with the given raw content

BUGS
None known, but there are probably a few. Please reports bugs via rt.cpan.org by sending mail to:

bug-Data-SExpression@rt.cpan.org

AUTHOR
Nelson Elhage <nelhage@mit.edu>