This commit is contained in:
perro tuerto 2023-03-16 08:52:04 -07:00
parent 270a5ceb22
commit f95db9f9f3
8 changed files with 36 additions and 102 deletions

View File

@ -1,7 +1,7 @@
# Literate Pandoc
# 👾 Computable Pandoc
Literate Pandoc is a [Pandoc filter] written in [Lua] for [literate] and
[natural] programming (LiNP or just Linp), i.e.: "[Programming \[...\] as the
Computable Pandoc is a [Pandoc filter] written in [Lua] for [literate] and
[natural] programming (LIN programming), i.e.: "[Programming \[...\] as the
process of creating works of literature][1]".
## Requirements
@ -11,32 +11,32 @@ process of creating works of literature][1]".
## Install
1. Go to [Releases].
2. Download the latest version of `linp.lua`.
2. Download the latest version of `lin.lua`.
3. Done!
## Usage
With `linp.lua` downloaded and Pandoc installed, do:
With `lin.lua` downloaded and Pandoc installed, do:
pandoc -L PATH/TO/linp.lua -t FORMAT DOC
pandoc -L PATH/TO/lin.lua -t FORMAT DOC
For example, if `DOC` is `source.md` and the output `FORMAT` is HTML, do:
pandoc -L PATH/TO/linp.lua -t html source.md
pandoc -L PATH/TO/lin.lua -t html source.md
## Manual
Learn how to do LiNP [here].
Learn how to do LIN programming [here].
## Develop
Clone this repo:
git clone https://git.cuates.net/perro/literate-pandoc.git
git clone https://git.cuates.net/perro/computable-pandoc.git
Enter the repo:
cd literate-pandoc
cd computable-pandoc
Inside, do the tests:
@ -53,14 +53,14 @@ Contribute!
This wouldn't be possible without these projects and their collaborators:
- [Pandoc][]: universal document converter and parser; handles the
requirements for LiNP.
- [Lua][]: programming language; enables LiNP.
- [Fennel][]: [Lisp] dialect with full Lua compatibility; allows to go from
LiNP to Lisp or Lua.
requirements for LIN.
- [Lua][]: programming language; enables LIN.
- [Fennel][]: [Lisp] dialect with full Lua compatibility; allows native evals
for Lisp.
## License
Literate Pandoc is under [GPLv3].
Computable Pandoc is under [GPLv3].
Happy hacking :)
@ -70,8 +70,8 @@ Happy hacking :)
[natural]: https://en.wikipedia.org/wiki/Natural-language_programming
[1]: https://web.archive.org/web/20170605163729/http://www.desy.de/user/projects/LitProg/Philosophy.html
[Pandoc]: https://pandoc.org/
[Releases]: https://git.cuates.net/perro/literate-pandoc/releases
[here]: https://git.cuates.net/perro/literate-pandoc/src/branch/no-masters/man/README.md
[Releases]: https://git.cuates.net/perro/computable-pandoc/releases
[here]: https://git.cuates.net/perro/computable-pandoc/src/branch/no-masters/man/README.md
[Fennel]: https://fennel-lang.org
[Lisp]: https://en.wikipedia.org/wiki/Lisp_(programming_language)
[GPLv3]: https://git.cuates.net/perro/literate-pandoc/src/branch/no-masters/LICENSE.txt
[GPLv3]: https://git.cuates.net/perro/computable-pandoc/src/branch/no-masters/LICENSE.txt

View File

@ -1,15 +1,15 @@
--[[
Literate Pandoc & Fennel Bundle:
Computable Pandoc & Fennel Bundle:
A Pandoc filter for literate and natural programming
Computable Pandoc:
(C) 2023 perro hi@perrotuerto.blog
License: GPLv3 https://git.cuates.net/perro/computable-pandoc/src/branch/no-masters/LICENSE.txt
Source: https://git.cuates.net/perro/computable-pandoc
Fennel:
(C) 2016-2023 Calvin Rose and contributors
License: MIT License https://git.sr.ht/~technomancy/fennel/tree/main/item/LICENSE
Source: https://sr.ht/~technomancy/fennel or https://github.com/bakpakin/Fennel/issues
Website: https://fennel-lang.org
Literate Pandoc:
(C) 2023 perro hi@perrotuerto.blog
License: GPLv3 https://git.cuates.net/perro/literate-pandoc/src/branch/no-masters/LICENSE.txt
Source: https://git.cuates.net/perro/literate-pandoc
]]--
package.preload["fennel.repl"] = package.preload["fennel.repl"] or function(...)
local utils = require("fennel.utils")
@ -6343,7 +6343,7 @@ end
return {
{
-- Parses LiNP declarations
-- Parses LIN declarations
CodeBlock = function(codeblock)
return lit.parse_declarations(codeblock)
end,
@ -6354,7 +6354,7 @@ return {
str = pandoc.utils.stringify(quoted.content):gsub('"', '\\"')
return '"' .. str .. '"'
end,
-- Parses and does LiNP calls
-- Parses and does LIN calls
Inlines = function(inlines)
return lit.parse_calls(inlines)
end,

View File

@ -1,66 +0,0 @@
# Test 1
With Literate Pandoc you can write code as you write everything else! For
example, this is a function declaration: f() = (+ 1 2 3).
Every function declaration has:
1. A *function name* consisting in:
1. One or more alphanumeric characters following by a opening parenthesis
(i.e. `%w+(`).
2. Optional arguments (args).
3. Closing parenthesis (`)`).
2. A *function assignment* indicated with the equal sign (`=`).
3. A *function body* composed by Lisp code between parentheses.
Any function can be called at any time by is function name, for example now
we call f()! This also apply for function that haven't been defined, like
foo(1).
The functions can contain args, for example:
* foo(n) = (* #n #n) is a function declaration with the arg `n`; any arg can
be used in the function body if it is prefixed with a hashtag (`#n`).
* They can contain more args like bar(a, b) = (- a b).
* For a variable number of args the `...` symbol is used: baz(...) =
(.. #...). You can call baz() or baz('hello', ' ', 'world!').
All args can be treated as keyword args (kwargs), so foo(3) can be foo(n: 3),
or bar(2, 1) can be bar(b: 1, a: 2).
With kwargs you can declare args in any order and makes args more readable. The
trade-off is that they are verbose. Also, `...` arg can't be use as kwarg!
Calling f(), foo(2), bar(4, 3), baz(':', ')') will evaluate the functions and
will print the output during Pandoc conversion, but, what if we want to...
1. ...write the evaluation result instead of the function call?
For example, see `6` instead of `f()`, or `:)` instead of `baz(':', ')')`.
2. ...remove the function call? So you don't see `f()` anymore.
3. ...avoid evaluation?
4. ...write the evaluation result to a file?
5. ...write the evaluated code to a file?
6. ...write Lisp code as Lua code to a file?
Well, we can do that with *reserved kwargs*. All reserved kwargs are optional
(you don't declare them) and start with underscore (`_`):
* `_action`: indicates action to perfom with the function call; can be:
* `'flip'`: puts its evaluation result instead;
* `'wipe'`: deletes it from source document but still calls it;
* `'skip'`: doesn't perform call;
* `'kill'`: doesn't perform call and deletes it from source.
* `_eval`: saves evaluation to file; takes file path string as value.
* `_code`: saves code to file; takes file path string as value.
* `_lua`: converts Lisp code to Lua and saves it to file; takes file path
string as value.
With reserved kwargs, we can finally replace f() by its evaluation result like
this: f(_action: 'flip'); or skip its evaluation: f(_action: 'skip').
We can also save different files:
* The avaluation results of foo(4, _eval: 'results.txt') and bar(5, 4, _eval:
'results.txt').
* The code of foo(4, _code: 'code.lisp') and bar(5, 4, _code: 'code.lisp').
* The Lua code of foo(4, _lua: 'code.lua') and bar (5, 4, _lua: 'code.lua').

View File

View File

@ -1,23 +1,23 @@
# Makes distribution release
# Variables
NAME="linp.lua"
NAME="lin.lua"
DIST=dist/$NAME
LICENSE="--[[
Literate Pandoc & Fennel Bundle:
Computable Pandoc & Fennel Bundle:
A Pandoc filter for literate and natural programming
Computable Pandoc:
(C) 2023 perro hi@perrotuerto.blog
License: GPLv3 https://git.cuates.net/perro/computable-pandoc/src/branch/no-masters/LICENSE.txt
Source: https://git.cuates.net/perro/computable-pandoc
Fennel:
(C) 2016-2023 Calvin Rose and contributors
License: MIT License https://git.sr.ht/~technomancy/fennel/tree/main/item/LICENSE
Source: https://sr.ht/~technomancy/fennel or https://github.com/bakpakin/Fennel/issues
Website: https://fennel-lang.org
Literate Pandoc:
(C) 2023 perro hi@perrotuerto.blog
License: GPLv3 https://git.cuates.net/perro/literate-pandoc/src/branch/no-masters/LICENSE.txt
Source: https://git.cuates.net/perro/literate-pandoc
]]--"
# Merges Fennel and Literate Pandoc
# Bundles Fennel and computable Pandoc
(echo "$LICENSE") > $DIST
head -n -1 opt/fennel.lua >> $DIST
echo "local fnl = mod" >> $DIST

View File

@ -1,7 +1,7 @@
# Makes JSON test files
# Variables
FILTER=dist/linp.lua
FILTER=dist/lin.lua
FILES="tests/*.md"
for file in $FILES; do

View File

@ -1,7 +1,7 @@
# Makes tests
# Variables
FILTER=dist/linp.lua
FILTER=dist/lin.lua
FILES="tests/*.md"
VERBOSE=false
CMD="sh $0"

View File

@ -2,7 +2,7 @@
return {
{
-- Parses LiNP declarations
-- Parses LIN declarations
CodeBlock = function(codeblock)
return lit.parse_declarations(codeblock)
end,
@ -13,7 +13,7 @@ return {
str = pandoc.utils.stringify(quoted.content):gsub('"', '\\"')
return '"' .. str .. '"'
end,
-- Parses and does LiNP calls
-- Parses and does LIN calls
Inlines = function(inlines)
return lit.parse_calls(inlines)
end,