CrossClj

0.22.0 docs

SourceDocs



RECENT

    active-clojure

    Clojars

    Nov 26, 2017


    OWNER
    active-group

    Readme

    Index of all namespaces


    « Project + dependencies

    Active Clojure: Various Clojure utilities in use at Active Group

    active.clojure.conditionDocsSource
    Conditions, protocol for communicating the causes of exceptions.
    
    This provides infrastructure for building *condition* objects.
    A condition object provides information about the cause of an exception.
    Conditions thus form a protocol.
    
    Clojure ex-info objects do not, by themselves, enough to form such
    a protocol, as they do not allow classifying an exception easily.
    
    This condition system builds on the design of
    [R6RS Scheme](http://www.r6rs.org/final/html/r6rs-lib/r6rs-lib-Z-H-8.html#node_sec_7.2).
    
    Condition objects are represented as specially marked ex-info objects.
    
    One notable difference to the R6RS design is that there is no user-facing type for 
    'simple conditions', nor are they regular records.
    active.clojure.configDocsSource
    Application configuration via a big map.
    
    A configuration is a nested key-value map.
    
    It contains top-level settings and sections of qualified settings, like so:
    
    
        {:top-level-setting-key 'foo
         {:section-key
          {:section-setting 'bar}}}
    
    Additionally, a config contains *profiles* with additional
    settings that can be mixed in, like so:
    
        {:top-level-setting-key 'foo
         {:section-key
          {:section-setting 'bar}}
         {:profiles
          {:dev
           {:top-level-setting-key 'bar
            {:section-key
             {:section-setting 'baz}}}}}}
    
    Each profile has the same format as the top-level configuration itself
      (sans the :profiles key).

    VARS

    A access access-section any-range any-value-range apply-profiles

    B boolean-range boolean?

    C ->Configuration check-section complete-section complete-settings configuration-object configuration-schema configuration?

    D default-string-range diff-configuration-objects diff-configurations

    I integer-between-range

    K keyword-range

    M make-configuration make-map-schema make-range make-range-error make-scalar-range make-section make-sequence-schema make-setting map->Configuration map->RangeError map->Schema map->Section map->SequenceSchema map->Setting map->ValueRange map-of-range map-schema-description map-schema-sections map-schema-sections-map map-schema-settings map-schema-settings-map map-schema? max-string-range merge-config-objects merge-config-objects-sans-profiles

    N non-nil-range nonempty-string-range normalize&check-config-object normalize&check-config-object-internal

    O one-of-range one-of-range-custom-compare optional-default-range optional-range or-dot-range

    P predicate-range

    R ->RangeError range-completer range-description range-error-path range-error-range range-error-value range-error? range-map range-reduce range? really-make-configuration

    S ->Schema ->Section ->SequenceSchema ->Setting schema schema-range schema-reduce section section-inherit? section-key section-schema section-subconfig section? sequable? sequence-of-range sequence-schema sequence-schema-description sequence-schema-element-schema sequence-schema? set-of-range setting setting-default-value setting-description setting-inherit? setting-key setting-or-section-key setting-range setting? slurpable-range string-range

    T tuple-of-range

    V ->ValueRange

    active.clojure.matchDocsSource
    Syntactic sugar for map matching around core.match.
    
    active.clojure.record-specDocsSource
    A re-implementation of active.clojure.record that makes use of
    Clojure's new spec library. Define records the same ways as in the old
    implemenation or use the new syntax to automatically generate specs.
    If a field has no explicit spec, defaults to any?.
    active.clojure.test-conditionDocsSource
    Support for using clojure.test and conditions together.
    
    The README below is fetched from the published project artifact. Some relative links may be broken.

    Active Clojure

    A library with various basic utilities for programming with Clojure.

    Usage

    Records

    The active.clojure.record namespace implements a define-record-type form similar to Scheme’s SRFI 9.

    Records (Spec)

    The active.clojure.record namespace implements a define-record-type form similar to Scheme’s SRFI 9 (similar to active.clojure.record).

    Additionally, this form creates Clojure Specs according to provided metadata.

    Example:

    (ns your.namespace
      (:require [active.clojure.record-spec :as rs]
                [clojure.spec.alpha :as s]
                [clojure.spec.test.alpha :as stest]
                [clojure.spec.gen.alpha :as gen]))
    
    (s/def ::color #{:hearts :diamonds :spades :clover})
    (s/def ::number #{:ace :two :three :four :five :six :seven :eight :nine :ten :jack :queen :king})
    
    (rs/define-record-type card
      (make-card number color) card?
      [^{:spec ::number} number card-number
       (^{:doc "Field with spec, lens and doc." :spec ::color}
       color card-color card-color-lens)])
    

    This defines the following Specs (aside from what the regular active.cloujre.records already define):

    • ::card a Spec which conforms values that are instances of a card (see example below).
    • Specs for accessors.
    • Spec for the constructor function.
    (s/explain ::card (make-card :four :spades))
    ;; => Success!
    (s/explain ::card {:card-number :four :card-color :spades})
    ;; => val: {:card-number :four, :card-color :spades} fails spec:
    ;;    :your.namespace/card predicate: card?
    

    If you don’t specify a spec, it defaults to any?. Further, this enables generating data based on record definitions:

    (gen/sample (s/gen ::card) 3)
    ;; => (#your.namespace.card{:card-number :four, :card-color :hearts}
    ;;     #your.namespace.card{:card-number :six, :card-color :hearts}
    ;;     #your.namespace.card{:card-number :queen, :card-color :diamonds}
    

    If instrumentation is enabled (via clojure.spec.test.alpha/instrument), the constructor is checked using the specs provided for the selector functions:

    ;; Does not get checked without instrument.
    (make-card :ace :heartz)
    ;; => #your.namespace.card{:card-number :ace :card-color :heartz}
    
    ;; Now, with instrumentation.
    (stest/instrument)
    
    (make-card :ace :heartz)
    ;; =>
    ;; 1. Unhandled clojure.lang.ExceptionInfo
    ;; Spec assertion failed.
    ;; ...
    ;; Problems: 
    
    ;; val: :heartz
    ;; in: [1]
    ;; failed: #{:spades :diamonds :hearts :clover}
    ;; spec: :your.namespace/color
    ;; at: [:args :color]
    

    NOTE: You must keep track of your namespaced keywords manually (e.g. the keywords you use for defining specs). We do not check for collisions, so former definitions with the same name will be overwritten!

    Conditions

    The active.clojure.condition namespace implements conditions, specifically crafted exception objects that form a protocol for communicating the cause of an exception, similar to the condition system in R6RS Scheme.

    Lenses

    The active.clojure.lens namespace implements lenses. Lenses provide a subtle way to access and update the elements of a structure and are well-known in functional programming languages.

    Configuration

    The active.clojure.config namespace implements application configuration via a big map.

    Debugging

    The active.clojure.debug namespace implements some useful debugging tools such as a macro pret that prints and returns its argument.

    Pattern Matching

    The active.clojure.match namespaces provides some syntactic sugar for map matching around core.match.

    License

    Copyright © 2014 Active Group GmbH

    Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.