文件列表:

CHANGELOG.md (313, 2023-04-27)
LICENSE (11358, 2023-04-27)
Makefile (236, 2023-04-27)
Setup.hs (46, 2023-04-27)
airloom.cabal (2702, 2023-04-27)
airloom.jpg (129753, 2023-04-27)
app/ (0, 2023-04-27)
app/Main.hs (86, 2023-04-27)
example/ (0, 2023-04-27)
example/hello-world/ (0, 2023-04-27)
example/hello-world/Makefile (309, 2023-04-27)
example/hello-world/expected.md (435, 2023-04-27)
example/hello-world/hello.c (202, 2023-04-27)
example/hello-world/hello.md (334, 2023-04-27)
package.yaml (1556, 2023-04-27)
src/ (0, 2023-04-27)
src/AirLoom.hs (101, 2023-04-27)
src/AirLoom/ (0, 2023-04-27)
src/AirLoom/Cli.hs (3460, 2023-04-27)
src/AirLoom/Lift.hs (3474, 2023-04-27)
src/AirLoom/Parser.hs (2947, 2023-04-27)
src/AirLoom/Store.hs (1743, 2023-04-27)
src/AirLoom/Weave.hs (930, 2023-04-27)
stack.yaml (2208, 2023-04-27)
stack.yaml.lock (539, 2023-04-27)
test/ (0, 2023-04-27)
test/Spec.hs (429, 2023-04-27)
test/TestLift.hs (5920, 2023-04-27)
test/TestParser.hs (6371, 2023-04-27)
test/TestStore.hs (999, 2023-04-27)
test/TestWeave.hs (1306, 2023-04-27)

>The programmer, like the poet, works only slightly removed from pure >thought-stuff. He builds his castles in the air, from air, creating by exertion >of the imagination > >— Fred Brooks, _The Mythical Man-Month_ # Air Loom **Air Loom** is a reverse literate programming tool: it takes code and documentation and weaves them together. It is both language-agnostic and markup language-agnostic. ## Example Given a `hello.c` file: ```c++ // loom:start(file) #include #include int main(void) { // loom:start(printf) printf("Hello, World!\n"); // loom:end(printf) return EXIT_SUCCESS; } // loom:end(file) ``` And `hello.md`: ~~~markdown # Hello, World in C Traditionally, the way to kick the tires on a programming language is to write a program that simply prints "Hello, world!" and exits. In C, the function for printing text is called `printf`, and we use it like this: ```c loom:include(printf) ``` The whole program looks like this: ```c loom:include(file) ``` ~~~ Then the following: ```bash $ airloom lift hello.c -o frags.json $ airloom weave hello.md -f frags.json -o docs.md ``` Will produce a file `docs.md` with the following contents: ~~~markdown # Hello, World in C Traditionally, the way to kick the tires on a programming language is to write a program that simply prints "Hello, world!" and exits. In C, the function for printing text is called `printf`, and we use it like this: ```c printf("Hello, World!\n"); ``` The whole program looks like this: ```c #include #include int main(void) { printf("Hello, World!\n"); return EXIT_SUCCESS; } ``` ~~~ ## Conceptual Overview Traditionally, there are two approaches to literate programming: 1. You write code inside your documentation, and a program extracts and concatenates the listings into source code. This worked in the 70's, but nowadays, you lose all the benefits of IDEs. 2. A newer approach is to write the documentation within the code as block comments, then a program strips the comment markers and turns everything that's not a comment into a code block. The problem with this approach is many languages require declarations to appear in a specific order, which is rarely the ideal reading order. With Air Loom, you write your code in source files, retaining all the benefits of using IDEs, and use comment directives to define named chunks of code called _fragments_. Then, in your documentation, you use directives to include fragments. Air Loom then lifts the fragments out of the code and weaves them into the documentation. Code and documentation are entirely separated. ## Usage The `lift` command extracts fragments from a set of files into a fragments file: ```bash airloom lift lib.c hello.c test.c -o fragments.json ``` The `weave` command takes a number of documentation files and a fragments file, it weaves the fragments into the documentation and concatenates them together: ```bash airloom weave intro.md examples.md api.md -f fragments.json -o docs.md ``` If you don't want to concatenate the output, just process them one file at a time: ```bash airloom weave intro.md -f fragments.json -o build/intro.md airloom weave examples.md -f fragments.json -o build/examples.md airloom weave api.md -f fragments.json -o build/api.md ``` ## Example Makefile Usage The following is an example of using Air Loom with `make`: ```make SRC := src/*.c FRAGS := fragments.json DOCS := intro.md concepts.md frontend.md core.md backend.md api.md MAN := manual.md $(FRAGS): $(SRC) airloom lift $(SRC) -o $(FRAGS) $(MAN): $(FRAGS) $(DOCS) airloom weave $(DOCS) -f $(FRAGS) -o $(MAN) clean: rm $(FRAGS) ``` ## Building You need [stack][stack] installed. Then: [stack]: https://docs.haskellstack.org/en/stable/ ```bash $ git clone https://github.com/eudoxia0/airloom.git $ cd airloom $ make $ sudo make install ``` ## Uses Projects or articles that use Air Loom. - [_Dependency Resolution Made Simple_](https://borretti.me/article/dependency-resolution-made-simple) ([Source](https://github.com/eudoxia0/eudoxia0.github.io/tree/2344de581ed95588e19b68769ccbcada985c1a10/assets/content/dependency-resolution-made-simple)) ## Future Work - Warnings - Warn when a file has no fragments. - Warn when there are unused fragments. - Complete mode: every non-blank line must be part of a fragment. - Escaping: allow prefixing directives with `\` to skip processing. - Transclusion escaping: - When transcluding code into e.g. XML, it would be useful to have an option to escape incompatible characters. ## License Copyright (c) 2023 [Fernando Borretti](https://borretti.me/). Licensed under the Apache 2.0 license.

近期下载者：

相关文件：

评论：[我要评论] [举报此文件]

收藏者：