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