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