This is necessary to ensure we distinguish between the symbol "Type" as
returned by `type` from the type/module "Type" potentially defined by a
user:
```
(deftype Type)
(type Type)
=> Module
(type (type 1))
=> Type
;; Even though the symbol conflicts with the module defined above,
;; subsequent calls to type return the correct result.
(type (type (type 1)))
=> ()
```
Extends Carp's support for type reflection by returning types for
values as well as bindings.
`type` now also returns a valid Carp expression/s-expression and so its
output can be used as input to dynamic functions and macros (prior to
this commit, `type` printed the type to the REPL but did not return a
meaningful expression in Carp).
Here are a few illustrations of the behavior:
```
(def x 1)
;; type now returns an s-expression/symbol
(type x)
=> Int
;; It also works on values
(type 1)
=> Int
(type 2b)
=> Byte
(type "foo")
=> (Ref String <StaticLifetime>)
;; It works on more complex values as well
(type Maybe)
=> Module
(type Maybe.Just)
(Fn [a] (Maybe a) <StaticLifetime>)
;; reports honestly about polymorphism
(type (Maybe.Nothing))
=> (Maybe a)
(type (Pair.init 1 2))
=> (Pair Int Int)
;; What about the type of types?
(type (type 2))
=> Type
;; Or the type of types of types?
(type (type (type 2)))
=> ()
;; One more time!
(type (type (type (type 2))))
=> ()
;; so, () is the fixpoint of type, and is reached after two applications
(type zero)
;; the type of an interface is all of its implementations
=> (((Fn [] (Array a) <StaticLifetime>) (Fn [] Bool <StaticLifetime>) (Fn
[] Byte <StaticLifetime>) (Fn [] Char <StaticLifetime>) (Fn [] Double
<StaticLifetime>) (Fn [] Float <StaticLifetime>) (Fn [] Int
<StaticLifetime>) (Fn [] Int16 <StaticLifetime>) (Fn [] Int32
<StaticLifetime>) (Fn [] Int64 <StaticLifetime>) (Fn [] Int8
<StaticLifetime>) (Fn [] Long <StaticLifetime>) (Fn [] (Maybe a)
<StaticLifetime>) (Fn [] (Pair a b) <StaticLifetime>) (Fn [] (Quadruple
a b c d) <StaticLifetime>) (Fn [] String <StaticLifetime>) (Fn []
(Triple a b c) <StaticLifetime>) (Fn [] Uint16 <StaticLifetime>) (Fn []
Uint32 <StaticLifetime>) (Fn [] Uint64 <StaticLifetime>) (Fn [] Uint8
<StaticLifetime>)))
```
As shown in the example above, this change also includes a cosmetic
update to the representation of lifetime variables, which are surrounded
in <> to distinguish them from type variables.
This commit also adds a new `kind` primitive that reports on the kind of
a binding or value:
```
(def x 3)
(kind x)
=> Base
(kind 2)
=> Base
(kind Maybe.Just)
=> Higher
(kind (Maybe.Just 2))
=> Higher
```
`kind` and `type` both support interactive development in the repl, for
example, a user can rely on `kind` to check the kind of a type they plan
on using in an interface that demands a higher-kinded argument.
Likewise, they both also support developing macros based on type
information.
getPath returns the path of a form. The DefDynamic case was missing from
the function's definition, resulting in failures when calling functions
such as the meta set primitive on dynamic defs. This change fixes such
issues.
Carp preserves tabulation and other whitespace in strings, as it should.
This sometimes results in awkward code indentation when it comes to long
doc strings that exceed 80 characters. Often, one has to continue the
string on a newline, but needs to avoid adding tabs to prevent Carp from
rendering them in the output.
This change alters the behavior of doc to take a series of strings as a
rest parameter instead, allowing for neater organization in the source,
for example, after this change the following long doc string for
compose:
~~~
"Returns the composition of two functions `f` and `g` for functions of any
arity; concretely, returns a function accepting the correct number of
arguments for `g`, applies `g` to those arguments, then applies `f` to the
result.
If you only need to compose functions that take a single argument (unary arity)
see `comp`. Comp also generates the form that corresponds to the composition,
compose contrarily evaluates 'eagerly' and returns a computed symbol.
For exmaple:
```
;; a silly composition
((compose empty take) 3 [1 2 3 4 5])
;; => []
(String.join (collect-into ((compose reverse map) Symbol.str '(p r a c)) array))
;; => 'carp'
;; comp for comparison
((comp (curry + 1) (curry + 2)) 4)
;; => (+ 1 (+ 2 4))
```"
~~~
becomes:
~~~
"Returns the composition of two functions `f` and `g` for functions of any"
"arity; concretely, returns a function accepting the correct number of"
"arguments for `g`, applies `g` to those arguments, then applies `f` to the"
"result."
""
"If you only need to compose functions that take a single argument (unary arity)"
"see `comp`. Comp also generates the form that corresponds to the composition,"
"compose contrarily evaluates 'eagerly' and returns a computed symbol."
"```"
";; a silly composition"
"((compose empty take) 3 [1 2 3 4 5])"
";; => []"
""
"(String.join (collect-into ((compose reverse map) Symbol.str '(p r a c)) array))"
";; => 'carp'"
""
";; comp for comparison"
"((comp (curry + 1) (curry + 2)) 4)"
";; => (+ 1 (+ 2 4))"
"```")
~~~
And the output remains the same; this just enables better alignment in
the source file.
The strings passed to doc are newline separated by default, but one can
circumvent this behavior by passing a bool along with the string as
follows:
~~~
(doc foo
("My amazing doc " false)
"continues on one line."
""
"And then another.")
~~~
The above doc string will result in the following output:
~~~
My amazing doc continues on one line.
And then another.
~~~
Of course, the original behavior of doc also remains valid, so if one
prefers to use the old indentation-mixed single string format, one still
can!
This change also reformats the doc strings in macro to utilize the new
rest parameter and make the source a bit neater.
Interfaces are now explicitly implemented using the `implements` key
word (in the past, implementation of an interface was implicit based on
matching names and function signatures).
This commit updates the language guide to account for this change and
includes an illustrative example to provide guidance on using
interfaces.
The `last` command relies on Haskell's `Prelude.last`--which will crash
on an empty list input. We report an error for incorrect input to last,
but we didn't handle the empty list case. This small change to our
pattern match ensures errors in carp code produce Carp's last command
error rather than causing `Prelude.last` to throw an error on empty list
input.
Indexing from zero is consistent with the rest of Carp's indexing
behavior, so this should make the function more predictable. I've also
added a note to the docs about this.
with-copy better communicates that this macro will produce a function
that performs a copy--it doesn't cover the fact that it creates a
references to an anonymous function...but there's only so much we can
cover in a name.
I've also updated the documentation.
Like the previous two commits, this commit extends support for
reflection to yet another type, externally registered functions,
allowing us to support calls such as `(arity Int.+)`.
Just as the prior commit added support for capturing the arity of
registered commands, this one captures the arity of registered
primitives, enabling one to make calls such as `(arity defmacro)`, etc.
I have also moved the dummy argument name function into Util.hs since
it's used in both Commands.hs and Primitives.hs.
Previously, the command xobjs did not capture the arity of their
definitions. After this commit, they do, which enables us to surface
useful information about commands in reflective modules such as
core/Introspection.
Calls such as `(arity Dynamic.+)` and `(arity Dynamic.load)` will work
after this change.
It's a fairly common pattern in Carp to call a higher-order function on
some structure of values, such as an Array. However, these structures,
and their members, all have lifetimes under Carp's memory management
model, which means they expect functions that are mapped over them to
take *a reference to a value* rather than a pure value. Array.reduce is
one example of such a "referential" higher-order, the type of its
function argument is:
```
(Fn [a, (Ref b c)] a)
```
That is, this function takes some pure initial value, then expects to be
called against the members of an array, which are *references* to the
values that are alive throughout the Array's lifetime.
However, one often wants to use a function that operates on pure values
in such contexts, such as +, which forces the programmer to write
anonymous functions that handle copying referenced values to pass them
to the underlying "pure" function:
```
(Array.reduce &(fn [x y] (+ x @y)) 0 &[1 2 3])
```
So, in using some high-order function over some structure in Carp one
usually has to do two things:
1. Wrap the function in a ref
2. Handle copying references into values in order to pass them into some
simpler function that can also be used outside of memory-bound
contexts.
The `proxy` macro captures this pattern. It wraps a given function in a
referenced anonymous function and copies an argument of that function at
a designated position before calling the underlying function. For
example, with `proxy`, the above example becomes:
```
(Array.reduce (proxy + 2) 0 &[1 2 3])
```
The macro effectively gives a name to a common pattern--typically it
will only save the programmer a few characters, but it perhaps makes the
act of using a "function that doesn't care about references" in a
reference dominant context more apparent.
One can also use the macro to develop more specialized macros for
certain higher-orders, since these usually dictate where copying must be
performed. For instance, the `Array.reduce` function argument always
expects the referenced value to occur in the second position, thus one
could write:
```
(defmacro reducer [function] (eval (list proxy function 2)))
```
Then the above code becomes even simpler:
```
(Array.reducer (reducer +) 0 &[1 2 3])
```
Which roughly means, "use the + function (which has no concept of
references) in this reference dependent context".
N.B. The examples using `+` won't work as of now due to current bugs
related to calling `arity` directly on an interface--but a synonym for
plus `add` defined as an explicit function will make all the above work
as expected.
gensym-local is similar to gensym-with, with it's arguments reversed.
That is, rather than allowing the user to specify a custom qualifier, it
allows the user to specify a custom counter (or any symbol) and appends
this to the default gensym `gensym-generated` symbol.
This enables one to, e.g. map over an array and generate symbols:
```
(map gensym-local (map Symbol.from [1 2 3]))
=> (gensym-generated1 gensym-generated2 gensym-generated3)
```
Theoretically, passing `gensym` as-is to `map` would accomplish this
using the global gensym-counter, but the counter is not incremented on
subsequent calls. This function gives users more flexibility as well.
