README.md

# klä

[![Build Status][gh-actions-badge]][gh-actions]
[![LFE Versions][lfe badge]][lfe]
[![Erlang Versions][erlang badge]][versions]
[![Tags][github tags badge]][github tags]

*An LFE Wrapper Library used to Dress Up Erlang Libraries in a Lispy Costume*

[![Project logo][logo]][logo-large]

##### Table of Contents

* [Introduction](#introduction-)
* [Dependencies](#dependencies-)
* [Installation](#installation-)
* [Usage](#usage-)


## Introduction [↟](#contents)

This is a utility library created and used simply for aesthetics. 

## Dependencies [↟](#contents)

As of version 0.5.0, this project assumes that you have
[rebar3](https://github.com/rebar/rebar3) installed somwhere in your ``$PATH``.
It no longer uses the old version of rebar. If you do not wish to use rebar3,
you may use the most recent rebar2-compatible release of kla: 0.4.2.


## Installation [↟](#contents)

Just add it to your ``rebar.config`` deps:

```erlang
{deps, [
    ...
    {kla, "0.9.1"}
]}.
```

And then do the usual:

```bash
    $ rebar compile
```

## Usage [↟](#contents)

To use this library, one does the following (usually in an include file):

1. Create a function that returns a list of function names as they would be called in an LFE application.
1. Create a generator function that will convert these to Erlang names and then look them up in the specified Erlang module.
1. Call the generate function in the include.
1. Use the include in your application.

The [moneta](https://github.com/lfex/moneta) project makes heavy use of `kla`; here's an excerpt of the "query" include file:

``` lisp
(eval-when-compile
  (defun get-api-funcs ()
    '((append 1) (append 2)
      (cursor 1) (cursor 2)
      (delete-cursor 1)
      (eval 1) (eval 2)
      (e 1) (e 2)
      (fold 3) (fold 4)
      (format-error 1)
      (info 1) (info 2)
      (keysort 2) (keysort 3)
      (next-answers 1) (next-answers 2)
      (q 1) (q 2)
      (sort 1) (sort 2)
      (string-to-handle 1) (string-to-handle 2) (string-to-handle 3)
      (table 2))))

(defmacro generate-api ()
  `(progn ,@(kla:make-funcs (get-api-funcs) 'qlc)))

(generate-api)
```

Then, in the library source file `mnt-qry`:

``` lisp
(defmodule mnt-qry
  (export all))

(include-lib "moneta/include/mnt-qry.lfe")
```

at which point all the functions listed in `get-api-funcs` are now available for use in `mnt-qry`. Calling the Lisp-style functions in `mnt-qry` will result in calls to the under-score functions in the Erlang `qlc` library.

[//]: ---Named-Links---

[logo]: priv/images/vikings-small.png
[logo-large]: http://callego.deviantart.com/art/Viking-Clothes-334955145
[github]: https://github.com/lfex/kla
[gitlab]: https://gitlab.com/lfex/kla
[gh-actions-badge]: https://github.com/lfex/kla/workflows/ci%2Fcd/badge.svg
[gh-actions]: https://github.com/lfex/kla/actions
[lfe]: https://github.com/lfe/lfe
[lfe badge]: https://img.shields.io/badge/lfe-2.1-blue.svg
[erlang badge]: https://img.shields.io/badge/erlang-21%20to%2026-blue.svg
[versions]: https://github.com/lfex/lxml/blob/master/.github/workflows/cicd.yml
[github tags]: https://github.com/lfex/kla/tags
[github tags badge]: https://img.shields.io/github/tag/lfex/kla.svg