view release on metacpan or  search on metacpan

docs/intro.md  view on Meta::CPAN

Check the [functional-perl website](http://functional-perl.org/) for
properly formatted versions of these documents.

---

# Introduction to using the functional-perl modules

Unlike the other documentation materials (as listed in [[README]]),
this tries to give a nice introduction to using the modules and
programs that this project offers. (The files in the
[intro/](../intro/) directory are more on the fundamental side, also
they are a bit older and possibly could use some updating (todo).)

If you've got questions, please tell, either on the [[mailing_list]],
or join [the IRC channel](//mailing_list.md). If you find any errors
or would like to clarify some wording or add to this or other
documents: if you're reading this document via the
[website](http://functional-perl.org), there is an edit link at the
top right corner that lets you edit it on Github.


<with_toc>


## Starting up: the REPL

Functional programming languages usually come with a read-eval-print
loop (REPL). A REPL reads a statement or expression, evaluates it and
prints its result. The better ones come with debugging features, like
being able to inspect the context (stack) from where they were
called. Functional Perl is no exception.

(NOTE: the author didn't know about the `reply` repl and maybe others
when finishing the work on this; he originally started `FP::Repl` in
2004. It might be worth merging the efforts.)

There are three ways to run the functional-perl REPL:

 - Run it from somewhere in your program by using `use FP::Repl;` and
   calling `repl;`.
 - Register the repl to be run upon encountering uncaught exceptions
   by adding `use FP::Repl::Trap;` somewhere to your code.
 - Run the [bin/perlrepl](../bin/perlrepl) script, which takes the
   `-M` option like perl itself to load modules of your choice. Or
   [bin/fperl](../bin/fperl) which calls the repl with most Functional
   Perl modules preloaded.

You need to install `Term::ReadLine::Gnu` and `PadWalker` (and
`Capture::Tiny` to see code definition location information and
`Sub::Util` to see function names when displaying code refs) to use
the repl. Once you've done that, from the shell run:

    $ cd functional-perl
    $ bin/fperl

Or if you installed the project, just

    $ fperl

This will show a prompt:

    fperl> 

The string left of the ">" indicates the current namespace, "fperl" in
this case. Let's try:

    fperl> 1+2
    $VAR1 = 3;

You can refer to the given $VAR1 etc. variables in subsequent entries:

    fperl> $VAR1*2
    $VAR1 = 6;
    fperl> $VAR1*2
    $VAR1 = 12;
    fperl> $VAR1*2, $VAR1+1
    $VAR1 = 24;
    $VAR2 = 13;

If you happen to produce an error at run time of the code that you
enter, you will be in a sub-repl, indicated by the level number `1`
here:

    fperl> foo()
    Exception: 'Undefined subroutine &fperl::foo called at (eval 143) line 1.
    '
    fperl 1> 

In that case, you can return to the parent repl by pressing ctl-d. It
will then show (XX: currently it also shows the exception again; work
is under way to improve this):

    fperl> 

(In case you really don't like this nesting feature, you can omit the
`-t` flag to the `perlrepl` script (adapt the `fperl` wrapper script).)


## Lists the functional way

One of the most basic features of functional programming are singly
linked lists. Those can be extended and shrunk in a purely functional
way, i.e. without changing existing list references. Lists can be
created using the `list` function from `FP::List`, which is preloaded
in fperl:

    fperl> list()
    $VAR1 = bless( [], 'FP::List::Null' );