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