Setup
API
Changelog
Introduction
Usage
Examples
Glossary
Contact

thingy

A Clojure library that provides a bizarre function definition mechanism

Setup

Leiningen/Boot

[com.sagevisuals/thingy "1"]

Clojure CLI/deps.edn

com.sagevisuals/thingy {:mvn/version "1"}

Require

(require '[thingy.core :refer [assign-thingy-fn! make-thingy]])

Introduction

This Clojure library provides tools to create function-like objects which implement the vector interface. It is intended for a very specific, niche use case and it is exceedingly unlikely to be useful or safe outside of that niche.

A thingy instance, when appearing at the head of an S-expression serves as a function, consuming the arguments contained in the tail and yielding a value. Unlike a typical function, the internal structure of a thingy is manipulatable with all the functions that make up the vector interface. Such objects may be used in academic programming languages that explore using sequential collections of values to define functions.

Sure, it's possible to write

(application-function vector arg1 arg2...)

where application-function provides some kind of logic about how to interpret vector. But having the symbol "application-function" scattered around is visually distracting. Instead of plainly representing the concepts, the machinery is leaking onto the page.

It is much nicer to write

(fn-vec arg1 arg2...)

as well to read and to understand: fn-vec is the operator. The thingy library enables such streamlining.

Usage

Basics

Let's pretend we want to create a trio of single-arity functions.

• Alice returns the string Hello, World! regardless of the argument.
• Bob increments its argument.
• Charlie reverses the sequence passed as an argument.

Since we're pretending, we want to define Alice, Bob, and Charlie each as a sequential collection, such as a Clojure vector. For the sake of discussion, we'll state the following "function" definitions, using vector literals.

(def Alice [:a])
(def Bob [:b])
(def Charlie [:c])

Let's write a function, application, which dispatches on argument f's first element.

(defn application
  [f x]
  (condp = (first f)
    :a "Hello, World!"
    :b (inc x)
    :c (reverse x)))

For this demonstration, that condp serves as a kind of crude lookup table, but application could be anything, such as a higher-order function, or a recursive function, etc.

Now we test out what we've done.

(application Alice :an-ignored-arg) ;; => "Hello, World!"

(application Bob 99) ;; => 100

(application Charlie [:chocolate :strawberry :vanilla])
;; => (:vanilla :strawberry :chocolate)

That looks promising. Alice returns string Hello, World! regardless of the argument, Bob increments the numeric argument, and Charlie indeed reverses the sequence passed as the next argument.

There's something we'd like to improve: We wanted to think of Alice, Bob, and Charlie as functions, so having the symbol "application" sprinkled throughout kinda destroys that illusion.

Perhaps we could leverage the fact that regular Clojure vectors have the capability to act as functions when at the head of an S-expression.

([97 98 99] 1) ;; => 98

We see that when a vector is at the head of the S-expression, there's an implied nth. It's as if we had written this.

(nth [97 98 99] 1) ;; => 98

For our Alice/Bob/Charlie trio, we'd like for there to be instead an implied application.

To do that, let's introduce a new utility, make-thingy, which creates a vector-like object.

(make-thingy 97 98 99) ;; => [97 98 99]

Does it do vector tasks?

(count (make-thingy 97 98 99)) ;; => 3
(nth (make-thingy 97 98 99) 1) ;; => 98
(conj (make-thingy 97 98 99) 100) ;; => [97 98 99 100]

That certainly looks like a vector. Each instance of a thingy implements the vector interface, so we have all the familiar functions like count, conj, etc.

Now, let's re-define the our trio using make-thingy.

(def Alice (make-thingy :a))
(def Bob (make-thingy :b))
(def Charlie (make-thingy :c))

Let's see what happens when we try to use a thingy as a function.

(Alice 0) ;; => :a

Hmm. It appears to behave like a regular vector, with an implicit nth. This is, in fact, the default.

Next, we'll re-set the invocation behavior of all instances of thingys to application using another utility, assign-thingy-fn!.

(assign-thingy-fn! application)
;; => {:fn application,
;;     :left-delimiter "[",
;;     :right-delimiter "]"}

assign-thingy-fn! mutates the invocation behavior for all thingy instances.

Let's see how our trio behaves.

(Alice :an-ignored-arg) ;; => "Hello, World!"

(Bob 99) ;; => 100

(Charlie [:chocolate :strawberry :vanilla])
;; => (:vanilla :strawberry :chocolate)

Now our Alice, Bob, and Charlie thingys behave like functions.

Details

There are three steps to using the thingy library: creating an instance, defining an invocation function, and assigning that invocation function.

1. Creating and manipulating a thingy instance is analogous to that of vectors. To create, use make-thingy

   (make-thingy 97 98 99) ;; => [97 98 99]

   similar to using clojure.core/vector. (There is no analogous facility to making a vector literal.) Create a new instance from some other existing collection like this.

   (into (make-thingy) #{:foo :bar :baz}) ;; => [:baz :bar :foo]

   Note that the type is distinct from a standard Clojure persistent vector.

   (type (into (make-thingy) #{:foo :bar :baz}))
   ;; => com.sagevisuals.AltFnInvocablePersistentVector

   Manipulate an instance with your favorite tools.

   (update (make-thingy 97 98 99) 2 inc) ;; => [97 98 100]
   
   (map inc (make-thingy 97 98 99)) ;; => (98 99 100)

   Note that, just like Clojure vectors, sequence functions consuming a thingy instance will return a sequence.

   (type (map inc (make-thingy 97 98 99))) ;; => clojure.lang.LazySeq

2. Defining a thingy invocation function is merely typical Clojure function definition, e.g., using defn.

   (defn yippee
      [_ _]
      "Hooray!")

   This example defines a 2-arity function that returns a string, ignoring its arguments. Observe.

   (yippee (make-thingy 1.23 4.56) 22/7) ;; => "Hooray!"

   The invocation function must have an arity of zero to nine. When there is at least one argument, the thingy instance is passed as the first argument, followed by up to eight trailing arguments.

3. Assigning a thingy invocation functions uses assign-thingy-fn!.

   (assign-thingy-fn! yippee)

   Evaluating assign-thingy-fn! synchronously mutates the invocation function for all thingy instances.

   Now, any thingy instance, when at the head of an S-expression, will implicitly invoke yippee.

   (def X (make-thingy 1 2 3))
   
   (X :an-ignored-arg) ;; => "Hooray!"

Examples

Eso-lang: A fictitious, esoteric language.

Glossary

thingy instance

An instance of com.sagevisuals.AltFnInvocableVector. In nearly every regard, identical to an instance of clojure.lang.PersistentVector. Whereas a Clojure vector at the head of an S-expression behaves as if there is an implicit nth, a thingy instance invokes a dynamically-mutable invocation function. (Defaults to nth.)

Instantiated with make-thingy.

invocation function

The function that is invoked when evaluating an S-expression with a thingy instance at the head. In all respects, a standard Clojure function, that may be called from any site.

Defined with regular Clojure machinery, i.e., defn.

License

This program and the accompanying materials are made available under the terms of the MIT License.

Copyright © 2024–2025 Brad Losavio.
Compiled by ReadMoi on 2025 March 14.
0b7db4a2-ac01-40eb-bb9b-0646700b987e