From 67df6fedaea83b8159fbadbadf460a1f3dd98c51 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Fri, 5 Jan 2024 12:31:48 +0100
Subject: Add cowboy:get_env/2,3

---
 doc/src/manual/cowboy.asciidoc         |  1 +
 doc/src/manual/cowboy.get_env.asciidoc | 78 ++++++++++++++++++++++++++++++++++
 doc/src/manual/cowboy.set_env.asciidoc |  1 +
 3 files changed, 80 insertions(+)
 create mode 100644 doc/src/manual/cowboy.get_env.asciidoc

(limited to 'doc')

diff --git a/doc/src/manual/cowboy.asciidoc b/doc/src/manual/cowboy.asciidoc
index c213df0..9298b6d 100644
--- a/doc/src/manual/cowboy.asciidoc
+++ b/doc/src/manual/cowboy.asciidoc
@@ -14,6 +14,7 @@ manipulating Ranch listeners.
 * link:man:cowboy:start_clear(3)[cowboy:start_clear(3)] - Listen for connections using plain TCP
 * link:man:cowboy:start_tls(3)[cowboy:start_tls(3)] - Listen for connections using TLS
 * link:man:cowboy:stop_listener(3)[cowboy:stop_listener(3)] - Stop the given listener
+* link:man:cowboy:get_env(3)[cowboy:get_env(3)] - Retrieve a listener's environment value
 * link:man:cowboy:set_env(3)[cowboy:set_env(3)] - Update a listener's environment value
 
 == Types
diff --git a/doc/src/manual/cowboy.get_env.asciidoc b/doc/src/manual/cowboy.get_env.asciidoc
new file mode 100644
index 0000000..c2895b0
--- /dev/null
+++ b/doc/src/manual/cowboy.get_env.asciidoc
@@ -0,0 +1,78 @@
+= cowboy:get_env(3)
+
+== Name
+
+cowboy:get_env - Retrieve a listener's environment value
+
+== Description
+
+[source,erlang]
+----
+get_env(Name :: ranch:ref(),
+        Key  :: atom())
+    -> any()
+
+get_env(Name    :: ranch:ref(),
+        Key     :: atom(),
+        Default :: any())
+    -> any()
+----
+
+Retrieve an environment value for a previously started
+listener.
+
+This function may crash when the key is missing from the
+environment and a default value is not provided.
+
+== Arguments
+
+Name::
+
+The name of the listener to access.
++
+The name of the listener is the first argument given to the
+link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
+link:man:cowboy:start_tls(3)[cowboy:start_tls(3)] or
+link:man:ranch:start_listener(3)[ranch:start_listener(3)] function.
+
+Key::
+
+The key in the environment map. Common keys include `dispatch`
+and `middlewares`.
+
+Default::
+
+The default value if the key is missing.
+
+== Return value
+
+The environment value is returned on success.
+
+If a default was provided and the key is missing, then the
+default value is returned.
+
+An `exit:badarg` exception is thrown when the listener does
+not exist.
+
+An `exit:{badkey, Key}` exception is thrown when the key
+requested is missing and no default was provided.
+
+== Changelog
+
+* *2.11*: Function introduced.
+
+== Examples
+
+.Retrieve a listener's routes
+[source,erlang]
+----
+Dispatch = cowboy:get_env(example, dispatch).
+----
+
+== See also
+
+link:man:cowboy(3)[cowboy(3)],
+link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
+link:man:cowboy:start_tls(3)[cowboy:start_tls(3)],
+link:man:cowboy:set_env(3)[cowboy:set_env(3)],
+link:man:ranch:get_protocol_options(3)[ranch:get_protocol_options(3)]
diff --git a/doc/src/manual/cowboy.set_env.asciidoc b/doc/src/manual/cowboy.set_env.asciidoc
index 30af485..fc0d1f7 100644
--- a/doc/src/manual/cowboy.set_env.asciidoc
+++ b/doc/src/manual/cowboy.set_env.asciidoc
@@ -76,4 +76,5 @@ cowboy:set_env(example, dispatch, Dispatch).
 link:man:cowboy(3)[cowboy(3)],
 link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
 link:man:cowboy:start_tls(3)[cowboy:start_tls(3)],
+link:man:cowboy:get_env(3)[cowboy:get_env(3)],
 link:man:ranch:set_protocol_options(3)[ranch:set_protocol_options(3)]
-- 
cgit v1.2.3