From 524f2235cad633185f5936d74947e78c7556ab24 Mon Sep 17 00:00:00 2001 From: Duncan McGreggor Date: Tue, 8 Aug 2023 08:56:06 -0500 Subject: [PATCH] Added usage. --- README.md | 48 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 45 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e035ac3..1b6e05a 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ ## Introduction [↟](#contents) -This is a utility library created and used simply for aesthetics. +This is a utility library created and used simply for aesthetics. ## Dependencies [↟](#contents) @@ -48,7 +48,49 @@ And then do the usual: ## Usage [↟](#contents) -Add content to me here! +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--- @@ -59,7 +101,7 @@ Add content to me here! [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-1.3.0-blue.svg +[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