### Start Shadow-CLJS Server Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc This bash command initiates the shadow-cljs development server. It's shown in the context of preventing accidental release builds with Guardrails enabled, by ensuring the server is running in a development mode that might cache Guardrails enablement. ```bash # in one terminal: $ shadow-cljs server ``` -------------------------------- ### Static Exclusions Export File Example Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc An example of the `guardrails-export.edn` file used by library authors to define static exclusions for their public API. ```clojure ;; src/main/guardrails-export.edn {:exclude #{com.fulcrologic.statecharts.algorithms.v20150901-impl}} ``` -------------------------------- ### Spec Failure Example Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc An example of a runtime error when a function defined with Guardrails receives an argument that does not satisfy its specified type. ```bash user=> (f 3.2) ERROR /Users/user/project/src/com/domain/app_ns.clj:12 f's argument list -- Spec failed -------------------- [3.2] ^^^ should satisfy int? or string? -- Relevant specs ------- :user/thing: (clojure.spec.alpha/or :i clojure.core/int? :s clojure.core/string?) ``` -------------------------------- ### Configure Guardrails for shadow-cljs Release Builds Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Demonstrates how to configure Guardrails for shadow-cljs release builds by setting JVM options. It highlights the discouraged practice of enabling Guardrails in production builds and provides the correct JVM option syntax. ```clojure :jvm-opts ["-Dguardrails.enabled=production"] ``` -------------------------------- ### Configure Shadow-CLJS for Guardrails Development Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc This snippet demonstrates the recommended shadow-cljs configuration for Guardrails. It sets up separate `:dev` and `:release` build profiles, enabling Guardrails checks only in the development environment by setting `goog.DEBUG` and `external-config` for Guardrails. This prevents performance degradation in production builds. ```clojure { :builds {:main {:target :browser ... :dev {:compiler-options {:closure-defines {'goog.DEBUG true} :external-config {:guardrails {}}}} :release {}}} ... } ``` -------------------------------- ### Clojure: Using Spec and Malli with Guardrails >defn Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Demonstrates how to use Guardrails' `>defn` macro with both Clojure.spec.alpha and Malli for defining function signatures and validation schemas. It shows how to require the respective Guardrails namespaces and alias them for concurrent use. ```clojure (ns foo.bar (:require [clojure.spec.alpha :as s] [com.fulcrologic.guardrails.core :as gr.spec] [com.fulcrologic.guardrails.malli.core :as gr.malli :refer [=> | ?]])) (gr.spec/>defn f [x] [(s/keys :req [:thing/x]) => int?] ...) (gr.malli/>defn f [x] [[:map :thing/x] => :int] ...) ``` -------------------------------- ### APIDOC: Guardrails Configuration Options Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Details the configuration parameters available for Guardrails, typically managed via a `guardrails.edn` file or JVM properties. These options control Guardrails' behavior, including enabling/disabling, performance tuning, and error reporting. ```APIDOC Configuration Options: - :defn-macro: Alias for another defn macro if needed. - :expound: Map of Expound configuration options (e.g., :show-valid-values?, :print-specs?). - :guardrails/mcps: Maximum checks per second. Limits function call checks to prevent performance impact. Spread checks evenly. - :guardrails/stack-trace: Controls stack trace output format (:prune, :full, :none). Default is :full. - :guardrails/use-stderr?: Boolean to direct output to stderr. Useful for REPLs. Default is false. - :guardrails/compact?: Boolean to compress problem explanations. Default is false. - :guardrails/trace?: Boolean to keep track of active GR-instrumented calls as a stack for error reporting. Default is false. - :guardrails/throw-on-spec-failure?: Boolean to determine if spec failures on args or return values should throw an exception (always logs a message). Default is true. ``` -------------------------------- ### APIDOC: Enabling Guardrails Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Explains the methods for enabling Guardrails, which is disabled by default to prevent performance issues in production. Enabling is typically done via JVM options or specific configurations in build tools. ```APIDOC Enabling Guardrails: Guardrails is disabled by default. To enable: 1. JVM Option: Use the system property `-Dguardrails.enabled=true`. 2. ClojureScript (shadow-cljs): Include an empty configuration map in your shadow-cljs configuration to enable it. When not explicitly enabled, `>defn` behaves identically to a standard `defn`. ``` -------------------------------- ### Clojure: Registering Malli Schemas with >def Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Shows the usage of the `>def` macro provided by `com.fulcrologic.guardrails.malli.core`. This macro is analogous to Clojure's `def` and registers a Malli schema under a qualified keyword in the Guardrails registry, simplifying schema definition. ```clojure (require '[com.fulcrologic.guardrails.malli.core :as gr.malli]) (gr.malli/>def :member/name :string) ``` -------------------------------- ### Clojure Configuration Override Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Demonstrates how to override Guardrails configuration settings within a shadow-cljs build configuration file. This allows for fine-grained control over library behavior per build. ```clojure ... :app {:target :browser :dev {:compiler-options {:external-config {:guardrails {:throw? false}} :closure-defines {'goog.DEBUG true}}}} ... ``` -------------------------------- ### Define Function with Spec and Return Type Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Demonstrates defining a Clojure function using `>defn` with inline specification for arguments and return values, including a 'such-that' predicate for the return value. ```clojure (>defn ranged-rand [start end] [int? int? | #(< start end) ; `|` = such that => int? | #(>= % start) #(< % end)] (+ start (long (rand (- end start))))) ``` -------------------------------- ### Guardrails Configuration Functions Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Functions for controlling Guardrails checks at runtime, allowing granular or broad exclusion/inclusion of namespaces or functions. ```APIDOC com.fulcrologic.guardrails.config: - `exclude-checks! ns-or-fn` - Turns off checking for an entire namespace or a single fully-qualified symbol. - Parameters: - `ns-or-fn`: A namespace symbol (e.g., `'my.namespace`) or a fully-qualified function symbol (e.g., `'my.namespace/my-function`). - Example: ```clojure (config/exclude-checks! 'my.namespace) (config/exclude-checks! 'my.namespace/my-function) ``` - `allow-checks! ns-or-fn` - Turns on checking for an entire namespace or a single fully-qualified symbol. - Parameters: - `ns-or-fn`: A namespace symbol or a fully-qualified function symbol. - Example: ```clojure (config/allow-checks! 'my.namespace) (config/allow-checks! 'my.namespace/my-function) ``` - `excluded? ns-or-fn` - Indicates if the given namespace or function is currently excluded from checks. - Parameters: - `ns-or-fn`: A namespace symbol or a fully-qualified function symbol. - Returns: A boolean value (`true` if excluded, `false` otherwise). - Example: ```clojure (config/excluded? 'my.namespace) ``` - `clear-exclusions!` - Resets all exclusions, making all code subject to checks. This overrides any previously set exclusions, including those from static export files. - No parameters. - Example: ```clojure (config/clear-exclusions!) ``` - `reset-exclusions!` - Re-applies any library exclusion exports found at load time. This restores exclusions to their initial state as defined in `guardrails-export.edn` files. - No parameters. - Example: ```clojure (config/reset-exclusions!) ``` ``` -------------------------------- ### Gspec Syntax for Function Specifications Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Explains the Gspec syntax used for defining function specifications in Clojure, including argument specifications, return specifications, and 'such that' predicates. It covers single/multiple arities, variadic arguments, nilable types, and nested specs. ```APIDOC Gspec Syntax Overview: [arg-specs* (| arg-preds+)? \=> ret-spec (| ret-preds+)? (<- generator-fn)?] | : such that - arg-specs: Specifications for function arguments. - arg-preds: Additional predicates for arguments. - \=>: Separator between argument and return specifications. - ret-spec: Specification for the return value. - ret-preds: Additional predicates for the return value. - (<- generator-fn): Optional generator function. Single/Multiple Arities: Define specs after the argument list for each arity. Example: (>defn myf ([x] [int? => number?] ...) ([x y] [int? int? => int?] ...)) Variadic Argument Lists: Use standard fspec notation for variadic arguments. Example: (>fdef clojure.core/max [x & more] [number? (s/* number?) => number?]) Such That Predicates: Add '|' followed by a predicate function to specify conditions. - Argument predicates use argument symbols. - Return predicates use '%' for the return value. Example: (>defn f [i] [int? | #(< 0 i 10) => int? | #(pos-int? %)] ...) Nilable Specs: Use '?' as shorthand for s/nilable. Example: (>fdef clojure.core/empty? [coll] [(? seqable?) => boolean?]) Nested Specs: Define nested specs using the same syntax within vectors or lists. Example: (>fdef clojure.core/map-indexed ([f] [[nat-int? any? => any?] => fn?]) ([f coll] [[nat-int? any? => any?] (? seqable?) => seq?])) For nilable nested specs, use '?' within a vector: Example: (>fdef clojure.core/set-validator! [a f] [atom? [? [any? => any?]] => any?]) Note on Nested Specs with 'any?': - If one or more 'any?' argspecs are present, it desugars to 'ifn?' to aid generative testing. - This can be overridden by providing a generator (e.g., adding '\<-' or ':gen'). - Documenting functions with 'any? \=> any?' is useful for clarity, even if it desugars. Gspec Advantages: - Conciseness and readability. - Inline documentation visible in editors. - Simplified specs for multi-arity functions. - Easy refactoring of parameters due to valid Clojure syntax. ``` -------------------------------- ### Define Function with Development Spec Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Illustrates defining a function using `>defn` that utilizes a development-only spec (`::thing`) for its argument and specifies the return type. ```clojure (>defn f [i] [::thing => int?] (if (string? i) 0 (inc i))) ``` -------------------------------- ### Define Development-Only Spec Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Shows how to define a specification using `>def` which is intended for development-time checks and can be removed from production builds. ```clojure (>def ::thing (s/or :i int? :s string?)) ``` -------------------------------- ### Clojure: Merging Custom Schemas into Guardrails Malli Registry Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Illustrates how to merge custom schema definitions into the mutable Guardrails Malli registry. This is essential for using qualified keywords in Malli schemas within `>defn` definitions, reducing boilerplate and avoiding keyword collisions. ```clojure (require '[com.fulcrologic.guardrails.malli.registry :as gr.reg]) (gr.reg/merge-schemas! my-custom-stuff my-other-stuff) ``` -------------------------------- ### Clojure Function with Max Checks Per Second (MCPS) Limit Source: https://github.com/fulcrologic/guardrails/blob/main/README.adoc Shows how to apply a per-function limit for checks per second using the `:guardrails/mcps` metadata attribute. This is a recommended approach for performance tuning functions that are called frequently. ```clojure (>defn f {:guardrails/mcps 100} [x] [int? => int?] ...) ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.