diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..0957abb --- /dev/null +++ b/.editorconfig @@ -0,0 +1,8 @@ +[*] +indent_style = space +indent_size = 2 +tab_width = 8 +max_line_length = 80 +trim_trailing_whitespace = false +end_of_line = lf +insert_final_newline = true diff --git a/README.md b/README.md index a108a03..6838b2b 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ declarative DSL to setup MacroExpress routes. The Macro [Examples](https://github.com/Macro-swift/Examples) package contains a few examples which all can run straight from the source as -swift-sh scripts. +[swift-sh](https://github.com/mxcl/swift-sh) scripts. ```swift #!/usr/bin/swift sh @@ -80,5 +80,10 @@ app.listen(1337) We like feedback, GitHub stars, cool contract work, presumably any form of praise you can think of. -There is a `#microexpress` channel on the -[Noze.io Slack](http://slack.noze.io/). Feel free to join! +**Want to support my work**? +Buy an app: +[Code for SQLite3](https://apps.apple.com/us/app/code-for-sqlite3/id1638111010), +[Past for iChat](https://apps.apple.com/us/app/past-for-ichat/id1554897185), +[SVG Shaper](https://apps.apple.com/us/app/svg-shaper-for-swiftui/id1566140414), +[HMScriptEditor](https://apps.apple.com/us/app/hmscripteditor/id1483239744). +You don't have to use it! 😀 diff --git a/Sources/dotenv/dotenv.swift b/Sources/dotenv/dotenv.swift index 258083f..05abdab 100644 --- a/Sources/dotenv/dotenv.swift +++ b/Sources/dotenv/dotenv.swift @@ -3,7 +3,7 @@ // MacroExpress // // Created by Helge Heß on 02.07.20. -// Copyright © 2020 ZeeZide GmbH. All rights reserved. +// Copyright © 2020-2024 ZeeZide GmbH. All rights reserved. // #if os(Linux) @@ -17,13 +17,25 @@ import func MacroCore.__dirname import func fs.accessSync import let fs.R_OK +/** + * How to use: + * + * ```swift + * import dotenv + * + * dotenv.config() + * ``` + * + * This reads the `.env` file (located using `__dirname`), + * and adds the contents to the environment of the running process. + */ public enum dotenv {} public extension dotenv { #if swift(>=5.3) // oh this mess /** - * Read the .env config file, apply it to the environment, and return the + * Read the .env config file, apply it on the environment, and return the * parsed values. * * Important: Remember to call this as early as possible, otherwise Foundation diff --git a/Sources/express/Express.swift b/Sources/express/Express.swift index 1fec3e9..d776440 100644 --- a/Sources/express/Express.swift +++ b/Sources/express/Express.swift @@ -149,20 +149,61 @@ open class Express: SettingsHolder, MountableMiddlewareObject, MiddlewareObject, // MARK: - SettingsHolder - public func set(_ key: String, _ value: Any?) { + /** + * Sets or removes a configuration key in the settings store. + * + * Example: + * ```swift + * app.set("view engine", "html") + * .set("views", __dirname() + "/views") + * ``` + * + * - Parameters: + * - key: The name of the key, e.g. "view engine" + * - value: The associated value, if `nil` is passed in, the value is + * removed from the store. + * - Returns: `self` for chaining. + */ + @discardableResult + public func set(_ key: String, _ value: Any?) -> Self { if let v = value { settingsStore[key] = v } else { settingsStore.removeValue(forKey: key) } + return self } + + /** + * Returns the value of a configuration key from the settings store. + * + * Example: + * ```swift + * let engine = app.get("view engine") + * ``` + * + * - Parameters: + * - key: The name of the key, e.g. "view engine" + * - Returns: The value in the store, or `nil` if missing. + */ public func get(_ key: String) -> Any? { return settingsStore[key] } + // MARK: - Engines - var engines = [ String : ExpressEngine]() + var engines = [ String : ExpressEngine ]() - public func engine(_ key: String, _ engine: @escaping ExpressEngine) { + /** + * Sets an engine implementation. + * + * Example: + * ```swift + * app.engine("mustache", mustacheExpress) + * ``` + */ + @discardableResult + public func engine(_ key: String, _ engine: @escaping ExpressEngine) -> Self { engines[key] = engine + return self } diff --git a/Sources/express/Settings.swift b/Sources/express/Settings.swift index 81916d6..23b92cb 100644 --- a/Sources/express/Settings.swift +++ b/Sources/express/Settings.swift @@ -7,31 +7,89 @@ // /** - * Just a special kind of dictionary. The `Express` application class is + * Just a special kind of dictionary. The ``Express`` application class is * currently the sole example. * * Examples: + * ```swift + * app.set("env", "production") + * app.enable("x-powered-by") * - * app.set("env", "production") - * app.enable("x-powered-by") - * - * let env = app.settings.env + * let env = app.settings.env + * ``` */ public protocol SettingsHolder { - func set(_ key: String, _ value: Any?) + /** + * Sets or removes a configuration key in the settings store. + * + * Example: + * ```swift + * app.set("view engine", "html") + * .set("views", __dirname() + "/views") + * .enable("x-powered-by") + * ``` + * + * - Parameters: + * - key: The name of the key, e.g. "view engine" + * - value: The associated value, if `nil` is passed in, the value is + * removed from the store. + * - Returns: `self` for chaining. + */ + @discardableResult + func set(_ key: String, _ value: Any?) -> Self + + /** + * Returns the value of a configuration key from the settings store. + * + * Example: + * ```swift + * let engine = app.get("view engine") + * ``` + * + * - Parameters: + * - key: The name of the key, e.g. "view engine" + * - Returns: The value in the store, or `nil` if missing. + */ func get(_ key: String) -> Any? } public extension SettingsHolder { + /** + * Set configuration key in the settings store to `true`. + * + * Example: + * ```swift + * app.enable("x-powered-by") + * ``` + * + * - Parameters: + * - key: The name of the bool key, e.g. "view engine" + * - Returns: `self` for chaining. + */ @inlinable - func enable(_ key: String) { - set(key, true) + @discardableResult + func enable(_ key: String) -> Self { + return set(key, true) } + + /** + * Set configuration key in the settings store to `false`. + * + * Example: + * ```swift + * app.disable("x-powered-by") + * ``` + * + * - Parameters: + * - key: The name of the bool key, e.g. "view engine" + * - Returns: `self` for chaining. + */ @inlinable - func disable(_ key: String) { - set(key, false) + @discardableResult + func disable(_ key: String) -> Self { + return set(key, false) } @inlinable