=pod

=encoding utf8

=head1 NAME

Lingy - A Modern Acmeist Lisp Dialect

=head1 SYNOPSIS

Run the Lingy REPL:

    $ lingy
    Welcome to Lingy [perl]

    user> (prn "Hello, world!")
    "Hello, world!"
    nil
    user>

or a Lingy one-liner:

    $ lingy -e '(println "Hello, world!")'
    Hello, world!

or run a Lingy program file:

    $ echo '(println "Hello, world!")' > hello.ly
    $ lingy hello.ly
    Hello, world!

or run an example Lingy program:

    $ curl -sL https://raw.githubusercontent.com/ingydotnet/lingy/main/eg/99-bottles.ly | lingy - 3
    3 bottles of beer on the wall
    3 bottles of beer
    Take one down, pass it around
    2 bottles of beer on the wall.

    2 bottles of beer on the wall
    2 bottles of beer
    Take one down, pass it around
    1 bottles of beer on the wall.

    1 bottles of beer on the wall
    1 bottles of beer
    Take one down, pass it around
    0 bottles of beer on the wall.

=head1 DESCRIPTION

Lingy is a Lisp dialect written in many languages, including: Perl.

Clojure is a Lisp dialect that compiles to run on the JVM.

ClojureScript uses the same Clojure source code but compiles to NodeJS.

Lingy is the runtime that supports the YAMLScript language.

YAMLScript is meant to be implemented in all the same languages as Lingy.

Lingy is heavily influenced by the Clojure (Lisp) language. It aspires to be largely interoperable with Clojure. Currently it supports just a tiny subset of Clojure but supports Lisp basics like function application and macros.

Lingy started as a Perl L<implementation|https://github.com/ingydotnet/mal/tree/perl.2/impls/perl.2> of the L<Make a Lisp|https://github.com/kanaka/mal> project. This provided a bare-bones Clojure-inspired Lisp interpreter.

=head1 C<LINGY> CLI USAGE

The Lingy language installs a command C<lingy>. You can use this command to run Lingy programs, start a Lingy REPL or run Lingy one-liner expressions.

=over

=item * C<lingy --repl> (or just C<lingy>)

Starts a Lingy interactive REPL. The REPL has readline support that includes:

=over

=item * Command history

=item * CTL-R searching

=item * Parentheses match highlighting

=item * CTL-C to abort a command w/o leaving REPL

=back

Use CTL-D to exit the REPL

=item * C<lingy program.ly foo bar>

Run a Lingy program passing in arguments. Arguments are available in Lingy as C<*ARGV*>.

=item * C<cat program.ly | lingy - foo bar>

Run a Lingy program from STDIN and pass in arguments. The C<-> means run from STDIN instead of a file. If there are no arguments you can omit the C<->.

=item * C<lingy -e '(println "Hello" (nth *ARGV* 0))' world>

Run a Lingy one-liner with arguments.

When used with C<--repl>, run the C<-e> code first, then enter the REPL.

=back

=head2 C<LINGY> CLI OPTIONS

=over

=item * C<-e <string>>, C<--eval=<string>>

A Lingy string to evaluate.

=item * C<-r>, C<--repl>

Start a Lingy REPL. Can be used with C<-e>.

=item * C<--ppp>

Print the Lingy compiled AST for a C<-e> expression.

=item * C<--xxx>

YAML dump the Lingy compiled AST for a C<-e> expression.

=back

=head1 SUPPORTED FUNCTIONS

=over

=item * C<*>

=item * C<+>

=item * C<->

=item * C</>

=item * C<<<>>

=item * C<<<=>>

=item * C<=>

=item * C<==>

=item * C<>>

=item * C<>=>

=item * C<apply>

=item * C<*ARGV*>

=item * C<assoc>

=item * C<atom>

=item * C<atom?>

=item * C<catch>

=item * C<concat>

=item * C<cond>

=item * C<conj>

=item * C<cons>

=item * C<contains?>

=item * C<count>

=item * C<dec>

=item * C<def>

=item * C<defmacro>

=item * C<deref>

=item * C<dissoc>

=item * C<do>

=item * C<empty?>

=item * C<eval>

=item * C<false>

=item * C<false?>

=item * C<*file*>

=item * C<first>

=item * C<fn>

=item * C<fn?>

=item * C<get>

=item * C<getenv>

=item * C<hash-map>

=item * C<*host-language*>

=item * C<if>

=item * C<join>

=item * C<keys>

=item * C<keyword>

=item * C<keyword?>

=item * C<let>

=item * C<list>

=item * C<list?>

=item * C<load-file>

=item * C<macro?>

=item * C<macroexpand>

=item * C<map>

=item * C<map?>

=item * C<meta>

=item * C<nil>

=item * C<nil?>

=item * C<not>

=item * C<nth>

=item * C<number>

=item * C<number?>

=item * C<println>

=item * C<prn>

=item * C<pr-str>

=item * C<quasiquote>

=item * C<quasiquoteexpand>

=item * C<quote>

=item * C<range>

=item * C<readline>

=item * C<read-string>

=item * C<reset!>

=item * C<rest>

=item * C<seq>

=item * C<sequential?>

=item * C<slurp>

=item * C<str>

=item * C<string?>

=item * C<swap!>

=item * C<symbol>

=item * C<symbol?>

=item * C<throw>

=item * C<time-ms>

=item * C<true>

=item * C<true?>

=item * C<try>

=item * C<vals>

=item * C<vec>

=item * C<vector>

=item * C<vector?>

=item * C<with-meta>

=item * C<PPP>

=item * C<WWW>

=item * C<XXX>

=item * C<YYY>

=item * C<ZZZ>

=back

=head1 ROADMAP

The next major things to add are:

=over

=item * Multi-arity function/macro definition and application

=item * Namespaces

=item * Lambdas

=item * lingy.core libary

=item * Regex support

=back

=head1 SEE ALSO

=over

=item * L<YAMLScript|https://metacpan.org/pod/YAMLScript>

=item * L<YAMLTest|https://metacpan.org/pod/YAMLTest>

=back

=head1 STATUS

Lingy is in ALPHA status.

=head1 AUTHORS

=over

=item * Ingy döt Net L<ingy@ingy.net|mailto:ingy@ingy.net>

=back

=head1 COPYRIGHT AND LICENSE

Copyright 2023 by Ingy döt Net

This is free software, licensed under:

The MIT (X11) License

=cut
