* feat: add 'when' functions for Maybe and Result
These functions enable users to execute some side-effecting function
(one that returns unit and take no arguments) based on the contents of a
Maybe or Result.
`when-success`: Executes a side-effect when given a `Result.Success`
`when-error`: Executes a side-effect when given a `Result.Error`
`when-just`: Executes a side-effect when given a `Maybe.Just`
`when-nothing`: Executes a side-effect when given a `Maybe.Nothing`
* docs: add Control to core lib doc generation
* feat: Add support for emitting literal C
This commit adds a new Obj type, C, as well as a command for emitting C
literals (which are represented by this object).
This is necessary for circumstances in which Carp's handling of
templates and emission orders prevents interop with C. For example, the
c11 macro static_assert must only take a string literal in its second
position. However, Carp's memory management will typically assign a
string literal (in Carp) to an anonymous variable, which makes them
impossible to use with static_assert. The new emit-c command will
support this use case:
```
(static-assert 0 (Unsafe.emit-c "\"message!\""))
```
The literal string "message!" will be emitted in the compiler's C output
in the position corresponding to the macro call.
We also add a special type for c literals, CTy, to prevent conflating
them with Strings. This helps maintainers define clear boundaries and
express what interop code requires the use of literal C.
Likewise, we need to emit `c_code` to represent this type in C. This
wouldn't be necessary except that Carp sometimes auto-generates
functions that refer to Carp types in their C equivalents, so we need
this for completeness. It is typed as the void pointer.
N.B. That the command is not yet exposed in Carp in this commit.
Thanks to @TimDeve for recommending the name emit-c!
* feat: Add preproc command and add emit-c to Unsafe module
This commit adds the preproc command, which enables users to emit
arbitrary C in the compilers emitted C output.
The C emitted by calls to preproc will be appended to the output after
include directives but prior to any other emissions. One can use it to
call preprocessor directives in C, define helper functions etc.
preproc takes a C type value as an argument and must be used in
conjunction with emit-c. Both functions are added to the Unsafe module
to signal their dangerousness.
One can use `register` in combination with preproc to define code
entirely in Carp and obviate the need of additional header files. For
example:
```
(Unsafe.preproc (Unsafe.emit-c "#define FOO 0"))
(Unsafe.preproc (Unsafe.emit-c "void foo() { printf(\"%d\\n\", 1); }"))
(register FOO Int)
(register foo (Fn [] ()))
(defn main []
(do (foo)
(IO.println &(fmt "%d" FOO))))
```
The prior example emits C that defines a FOO macro and foo function,
which are both referenced in the main function emitted by Carps normal
processing. Here's what the output looks like:
```
// .. several other includes emitted by the compiler...
void foo() { printf("%d\n", 1); }
//Types:
// Depth 3
typedef struct {
union {
struct {
Long member0;
} Just;
// Nothing
char __dummy;
} u;
char _tag;
} Maybe__Long;
```
The C passed to preproc calls is emitted prior to Carps other emissions,
ensuring the user has access to these definitions before any Carp code
is called.
* docs: Add documentation on emit-c and preproc
* feat: add macros for emitting C compiler directives
This suite of macros uses the `Unsafe.emit-c` and `Unsafe.preproc`
functions to provide macros for emitting common C compiler directives,
such as #ifdef, #define, #pragma and others.
* refactor: Groups Dynamic together in Macros.carp
* fix: Fixes doc for `hidden` referring to the wrong symbol
* feat: Adds defn- & def- macros
Adding these macros as a shortand for declaring a def or defn and making
them `hidden` and `private`, useful to keep things internal to a module.
* test: Adds expected error output tests for def- & defn-
* refactor: Changes position of Module and Interface section in LanguageGuide
Trying to introduce concepts in the same order they are referred to in
the examples: structs > modules > interfaces.
* docs: Adds private & hidden section in the LanguageGuide
* refactor: move Context updates into functions
Previously, we had a lot of instances of updating Context records
directly, replacing environments where needed. This commit replaces
those hand-written record setting instances with functions, which should
allow us to more gracefully abstract over any preprocessing we should
have to do and help ensure we're updating contexts in the right way.
* refactor: replace inline context manipulation in primitives
Like the commit that altered Eval before it, this commit leverages
Context functions to remove a bunch of inline record field setting code
and direct env manipulation.
* refactor: replace generic binder lookups with contextual ones
* refactor: move true and false XObjs into Obj.hs
Previously, trueXObj and falseXObj were defined in Commands.hs, but
since they're just literal constructed XObj values, I feel Obj.hs is a
more appropriate home for them and makes them more widely accessible to
other modules without needing to import Commands.
* refactor: model symbol qualification requirements at typelevel
This commit refactors the Qualify module to express symbol qualification
at type level. In the past, all functions operated on SymPaths. In some
cases, the functions operated on paths that *were not yet qualified* and
so the functions would perform qualification inline. Contrarily, other
functions like define received XObjs (from another part of the codebase
entirely!) that were already fully qualified, and so it would be a grave
mistake to re-qualify them.
In the general case, it's difficult or impossible to tell across modules
whether or not a given SymPath is coming in qualified or unqualified,
which can easily lead to mistakes of double-qualification, e.g.
transforming `Foo.bar` into `Foo.Foo.bar`.
Modelling qualification in the type system enables us to avoid the
problem by distinguishing between unqualified and qualified paths. A
function receiving an SymPath can safely qualify it, whereas a function
receiving a QualifiedPath should not further qualify the path. This
helps better express and ensure constraints across modules.
In addition, this commit also refactors a few functions where there was
opportunity to do so.
* refactor: remove eval call from `doc`
This can lead to problems where a doc call intended to be evaluated
later (in a macro body) is evaluated *immediately* resulting in a
binding being added to the wrong scope (see the function reverse in
core).
The reason this behavior crops up now is that a special case for
evaluating module contexts was removed last commit--this special case
caused problems of its own, and the real root of things stems from the
unnecessary eval call. Generally, evaling a doc call provides no benefit
other than making evaluation of the meta set immediate in the repl,
which is easy enough for one to do on one's own by calling eval where
needed.
* refactor: use do notation to clarify case qualification
* refactor: rename runQualified to unQualified
@eriksvedang pointed out the `run` prefix typically denotes a monad. As
`Qualified` is not monadic (no monad instance defined) we drop the `r`
to ensure we don't mislead readers.
* refactor: convert a few more binds to do notation
Do notation is generally clearer in cases where we use mapM, etc. We can
also leverage liftM frequently in the qualification functions to
transform a Qualified xobj back into an xobj for further use.
* refactor: temporarily restore special case in meta set
Meta set disallows setting the meta of a prefixed, absolute path such as
`Foo.bar`. It only allows relative, unqualified paths `bar` and uses the
current context to determine the appropriate module.
If we eventually throw and error from envInsertAt, we can remove this
special case. I intend to do that later, but for now we'll keep the
special case to make for a more pleasant user experience.
* feat: a proper dynamic numeric tower
The following things were changed and/or added:
- `Dynamic.neg` was added
- `Dynamic.mod` was changed to work on float values
- `Dynamic.cxr` was changed to work with `0` instructions
- `Dynamic.=` was changed to ignore the type of the number
- `Dynamic.round` was added
- dynamic arithmetic was changed to respect the numeric type tower
- the instances of `Eq` and `Ord` for `Number` are no longer derived, so that they work across numeric types
- the instance of `Num` for `Number` was changed to work across numeric types
- `promoteNumber` was added as a type function to implement the numeric tower.
The numeric tower is as follows:
Byte -> Int -> Long -> Float -> Double
* test: add tests for cxr, neg, and =
* test: add tests for Dynamic.round
* feat: quasiquotation
* test: add tests for quasiquotation
* fix: fix typo in call to doc
* fix: do not evaluate quasiquote too eagerly
* test: pull quasiquote test into macro
* docs: fix unquote example with better constant
* feat: add quasiquote literals
* refactor: simplify reader macros
* core: add derive
* fix: fix errors with set!
Notably, don't type check dynamic bindings (which can be set to
whatever) and eliminate a hang that resulted from not handling an error
at the end of the `set!` call. Also refactors some of the code in
efforts to make it a bit cleaner.
Also adds an error when `set!` can't find the variable one calls set!
on.
* feat: better derive
* test: add error test for derive
* document derive
* add derive to core documentation to generate
* core: add derive
* fix: fix errors with set!
Notably, don't type check dynamic bindings (which can be set to
whatever) and eliminate a hang that resulted from not handling an error
at the end of the `set!` call. Also refactors some of the code in
efforts to make it a bit cleaner.
Also adds an error when `set!` can't find the variable one calls set!
on.
* feat: better derive
* document derive
* feat: first completely working version of derive
* feat: make name of derivable customizable (thanks @scolsen)
* refactor: implement doc edits provided by @scolsen
* feat: change argument order for derive
* fix: change deriver error test
* test: add derive tests
* fix: change order of derive back
* docs: fix typo in derive document
Co-authored-by: scottolsen <scg.olsen@gmail.com>
* fix: don't set the inner env to globals in type mods
Previously, we set the inner environment of a type generated module to
the global env in cases where the overarching context didn't have an
inner env. This leads to problems where by the recognition of modules is
inconsistent, and one can't use the names of types as submodules in
certain circumstances.
This commit fixes that issue.
* refactor: refactor primitiveDefmodule
This refactor fixes a issues with meta information on submodules, for
instance, sigs on submodule functions used to result in a compiler error
about ambiguous identifiers. This fixes that.
Unfortunately, I don't have a precise idea about what exactly was wrong
with the original definition of this function. My suspicion is that the
recursion originally altered submodule paths in the wrong way, but I'm
not certain. In any case it's fixed.
* fix: ensure macros are expanded in the correct module
Previously, macro expansions folded over all forms after the top level
form, without performing any context updates on encountered
`defmodules`. This created an issue in which macro calls that produced
new bindings, "meta stubs", were *hoisted* out of submodules and into
the top-level module, creating duplicate definitions.
This commit fixes that issue by adding a special case for defmodule in
macroExpand.
* fix: ensure submodules and globals don't conflict
Previously, our module lookups during new module definition always
eventually fell back to the global environment, which caused submodules
that happen to share a name with a global module to be confused with the
global module. This change fixes that, so now one can define both
`Dynamic` (global) and `Foo.Dynamic` without issue.
* fix: remove old prefixes from vector tests
Commit 7b7cb5d1e replaced /= with a generic function. However, the
vector tests still called the specific Vector variants of this function,
which were removed when the generic was introduced. After recent
changes, these calls are now (correctly) identified as erroneous. My
guess is that they only worked in the past because of problems with our
lookups.
* chore: format code
* feat!: support defining types in modules
This commit adds support for defining types (using deftype) in modules.
Previously, all types were hoisted to the top level of the type
environment. After this commit, the type environment supports defining
nested modules just like the value env, so, calling the following:
```
(defmodule Foo (deftype Bar Baz))
```
Adds the following to the type env:
```
Foo : Module = {
Bar : Type
}
```
and the following to the value env:
```
Foo : Module = {
Bar : Module = {
Baz : (Fn [] Foo.Bar)
copy : (Fn [(Ref Foo.Bar q)] Foo.Bar)
delete : (Fn [Foo.Bar] ())
get-tag : (Fn [(Ref Foo.Bar q)] Int)
prn : (Fn [(Ref Foo.Bar q)] String)
str : (Fn [(Ref Foo.Bar q)] String)
}
}
```
Such a type is *distinct* from any type defined at the top level that
happens to also have the name `Bar`.
This commit also updates info and tests to account for types in modules.
BREAKING CHANGE: This change is breaking since it alters the names of
types that were previously defined in modules. A good example of this is
the `Id` type in the `Color` module. Previously, one could refer to this
type by simply typing `Id` since it was hoisted to the top level. Now it
*must* be referred to by `Color.Id` since `Id` at the top level of the
type env and `Color.Id` (Id in the color module) are considered to be
distinct types.
* chore: format code
* refactor: use concat instead of intercalate
* chore: remove excess parentheses
* chore: Add todo to return IO () in printIfFound
* feat: 'delete' interface (deciding whether a type is managed or not)
* refactor: Move implements function to Interface module
* feat: Automatically implement 'delete' for types defined with `deftype`
* fix: Don't implement `delete` for Pointer
* refactor: Clarify `memberInfo` function
* fix: Also check if function types are managed
* fix: Implement 'delete' for String and StaticArray.
* fix: Manage String and Pattern. Tests run!
* feat: Add `managed?` primitive
* docs: Note about primitiveIsManaged
* test: Basic test cases for managed / nonmanaged external types
* test: Make sure `managed?` primitive works
* test: Inactivate sanitizer since we're creating leaks intentionally
* feat: Removed 'isExternalType' function
* refactor: Decide if struct member takes ref or not when printing
..based on blitable interface, and 'prn' implemntation
* refactor: Use 'blit' everywhere
* refactor: Implement `strTakesRefOrNot` in terms of `memberStrCallingConvention`
* refactor: Use `remove` over `filter not`
* fix: Make `str` work for (Pointer a) types
* test: Make sure that the Pointer.str compiles
* fix: Remove test case, keep function around to make sure it compiles
* docs: Generates HTML docs for Function core module
* docs: Adds lifetime information in Function module
* docs: Adds callback section to C Interop
* docs: Corrects typos in Function docs
* Pointer: Add utility functions
This commit adds a few more utility functions to `Pointer.carp`.
- Pointer.set-unsafe: Sets the value of a pointer to some arbitrary Carp
value, without type checking. Users need to ensure this operation is
safe.
- Pointer.set: Sets the value of a pointer to a value of type t to a
value that has the same type.
- Pointer.cast: Casts a pointer to a value of type t to a pointer to a
value of type `a`--the argument passed is ignored, it is only used to
determine the type to cast to.
- Pointer.leak: Copies a Carp reference to a new pointer to the same
value. This creates a leak since Carp will not automatically clean up
this memory.
- Pointer.free: Frees a pointer p. Users need to ensure calls to this
function are safe and do not produce errors like a double free.
Intended for use with leak.
Here's an example of some of these functions in action:
```
(defn foo []
(let-do [p (Pointer.leak "leaky")] ;; create a new pointer
(ignore (Pointer.set p @"foo")) ;; set the pointer to "foo"
(println* (Pointer.to-value p)) ;; convert to a Carp val to print
(Pointer.free p) ;; finally, free it.
0))
(foo)
=> Compiled to 'out/Untitled' (executable)
foo
0
```
And the C of interest:
```
int foo() {
int _35;
/* let */ {
static String _6 = "leaky";
String *_6_ref = &_6;
String* _7 = Pointer_leak__String(_6_ref);
String* p = _7;
/* let */ {
static String _15 = "foo";
String *_15_ref = &_15;
String _16 = String_copy(_15_ref);
String* _17 = Pointer_set__String(p, _16);
String* _ = _17;
/* () */
}
String _26 = Pointer_to_MINUS_value__String(p);
String _27 = StringCopy_str(_26);
String* _28 = &_27; // ref
IO_println(_28);
Pointer_free__String(p);
int _34 = 0;
_35 = _34;
String_delete(_27);
}
return _35;
}
```
As mentioned, and as w/ other Pointer functions users need to ensure the
safety of these operations themselves. For example, calling `free` on
`p` twice in the example above produces the expected double free:
```
(defn foo []
(let-do [p (Pointer.leak "leaky")] ;; create a new pointer
(ignore (Pointer.set p @"foo")) ;; set the pointer to "foo"
(println* (Pointer.to-value p)) ;; convert to a Carp val to print
(Pointer.free p) ;; finally, free it.
(Pointer.free p) ;; !Double free!
0))
(foo)
Compiled to 'out/Untitled' (executable)
foo
Untitled(38328,0x10d9a1dc0) malloc: *** error for object 0x7feb86c01790:
pointer being freed was not allocated
Untitled(38328,0x10d9a1dc0) malloc: *** set a breakpoint in
malloc_error_break to debug
[RUNTIME ERROR] '"out/Untitled"' exited with return value -6.
```
Still, these should come in handy in rare cases in which users need to
circumvent the type checker or borrow checker.
diff --git a/core/Pointer.carp b/core/Pointer.carp
index a662c636..4f29d587 100644
--- a/core/Pointer.carp
+++ b/core/Pointer.carp
@@ -20,6 +20,29 @@ The user will have to ensure themselves that this is a safe operation.")
(doc from-long "converts a long integer to a pointer.")
(deftemplate from-long (Fn [Long] (Ptr p)) "$p* $NAME(Long p)" " $DECL { return ($p*)p; }")
+ (doc set-unsafe
+ "Sets the value of a pointer."
+ "The user will have to ensure this operation is safe.")
+ (deftemplate set-unsafe (Fn [(Ptr p) (Ref a b)] (Ptr p)) "$p* $NAME($p* p, void* a)" "$DECL { *p = *($p*)a; return p;}")
+
+ (doc cast
+ "Cast a pointer to type p to a pointer to type a."
+ "The value of the `a` argument is ignored.")
+ (deftemplate cast (Fn [(Ptr p) a] (Ptr a)) "$a* $NAME($p* p, $a a)" "$DECL { *($a*)p = CARP_MALLOC(sizeof($a)); return ($a*)p;}")
+
+ (doc leak
+ "Allocate a new pointer that's a copy of the value of `Ref`"
+ "The Carp borrow checker won't delete this pointer. You will need to delete it manually by calling `Pointer.free`.")
+ (deftemplate leak (Fn [(Ref a b)] (Ptr a)) "$a* $NAME($a* r)" "$DECL { void *leak = CARP_MALLOC(sizeof($a)); memcpy(leak, r, sizeof($a)); return ($a*)leak;}")
+
+ (doc free
+ "Free a pointer."
+ "Users need to manually verify that this operation is safe.")
+ (deftemplate free (Fn [(Ptr p)] Unit) "void $NAME($p* p)" "$DECL {CARP_FREE(p);}")
+
+ (doc set "Sets the value of a pointer.")
+ (deftemplate set (Fn [(Ptr p) p] (Ptr p)) "$p* $NAME($p* p, $p a)" "$DECL { *p = a; return p;}")
+
(defn inc [a] (Pointer.add a 1l))
(implements inc Pointer.inc)
(defn dec [a] (Pointer.sub a 1l))
* Pointer: Change signature of leak to make it more sensible
Instead of `leak` copying a previously allocated value, it now takes
(unmanaged) ownership of a fresh value and allocates. This makes more
sense semantically, as we're just instantiating a new pointer that won't
be managed by Carp and will leak unless freed explicitly.
Thanks to @TimDeve for the suggestion!
* Pointer: Improve apis on set and alloc
- Rename set-unsafe to align w/ naming conventions
Most unsafe functions are prefixed with `unsafe`, not suffixed.
- Rename leak to `unsafe-alloc` to better convey its semantics (leak
also already exists as `Unsafe.leak`.
- Remove `cast` since its use is covered by `Unsafe.coerce`.
Thanks to TimDeve and hellerve for the suggestions!
* Pointer: Make unsafe-set take ownership
* Pointer: Correctly cast in unsafe-alloc; add unsafe-realloc
Here's a short illustration of why we need `realloc` even though we
already have `Pointer.add`:
```
(defn foo []
(let-do [p (Pointer.unsafe-alloc 2)]
(set! p (Pointer.add p (Pointer.width (Pointer.unsafe-alloc @"foo"))))
(ignore (Pointer.unsafe-set p @"foo"))
(println* (Pointer.to-value (the (Ptr String) (Unsafe.coerce p))))
(Pointer.free p)
0))
```
This function seems fine at first glance, but since `add` returns a new
pointer, `p` is reset to the new pointer, the reference to the original
is lost, and `free` is called on a value that was never actually
allocated since `add` does not malloc.
Using unsafe-realloc, we can avoid the additional allocation:
```
(defn foo []
(let-do [p (Pointer.unsafe-alloc 2)]
(Pointer.unsafe-realloc p @"foo")
(ignore (Pointer.unsafe-set p @"foo"))
(println* (Pointer.to-value (the (Ptr String) (Unsafe.coerce p))))
(Pointer.free p)
0))
```
The allocation is what we care about here. One still needs to use
`Unsafe.coerce` since as far as the Carp compiler is concerned, `p` is
still a (Ptr Int) even though the corresponding c has cast it silently
to a `String` in order to reallocate.
* Pointer: Change signature of unsafe-set to align with set!
* Pointer: Change signature of `set` to align with `set!`
* Pointer: Remove unsafe-realloc
* Pointer: Update docs for unsafe-alloc and free
* System: Remove System.free
Pointer.free serves a similar function, and is more restrictive, so
we'll remove System.free. One can use `delete` or cast to a pointer and
free that way.See PR #1012 for further discussion.
* refactor: Move code out of Macros.carp into other files
* fix: Move back some macros needed in --no-core mode
* refactor: Remove weird 'evaluate' macros
* fix: Put back more macros
* fix: Remove transitive loading of Macros.carp
* refactor: Remove ArrayMacros.carp and put 'for' at top of Array.carp instead
* refactor: More splitting up
* refactor: Move back save-docs
* fix: Moved back some stuff
Co-authored-by: Erik Svedang <erik@Eriks-iMac.local>
