The Fennel programming language
Calvin Rose 85cdae3b66 Update README to reference fennel.vim 1 week ago
.circleci Fix package name for CI build. 1 year ago
rockspecs Update version string. 1 month ago
.gitignore We need to precompiled code to git for luarocks 3 months ago
.luacheckrc Pacify luacheck; add makefile. 1 year ago
CODE-OF-CONDUCT.md Make examples IRC not Discord 1 month ago
CONTRIBUTING.md Use reference-style links in markdown instead of inline. 2 months ago
LICENSE Create LICENSE 11 months ago
Makefile Organize test cases. 2 months ago
README.md Update README to reference fennel.vim 1 week ago
api.md Use reference-style links in markdown instead of inline. 2 months ago
changelog.md Update changelog. 1 month ago
fennel Add `--add-package-path` and `--add-fennel-path` to launcher 2 months ago
fennel-watch.sh Add a script to "auto-compile" fennel code. 11 months ago
fennel.1 Add `--add-package-path` and `--add-fennel-path` to launcher 2 months ago
fennel.bat Add a bat file for command line usage on windows. 2 months ago
fennel.lua Update README to reference fennel.vim 1 week ago
fennelview.fnl Generate fewer IIFEs as a result of declarations. 1 month ago
fennelview.fnl.lua Generate fewer IIFEs as a result of declarations. 1 month ago
generate.fnl Remove commas from generated symbols in testing (commas are whitespace) 11 months ago
lua-primer.md Updated for post-release fennel 2 months ago
reference.md Allow macros to detect sequence literals 1 month ago
release-checklist.md Add release checklist to make releases smoother for scatter-brained devs. 1 month ago
test-macros.fnl Prevent quoting of lists and symbols at runtime. 2 months ago
test.lua Fix tset issue with table literals. 2 weeks ago
tutorial.md Addressing #139 1 month ago

README.md

Fennel

Fennel (formerly fnl) is a lisp that compiles to Lua. It aims to be easy to use, expressive, and has almost zero overhead compared to handwritten Lua.

  • Full Lua compatibility - You can use any function or library from Lua.
  • Zero overhead - Compiled code should be just as or more efficient than hand-written Lua.
  • Compile-time macros - Ship compiled code with no runtime dependency on Fennel.
  • Embeddable - Fennel is a one-file library as well as an executable. Embed it in other programs to support runtime extensibility and interactive development.

Documentation

  • The tutorial is a great place to start
  • The reference describes all Fennel special forms
  • The API listing shows how to integrate Fennel into your codebaes
  • The Lua primer gives a very brief intro to Lua with pointers to further details
  • The test suite has basic usage examples for most features.

For a small complete example that uses the LÖVE game engine, see pong.fnl.

The changelog has a list of user-visible changes for each release.

Example

Hello World

(print "hello, world!")

Fibonacci sequence

(fn fib [n]
 (if (< n 2)
  n
  (+ (fib (- n 1)) (fib (- n 2)))))

(print (fib 10))

Usage

At https://fennel-lang.org there's a live in-browser repl you can use without installing anything.

Check your OS's package manager to see if Fennel is available there. If you use LuaRocks you can run luarocks install fennel.

Otherwise clone this repository, and run ./fennel to start a repl. Use ./fennel my-file.fnl to run code or ./fennel --compile my-file.fnl > my-file.lua to perform ahead-of-time compilation.

See the API documentation for how to embed Fennel in your program.

Differences from Lua

  • Syntax is much more regular and predictable (no statements; no operator precedence)
  • It's impossible to set or read a global by accident
  • Pervasive destructuring anywhere locals are introduced
  • Clearer syntactic distinction between sequential tables and key/value tables
  • Separate looping constructs for numeric loops vs iterators instead of overloading for
  • Opt-in mutability for local variables
  • Opt-in arity checks for lambda functions
  • Ability to extend the syntax with your own macros and special forms

Differences from other lisp languages

  • Lua VM can be embedded in other programs with only 180kb
  • Access to excellent FFI
  • LuaJIT consistently ranks at the top of performance shootouts
  • Inherits aggressively simple semantics from Lua; easy to learn
  • Lua VM is already embedded in databases, window managers, games, etc
  • Low memory usage
  • Readable compiler output resembles input

(Obviously not all these apply to every lisp you could compare Fennel to.)

Resources

License

Copyright © 2016-2019 Calvin Rose and contributors

Released under the MIT license