desiderata

KO | EN

gitlite — search

#python #react #typescript #go #android #machine-learning #linux #nodejs #awesome #cli #kubernetes #vue #security #mcp

(★ 19)

Things wanted or needed but missing from clojure.core

desiderata 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# desiderata

[![Lint and test](https://github.com/thoughtfull-clojure/desiderata/actions/workflows/lint-and-test.yml/badge.svg)](https://github.com/thoughtfull-clojure/desiderata/actions/workflows/lint-and-test.yml) [![clojars badge](https://badgen.net/badge/clojars/2.3.0/blue)](https://clojars.org/systems.thoughtfull/desiderata/versions/2.3.0) [![cljdoc badge](https://badgen.net/badge/cljdoc/2.3.0/blue)](https://cljdoc.org/d/systems.thoughtfull/desiderata/2.3.0/doc/readme)

Things wanted or needed but missing from clojure.core.

This is not just a collection of utility functions, but more significant features (and maybe some
utility functions).  Maybe it's best to just poke around in the documentation?  Otherwise, I've
attempted to provide details below.

## Baseline versions

- JVM: 21
- Clojure: 1.12.0

## defrecord

You can use `systems.thoughtfull.desiderata/defrecord` as a drop-in replacement for
`clojure.core/defrecord` and what you get are five new features.  The first (minor) feature is the
factory function (i.e. `map->...`) takes keyword arguments.

### Metadata propagation

Metadata attached to the name symbol of `systems.thoughtfull.desiderata/defrecord` will get
propagated to the factory functions.  So, for example, if you deprecate the `defrecord`, then its
factory functions will also be deprecated.

### Docstring

`systems.thoughtfull.desiderata/defrecord` takes a docstring that it appends to the end of both the
factory and positional factory functions.

```clojure
user> (require '[systems.thoughtfull.desiderata :as desiderata])
nil

user> (desiderata/defrecord Widget
"A widget for frobbing gizmos.

width and height are in metric."
[width height])
user.Widget

user> (doc map->Widget)
-------------------------
user/map->Widget
([& {:keys [width height]}])
  Factory function for class user.Widget, taking a map of keywords to field values.

A widget for frobbing gizmos.
  
  width and height are in metric.
nil

user> (doc ->Widget)
-------------------------
user/->Widget
([width height])
  Positional factory function for class user.Widget.

A widget for frobbing gizmos.
  
  width and height are in metric.
nil
```

### Defaults

You can specify a map of default values for fields (and non-fields) with the
`systems.thoughtfull.desiderata/defaults` option.  Values given to the factory or positional factory
functions will override defaults.

```clojure
user> (desiderata/defrecord Gizmo
[name]
::desiderata/defaults
{:name "Gizmo"
 :color :blue})
user.Gizmo

user> (->Gizmo "the Great")
{:name "the Great", :color :blue}

user> (map->Gizmo :texture :bumpy)
{:name "Gizmo", :color :blue, :texture :bumpy}
```

### Initializer

A method with the same name as the defrecord is an initializer method called from both the factory
and positional factory functions.  The initializer runs after the defaults and arguments have merged
and the factory function has executed.

As a sanity check, the initializer must return an instance of the defrecord, otherwise an
*IllegalStateException* is thrown.

```clojure
user> (desiderata/defrecord Company
[debt equity]
(Company
  [this]
  (assoc this :gearing-ratio (/ debt equity))))
user.Company

user> (->Company 100 1000)
{:debt 100, :equity 1000, :gearing-ratio 1/10}
```

## Thread.UncaughtExceptionHandler

There are two convenience functions for working with *Thread.UncaughtExceptionHandler*.
`uncaught-exception-handler` will adapt a two argument function to a
*Thread.UncaughtExceptionHandler*.

`set-default-uncaught-exception-handler-fn!` will set the default *Thread.UncaughtExceptionHandler*
after adapting the given two argument function to a *Thread.UncaughtExceptionHandler*.  The default
handler is used if there is no handler defined for a *Thread* and its *ThreadGroup* (see
*[Thread/setDefaultUncaughtExceptionHandler](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Thread.html#setDefaultUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler))*).

## thread-factory

`thread-factory` creates a *java.util.concurrent.ThreadFactory* for use particularly with executors.
It passes options to *Thread*s as it creates them, however, a notable feature is it takes an
`uncaught-exception-handler-fn` that it will set as a *Thread.UncaughtExceptionHandler* on each
thread it creates.  It adapts the `uncaught-exception-handler-fn` into a
*Thread.UncaughtExceptionHandler* using `uncaught-exception-handler`, and conveys to the
`uncaught-exception-handler-fn` the bindings established at the time the thread factory is created.

Another notable and Clojure-specific feature is the *ThreadFactory* can convey to created threads
the bindings established when the thread factory was created.  You can enable this by passing
`:convey-bindings?` true, but by default it is disabled.

It will also take a `name` which is used as a prefix to the names of threads it creates.

## attempt

`attempt` is a configurable retry loop that calls a function repeatedly until it succeeds or the
number of attempts is exhausted.  It is given three things the no-arg function, a retry predicate, and a delay-fn.

Each time the function is called the retry predicate is used to check if a retry is necessary.  The retry predicate receives two arguments.  The first argument is the result of the function (if any) and the second is the exception thrown by the function (if any).  These arguments are exclusive.  Only one or the other will be non-nil and not both.

If the retry predicate returns a truthy value, then the delay-fn is called with the index of the attempt (zero being the initial attempt, 1 the first retry, etc.).  If the delay-fn returns nil, then the attempts cease and either the result is returned or the exception is thrown.  Otherwise the delay-fn should return a *java.time.Duration* indicating how long to wait before the next attempt.

The delay-fn can be any arbitrary function, but there are some implementations for common situation and some other functions that can mix in behavior.  `exponential-backoff` will return delays that increase exponentially from an initial duration.  `linear-backoff` will return delays that increase from an initial duration in increments of an incremental duration.  `fixed-delay` will always return a fixed delay.

Additionally, `max-attempts` and `max-duration` can be composed with another delay-fn to enforce a maximum number of attempts and a maximum duration delay (respectively).

Optionally, `attempt` takes a `sleep-fn` which is called with the *Duration* returned by `delay-fn`
and disables the thread for at most that duration.  It defaults to `java.lang.Thread/sleep`.
`sleep-unless` returns a `sleep-fn` that returns early if a condition is met.

## clj-kondo

To import custom clj-kondo hooks for `systems.thoughtfull.desiderata/defrecord` use

```
clj-kondo --lint "$(clojure -Spath)" --copy-configs --skip-lint
```

## License

> Copyright © technosophist
>
> This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of
> the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
>
> This Source Code Form is "Incompatible With Secondary Licenses", as defined by the Mozilla Public
> License, v. 2.0.

desiderata

desiderata 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

desiderata

desiderata 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README