# FAQ

NOTE: Some of the entries here are fairly old and thus may be inaccurate or outdated. If you notice any such mishaps then please let us now by submitting a bug report. Also, contributions are always welcome; please feel free to add to this page as needed and send us your changes in any convenient form.

## General

### What is Pure?

It is an algebraic/functional, general-purpose programming language based on term rewriting. Essentially, your programs are just collections of term rewriting rules which are used to reduce expressions to "normal form". More information about this approach can be found on the Rewriting page.

Modern programming languages are getting exceedingly complicated. Pure is an attempt to "go back to the roots" and boil down programming to a model of computation which is as simple as possible, yet expressive and practical enough so that people would want to use it for their everyday programming. The author thinks that term rewriting is a good candidate for achieving that goal, as all computing is essentially rewriting (of symbols on the tape of a Turing machine, for instance), but term rewriting also offers the dimension of hierarchical data structures which simple string rewriting lacks, and most important concepts of functional programming can be added on top of that quite easily.

This approach isn't really new, there are quite a few other systems which employ term rewriting as a computational model. But previous attempts to provide a real programming language based on term rewriting have suffered from various limitations or have been too slow or inconvenient for real-life applications. We think that Pure can change this situation.

### Why Pure?

Pure is unique in that it combines general term rewriting with modern-style functional programming in a practical and general-purpose programming language (as opposed to other systems which are mostly used for algebraic modelling). While Pure may look a lot like other modern FPLs such as Haskell and ML on the surface, under the hood it's much different:

• Pure is based on term rewriting rather than the lambda calculus. This gives you much more flexibility in dealing with general algebraic rules and constructor equations. Please visit the Rewriting page for details. Modern FPLs don't offer this since they segregate defined functions and constructors. Computer algebra systems do, but they're not general-purpose programming languages.

• Pure is dynamically typed. All terms belong to the same big Herbrand universe and any operation (even builtins) can be extended with new term rewriting rules at any time. This means a lot of flexibility with respect to ad-hoc polymorphism. Dynamic typing has become a rare feature in contemporary functional languages which usually employ a Hindley/Milner type system to offer more safety at the expense of restricting polymorphism. Erlang is one notable exception, but it lacks a real term data structure for representing algebraic data types in a convenient fashion.

• Pure is conceptually much simpler than Haskell et al. You don't have to learn about monadic I/O and type classes to get something done. If you understand equations and how they are used to evaluate expressions in a symbolic fashion, you should be able to start using Pure right away.

• Thanks to LLVM, Pure offers state-of-the-art JIT compiler technology in an interactive environment, and makes it easy to interface to C in a direct fashion. Recent releases also provide the ability to directly import LLVM bitcode modules into Pure scripts and to inline code written in various languages (currently C/C++, Fortran and Faust). Scripts can also be compiled to standalone native executables (they are also executed during compilation, which makes it possible to employ partial evaluation techniques).

• Pure has an efficient MATLAB-like, GSL-compatible matrix type which makes it easy to interface to languages and libraries for doing numeric computations and digital signal processing. In particular, Pure interfaces to (GNU) Fortran, Octave and Grame's Faust, and you can directly invoke GSL routines on Pure matrices. In a way, this is like having Haskell, Octave, DSP programming and the term rewriting capabilities of a computer algebra system under one hood.

• It goes without saying that Pure can be used for mathematical applications, but there's also a growing collection of extension modules for GUI, graphics, multimedia, database and web programming which makes Pure useful as a kind of algebraic/functional scripting language for a variety of purposes.

• Last but not least, Pure is embeddable, so you can use it as a component to run Pure scripts in your own C/C++ programs. This has also been put to good use to run Pure in a number of environments where you normally wouldn't expect it. In particular, we invite you to have a look at Pure's Pd plugin which seamlessly integrates Pure into Miller Puckette's state-of-the-art open-source graphical dataflow programming environment. In a similar vein, Pure is also available as a plugin for TeXmacs, the free scientific text editor from the GNU Project.

### Why Not Pure?

Obviously I tried to make Pure as useful and pretty as I could, but it's no silver bullet either and there are reasons why you would not want to use it (as well as some counter-arguments why you might want to try it anyway, despite these shortcomings):

• Pure probably appeals most to mathematically inclined programmers. This certainly doesn't mean that you have to hold a Master or PhD degree in mathematics, but if you hate symbolic algebra then Pure is probably not for you.

• Because of dynamic typing and limited module facilities, Pure is not an ideal language for big projects and teams. It's more on the "secret weapon" side of Paul Graham's programming language taxonomy. Like in Lisp, data types will be mostly in your head, so some people will miss the data modeling capabilities of H/M-typed languages.

• Pure doesn't attain the execution speed of compiled, statically typed languages, and because of its dynamic typing it probably never will. (OTOH, it's certainly much faster than most scripting languages and thus efficient enough for many purposes.)

• Pure doesn't support multithreading yet, so if you need this you will have to look elsewhere right now. (You can fork new processes, though, on platforms which provide that functionality.) Light-weight concurrent programming facilities are the next big thing on the TODO list, however.

• Pure doesn't have all the libraries of Perl, Python et al. But considering other FPLs like Haskell and ML, Pure's library support isn't bad, and in any case the direct C interface, along with the pure-gen utility, makes it easy to roll your own library interfaces if you want.

## Compiling and Installing Pure

### When running Pure, I get the error "pure: error while loading shared libraries".

On Linux, you have to run `ldconfig` after installing Pure, so that the dynamic linker finds the runtime library. Usually you have to do this as `root`, e.g.: `sudo ldconfig`. Please see `man ldconfig` for details. If after doing that you still get the same error, then most likely `/usr/local/lib` (or whereever the library was installed) is not in `/etc/ld.so.conf`, so you have to add that path to the file and then rerun `ldconfig`.

If you installed Pure in a nonstandard location which you can't (or don't want to) add to `/etc/ld.so.conf`, you can also set the `LD_LIBRARY_PATH` environment variable accordingly. Please see `man ld.so` for details.

### Compiling Pure on NetBSD

For convenience, you should set the following environment variables in your shell startup script:

``````export C_INCLUDE_PATH=/usr/local/include:/usr/pkg/include
export LIBRARY_PATH=/usr/local/lib:/usr/pkg/lib
export LD_LIBRARY_PATH=/usr/pkg/lib:/usr/local/lib
``````

To compile LLVM and Pure, you'll need updated versions of the following packages: gmake, perl5, flex, bison, readline, gmp, and gsl (Git will be needed, too, if you plan to use the latest sources from the repository).

The rest of the compilation process is as described in the INSTALL file, except that you have to use `gmake` instead of `make`. Thus:

``````\$ ./configure
\$ gmake
# gmake install
``````

Remember you must be a root user to install. Also, NetBSD folks recommend not putting stuff in ld.so.conf, so instead put `export LD_LIBRARY_PATH=/usr/pkg/lib:/usr/local/lib` in your shell startup script, as shown above.

Most addons are compiled in the same way, minus the `configure` step:

``````\$ gmake
# gmake install
``````

## Using Pure

### Deep recursion makes the interpreter segfault.

As of Pure 0.56 stack checks are now enabled by default, but since the interpreter has no way of knowing the actual stack space of your system, you might still have to set the `PURE_STACK` environment variable to an appropriate stack size limit in kilobytes. A reasonable default is assumed if `PURE_STACK` is not set (at the time of this writing this is 8192K - 128K for interpreter and runtime). This should work on most modern PCs, but may be too large on some embedded systems such as tablets and mobile phones, for instance. You can change the value as follows (Bourne shell syntax):

``````export PURE_STACK=4096
``````

If you now run the interpreter, it should generate an orderly exception instead (if not then you'll have to further reduce the `PURE_STACK` value):

``````> fact n = if n>0 then n*fact(n-1) else 1;
> fact 100000000;
<stdin>, line 2: unhandled exception 'stack_fault' while evaluating 'fact 100000000'
``````

Please note that `PURE_STACK` is only an advisory limit. Your operating system should provide you with a command (such as `ulimit` on Linux) to set the actual stack size available to processes. (On Windows, the stack size is hardcoded into the interpreter executable, but there are utilities to change that setting if you need to.)

### Dict or Stldict?

Properties of `dict`:

• included in the standard library

• purely functional/referentially transparent (no side effects)

• implemented in Pure

• mature

Properties of `stldict`:

• requires a separate package

• imperative (insert/delete modifies data structure)

• implemented using STL maps

• faster than `dict`

• supports larger tables than `dict`

• may be converted to lazy lists

• may be used both for dictionaries and as a set data structure.

• somewhat experimental

## Using the Pure Sphinx Framework

(Notes originally written by Peter Summerland, revised and continually updated by Albert Gräf.)

The Pure project uses the ReST markup language and Python's Sphinx framework for all its documentation. Ready-made documentation files in html and pdf formats are available online in a separate Git repository at https://agraef.github.io/pure-docs/. But you can also build the Pure documentation yourself in your local clone of the pure-lang repository. This is mainly useful for project members who want to test their documentation before committing to the repositories, and for users who want to get their hands on the latest bits of documentation which might not be online yet.

If you want to embark on this, you'll need a custom Sphinx version and a special Pygments module which provide support for the Pure language. In the following subsection, we first discuss how to get all the requisite software up and running.

### Prerequisites

Note that you'll need the Python2 version of all packages which follow. First, make sure that you have the python2-setuptools and python2-docutils packages installed. Next you'll have to install a custom version of Sphinx, therefore also make sure that you do not have the python2-sphinx package installed.

You'll need an older version of Sphinx and the Sphinx "puredomain" module, as well as a Pygments addon module, which provide support for the Pure language. A suitable version of Sphinx can be found here: https://bitbucket.org/purelang/pure-lang/downloads/sphinx.tar.bz2. Extract the tarball, cd into the resulting sphinx directory and run the following commands to build and install this package:

``````python2 setup.py build
sudo python2 setup.py install
``````

Next, get a working copy of the pygments-lexer-pure repository:

``````git clone https://github.com/agraef/pygments-lexer-pure.git
``````

Chdir into pygments-lexer-pure and install the pygments module:

``````python2 setup.py build
sudo python2 setup.py install
``````

Finally, get a working copy of the Pure source code repository:

``````git clone https://github.com/agraef/pure-lang
``````

Chdir into pure-lang/sphinx/puredomain and install the puredomain module:

``````python2 setup.py build
sudo python2 setup.py install
``````

Before creating the Sphinx documentation, make sure that you also have the Pure sources configured. To these ends, run `autoreconf && ./configure` in pure-lang/pure. The Makefile there is needed to properly format the Pure and Pure Library manuals. Otherwise Sphinx will give you strange errors and parts of the documentation (in particular the Pure Library Manual) will be broken.

Optionally, if you also want to build the TeXmacs-formatted documentation, you'll need a current version of TeXmacs (readily available as a package in most Linux distributions, otherwise you can get it from the TeXmacs website), GNU awk and the (really old) 1.5 version of pandoc. Because modern systems will usually ship much newer versions of pandoc, we provide a statically linked binary package in this tarball: pandoc-1.5.1.1-x86_64.tar.bz2. Extract the tarball to any location that seems convenient, and make sure that you have the included pandoc-1.5.1.1/bin directory in your `PATH` when running `make texmacs`. (NB: While Pure's TeXmacs plugin is still well-supported, the build system for the TeXmacs-formatted documentation is somewhat arcane and brittle. If it seems too much hassle for you, consider using the ready-made TeXmacs docs available at https://github.com/agraef/pure-docs instead.)

### Building the Documentation

Finally, cd into pure-lang/sphinx and kick the tires. To see if things are working, you can run `make allhtml` to format the docs in your local copy of the pure-lang repository. If you do, the generated html files will be at pure-lang/sphinx/build/html.

You can also run just `make` if you want to build the pdf manual in addition to the html files. This requires a fairly complete TeX installation such as texlive, and you also need some extra fonts and styles not usually installed by default, specifically: texlive-fonts-extra and texlive-latex-extra.

Sphinx also supports a couple of other formats; e.g., it's possible to format the documentation as a Windows html help file or as an ebook. Please check pure-lang/sphinx/Makefile for details. You can also run `make help` to see the available options.

As already noted, there's special support to build TeXmacs-formatted docs with `make texmacs`. For that you have to build the html documentation first, and make sure that you have pandoc 1.5 installed and in your `PATH`, see above.

##### Clone this wiki locally
You can’t perform that action at this time.
Press h to open a hovercard with more details.