gdritter repos bricoleur / 671ba3b
Update remaining references to collage Getty Ritter 6 years ago
7 changed file(s) with 57 addition(s) and 57 deletion(s). Collapse all Expand all
1 The `collage` tool is a tool for writing documents that rely on code samples while keeping the code samples up-to-date.
1 The `bricoleur` tool is a tool for writing documents that rely on code samples while keeping the code samples up-to-date.
22
33 # Including an Entire Source File
44
5 To create a `collage` project, create a directory that contains a file called `collage` as well as one or more subdirectories that contain the code that you want to expose, and a document in whatever plain text format you want. For example, say that we have a piece of Python source we'd like to write about: let's create a project directory as well as the subdirectory for the Python program, and initialize it with a trivial Python program:
5 To create a `bricoleur` project, create a directory that contains a file called `bricoleur` as well as one or more subdirectories that contain the code that you want to expose, and a document in whatever plain text format you want. For example, say that we have a piece of Python source we'd like to write about: let's create a project directory as well as the subdirectory for the Python program, and initialize it with a trivial Python program:
66
77 ```bash
88 $ mkdir my-post
2323 Isn't that easy?
2424 ```
2525
26 Notice that the code block there contains a string in guillemets (`«hello»`) instead of the actual source code. Now, finally, we write a `collage` file that ties these together:
26 Notice that the code block there contains a string in guillemets (`«hello»`) instead of the actual source code. Now, finally, we write a `bricoleur` file that ties these together:
2727
2828
2929 ```
4646 )
4747 ```
4848
49 In our directory, we can now run `collage test` and we'll get output that looks like the following:
49 In our directory, we can now run `bricoleur test` and we'll get output that looks like the following:
5050
5151 ```bash
52 $ collage test
52 $ bricoleur test
5353 testing my-document.md
5454 - building source hello
5555 - running "python main.py" in my-post/python-example
5656 Hello, world
5757 ```
5858
59 we can also run `collage splice` to stitch the source code in question into our document:
59 we can also run `bricoleur splice` to stitch the source code in question into our document:
6060
6161 ```bash
62 $ collage splice
62 $ bricoleur splice
6363 Here is a document describing a snippet of Python source. A 'Hello
6464 World' program in Python looks like this:
6565
7272
7373 # Including Multiple Source Files Per Project
7474
75 In addition to exposing a single source file, we can expose more than one. Replace the `(file "my-file")` expression with a map from names to files, and then use forward slashes to refer to names within this mapping. For example, if I added a `helper.py` file, and I wanted to use both, my Markdown file could reference `«hello/main»` and `«hello/helper»`, and my `collage` file could be updated to include
75 In addition to exposing a single source file, we can expose more than one. Replace the `(file "my-file")` expression with a map from names to files, and then use forward slashes to refer to names within this mapping. For example, if I added a `helper.py` file, and I wanted to use both, my Markdown file could reference `«hello/main»` and `«hello/helper»`, and my `bricoleur` file could be updated to include
7676
7777 ```
7878 # ...
9999 main()
100100 ```
101101
102 The two comment lines around the `main` function demarcate a _section_ of the file: `collage` will look for those substrings and then select only the lines of the file in between those two. We can refer to that section identifier just like we refer to multiple files above, as `«helper/main»`. We can then update our `collage` file to read:
102 The two comment lines around the `main` function demarcate a _section_ of the file: `bricoleur` will look for those substrings and then select only the lines of the file in between those two. We can refer to that section identifier just like we refer to multiple files above, as `«helper/main»`. We can then update our `bricoleur` file to read:
103103
104104 ```
105105 # ...
1 (document "main.md"
2
3 {
4 name "rust-sample"
5 dir "s1"
6 cmd [ "cargo clean" "cargo build" ]
7 expose (file "src/main.rs")
8 }
9
10 {
11 name "haskell-sample"
12 dir "s2"
13 cmd [ "rm -rf dist-newstyle" "cabal new-build" ]
14 expose (sections "Main.hs")
15 }
16
17 )
+0
-17
examples/basic-example/collage less more
1 (document "main.md"
2
3 {
4 name "rust-sample"
5 dir "s1"
6 cmd [ "cargo clean" "cargo build" ]
7 expose (file "src/main.rs")
8 }
9
10 {
11 name "haskell-sample"
12 dir "s2"
13 cmd [ "rm -rf dist-newstyle" "cabal new-build" ]
14 expose (sections "Main.hs")
15 }
16
17 )
1 (document "post.md"
2
3 { name ocaml
4 dir "ocaml-source"
5 cmd [
6 "rm -f main main.cmi main.cmo"
7 "ocamlc main.ml -o main"
8 ]
9 expose (sections "main.ml")
10 }
11
12 { name java
13 dir "java-source"
14 cmd [
15 "rm -f Main.class"
16 "javac Main.java"
17 ]
18 expose (sections "Main.java")
19 }
20
21 { name crystal
22 dir "crystal-source"
23 cmd [
24 "crystal build src/crystal-source.cr"
25 ]
26 expose (sections "src/crystal-source.cr")
27 }
28
29 )
+0
-29
examples/structural-types/collage less more
1 (document "post.md"
2
3 { name ocaml
4 dir "ocaml-source"
5 cmd [
6 "rm -f main main.cmi main.cmo"
7 "ocamlc main.ml -o main"
8 ]
9 expose (sections "main.ml")
10 }
11
12 { name java
13 dir "java-source"
14 cmd [
15 "rm -f Main.class"
16 "javac Main.java"
17 ]
18 expose (sections "Main.java")
19 }
20
21 { name crystal
22 dir "crystal-source"
23 cmd [
24 "crystal build src/crystal-source.cr"
25 ]
26 expose (sections "src/crystal-source.cr")
27 }
28
29 )
5757 cwd <- Sys.getCurrentDirectory
5858 options <- Opt.execParser opts
5959 return $ if null (optFile options)
60 then options { optFile = cwd Sys.</> "collage" }
60 then options { optFile = cwd Sys.</> "bricoleur" }
6161 else options
1313 import qualified Bricoleur.Commands.Splice as Cmd
1414 import qualified Bricoleur.Commands.Test as Cmd
1515
16 -- | Run the main @collage@ function with the provided options.
16 -- | Run the main @bricoleur@ function with the provided options.
1717 main :: Opt.Options -> IO ()
1818 main opts = do
1919 configMb <- Conf.getConfig (Opt.optFile opts)