1 83c817b4 2021-10-13 op # gemini.core
 2 1d126b15 2021-10-13 op 
 3 83c817b4 2021-10-13 op A Clojure library to make Gemini requests.
 4 1d126b15 2021-10-13 op 
 5 1d126b15 2021-10-13 op 
 6 1d126b15 2021-10-13 op ## Usage
 7 1d126b15 2021-10-13 op 
 8 83c817b4 2021-10-13 op Import the library for e.g. with:
 9 83c817b4 2021-10-13 op 
10 1d126b15 2021-10-13 op ```clojure
11 1d126b15 2021-10-13 op user=> (require '[gemini.core :as gemini])
12 1d126b15 2021-10-13 op ```
13 1d126b15 2021-10-13 op 
14 83c817b4 2021-10-13 op ### Documentation
15 1d126b15 2021-10-13 op 
16 1d126b15 2021-10-13 op `fetch` makes a Gemini request and returns a map with `:request`,
17 1d126b15 2021-10-13 op `:meta`, `:code` and `:body` as keys, or `:error` if an error occur.
18 1d126b15 2021-10-13 op 
19 83c817b4 2021-10-13 op The request needs to be closed afterwards using `close`.
20 1d126b15 2021-10-13 op 
21 1d126b15 2021-10-13 op ```clojure
22 1d126b15 2021-10-13 op user=> (gemini/fetch "gemini://gemini.circumlunar.space/")
23 1d126b15 2021-10-13 op {:request
24 1d126b15 2021-10-13 op  #object[com.omarpolo.gemini.Request 0x3b270767 "com.omarpolo.gemini.Request@3b270767"],
25 1d126b15 2021-10-13 op  :meta "gemini://gemini.circumlunar.space/",
26 1d126b15 2021-10-13 op  :code 31,
27 1d126b15 2021-10-13 op  :body
28 1d126b15 2021-10-13 op  #object[java.io.BufferedReader 0x49358b66 "java.io.BufferedReader@49358b66"]}
29 1d126b15 2021-10-13 op ```
30 1d126b15 2021-10-13 op 
31 83c817b4 2021-10-13 op `body-as-string!` reads all the response into a string and returns it.
32 83c817b4 2021-10-13 op It also closes the request automatically.
33 1d126b15 2021-10-13 op 
34 1d126b15 2021-10-13 op ```clojure
35 1d126b15 2021-10-13 op user=> (-> (gemini/fetch "gemini://gemini.circumlunar.space/")
36 1d126b15 2021-10-13 op            gemini/body-as-string!)
37 1d126b15 2021-10-13 op "# Project Gemini\n\n## Overview\n\nGemini is a new internet protocol which..."
38 1d126b15 2021-10-13 op ```
39 1d126b15 2021-10-13 op 
40 83c817b4 2021-10-13 op `close` closes a request.  It needs to be called after every
41 83c817b4 2021-10-13 op (successful) request.
42 1d126b15 2021-10-13 op 
43 83c817b4 2021-10-13 op ```clojure
44 83c817b4 2021-10-13 op user=> (let [req (gemini/fetch "...")]
45 83c817b4 2021-10-13 op          (when-not (:error req)
46 83c817b4 2021-10-13 op 		   ;; do something with req
47 83c817b4 2021-10-13 op 		   ,,,
48 83c817b4 2021-10-13 op 		   (gemini/close req)))
49 83c817b4 2021-10-13 op ```
50 1d126b15 2021-10-13 op 
51 83c817b4 2021-10-13 op `with-request` is a macro like `with-open` to making connection
52 83c817b4 2021-10-13 op easily.  It automatically closes the request and evaluates the body
53 83c817b4 2021-10-13 op only when the request is successful, otherwise throws an exception.
54 1d126b15 2021-10-13 op 
55 1d126b15 2021-10-13 op ```clojure
56 83c817b4 2021-10-13 op user=> (with-request [req (gemini/fetch "gemini://gemini.circumlunar.space/")]
57 1d126b15 2021-10-13 op          ,,,)
58 1d126b15 2021-10-13 op ```
59 83c817b4 2021-10-13 op 
60 83c817b4 2021-10-13 op 
61 83c817b4 2021-10-13 op ## Streaming content
62 83c817b4 2021-10-13 op 
63 83c817b4 2021-10-13 op The `:body` keyword in the returned map is an instance of a Java
64 83c817b4 2021-10-13 op BufferedReader, so streaming content is easy.
65 83c817b4 2021-10-13 op 
66 83c817b4 2021-10-13 op However, `body-as-string!` needs to materialise the full reply, so in
67 83c817b4 2021-10-13 op case of a streaming request it will never return!
68 83c817b4 2021-10-13 op 
69 83c817b4 2021-10-13 op 
70 83c817b4 2021-10-13 op ## text/gemini
71 83c817b4 2021-10-13 op 
72 83c817b4 2021-10-13 op This library only implements the network part of Gemini, it doesn't
73 83c817b4 2021-10-13 op try to handle any kind of content.  To handle text/gemini you can use
74 83c817b4 2021-10-13 op e.g. the [gemtext][gemtext] library:
75 83c817b4 2021-10-13 op 
76 83c817b4 2021-10-13 op ```clojure
77 83c817b4 2021-10-13 op user=> (require '[gemtext.core :as gemtext])
78 83c817b4 2021-10-13 op nil
79 83c817b4 2021-10-13 op user=> (gemini/with-request [req (gemini/fetch "gemini://gemini.circumlunar.space/")]
80 83c817b4 2021-10-13 op          (gemtext/parse (:body req)))
81 83c817b4 2021-10-13 op [[:header-1 "Project Gemini"]
82 83c817b4 2021-10-13 op  [:text ""]
83 83c817b4 2021-10-13 op  [:header-2 "Overview"]
84 83c817b4 2021-10-13 op  [:text ""]
85 83c817b4 2021-10-13 op  [:text "Gemini is a new internet protocol which:"]
86 83c817b4 2021-10-13 op  ,,,]
87 83c817b4 2021-10-13 op ```
88 83c817b4 2021-10-13 op 
89 0ccdb5e9 2021-10-13 op The [gemtext][gemtext] library supports streaming via the
90 0ccdb5e9 2021-10-13 op `gemtext.core/parse` transducer:
91 83c817b4 2021-10-13 op 
92 0ccdb5e9 2021-10-13 op ```clojure
93 0ccdb5e9 2021-10-13 op user=> (gemini/with-request [req (gemini/fetch "gemini://gemini.circumlunar.space/")]
94 0ccdb5e9 2021-10-13 op          (transduce gemtext/parser conj [] (line-seq (:body req))))
95 0ccdb5e9 2021-10-13 op ,,,
96 0ccdb5e9 2021-10-13 op ```
97 0ccdb5e9 2021-10-13 op 
98 0ccdb5e9 2021-10-13 op 
99 83c817b4 2021-10-13 op [gemtext]: https://github.com/omar-polo/gemtext