From 4852f1caabcbcd5ad3dd5696bfe4bc428d653f94 Mon Sep 17 00:00:00 2001 From: JJ Date: Mon, 1 Jan 2024 22:01:42 -0800 Subject: docs: rename overview --- README.md | 2 +- docs/BASIC.md | 236 ------------------------------------------------------- docs/OVERVIEW.md | 236 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/SUMMARY.md | 44 +++++++++++ 4 files changed, 281 insertions(+), 237 deletions(-) delete mode 100644 docs/BASIC.md create mode 100644 docs/OVERVIEW.md create mode 100644 docs/SUMMARY.md diff --git a/README.md b/README.md index 5a5d5e9..3fc6286 100644 --- a/README.md +++ b/README.md @@ -113,7 +113,7 @@ These are best read in order. Note that all of these documents (and parts of this README) are written as if everything already exists. Nothing already exists! You can see the [roadmap](docs/ROADMAP.md) for an actual sense as to the state of the language. I simply found writing in the present tense to be an easier way to collect my thoughts. -This language does not currently integrate ideas from the following areas of active research: effects systems, refinement types (including ranges), and dependent types. +This language does not currently integrate ideas from the following areas of active research: effects systems, refinement types, and dependent types. It plans to integrate refinement types in the future as a basis for `range[]` types, and to explore safety and optimizations surrounding integer overflow. ## Primary References - [The Rust I wanted had no future](https://graydon2.dreamwidth.org/307291.html) diff --git a/docs/BASIC.md b/docs/BASIC.md deleted file mode 100644 index df4b22f..0000000 --- a/docs/BASIC.md +++ /dev/null @@ -1,236 +0,0 @@ -# An Overview of Puck - -Puck is an experimental, high-level, memory-safe, statically-typed, whitespace-sensitive, interface-oriented, imperative programming language with functional underpinnings. It attempts to explore designs in making functional programming paradigms comfortable to those familiar with imperative and object-oriented languages, as well as deal with some more technical problems along the way, such as integrated refinement types and cross-language interop. Primarily, however, this is the language I keep in my head. It reflects the way I think and reason about code. - -I do hope others enjoy it. - -```puck -let ident: int = 413 -# type annotations are optional -var phrase = "Hello, world!" -const compile_time = when linux: "linux" else: "windows" -``` - -Variables may be mutable (`var`), immutable (`let`), or compile-time evaluated and immutable (`const`). -Type annotations on variables and other bindings follow the name of the binding (with `: Type`), and are typically optional. -Variables are conventionally written in `snake_case`. Types are conventionally written in `PascalCase`. -The type system is comprehensive, and complex enough to warrant delaying full coverage of until the end. Some basic types are of note, however: -- `int`, `uint`: signed and unsigned integers - - `i8`/`i16`/`i32`/`i64`/`i128`: their fixed-size counterparts - - `u8`/`u16`/`u32`/`u64`/`u128`: their fixed-size counterparts -- `float`, `decimal`: floating-point numbers - - `f32`/`f64`/`f128`: their fixed-size counterparts - - `dec64`/`dec128`: their fixed-size counterparts -- `byte`: an alias to `u8`, representing one byte -- `chr`: an alias to `u32`, representing one Unicode character -- `bool`: defined as `union[false, true]` -- `array[T, S]`: primitive fixed-size (`S`) arrays -- `list[T]`: dynamic lists -- `str`: mutable strings. internally a `list[byte]`, externally a `list[chr]` -- `slice[T]`: borrowed "views" into the three types above - -Comments are declared with `#` and run until the end of the line. -Documentation comments are declared with `##` and may be parsed by language servers and other tooling. -Multi-line comments are declared with `#[ ]#` and may be nested. -Taking cues from the Lisp family of languages, any expression may be commented out with a preceding `#;`. - -```puck -func reverse(s: str): str = - let half_len = s.len div 2 - s.get(half_len, s.len)!.reverse() & s.get(half_len, s.len)!.reverse() - -pub func... - -# May fail! `yeet` denotes functions that can throw -pub yeet func pretty_print[T](value: T) = - # the ! converts optionals into throwing exceptions - print!(typeof(value)) - print!(value) -``` - -Functions are declared with the `func` keyword. They take an (optional) list of generic parameters (in brackets), an (optional) list of parameters (in parentheses), and **must** be annotated with a return type if they return a type. Every function parameter must be annotated with a type. Their type may optionally be prefixed with either `mut` or `static`: denoting a *mutable* type (types are copied into functions and thus immutable by default), or a *static* type (known to the compiler at compile time, and usable in `const` exprs). Generic parameters may each be optionally annotated with a type functioning as a _constraint_. - - - -Whitespace is significant but flexible: functions may be declared entirely on one line if so desired. A new level of indentation after certain tokens (`:`, `=`) denotes a new level of scope. There are some places where arbitrary indentation and line breaks are allowed - as a general rule of thumb, after operators, commas, and opening parentheses. The particular rules governing indentation may be found in the [syntax guide](SYNTAX.md#indentation-rules). - -```puck -``` - -Puck supports *uniform function call syntax*: and so any function may be called using the typical syntax for method calls, that is, the first parameter of any function may be appended with a `.` and moved to precede it, in the style of a typical method. (There are no methods in Puck. All functions are statically dispatched. This may change in the future.) - -This allows for a number of syntactic cleanups. Arbitrary functions with compatible types may be chained with no need for a special pipe operator. Object field access, module member access, and function calls are unified, reducing the need for getters and setters. Given a first type, IDEs using dot-autocomplete can fill in all the functions defined for that type. Programmers from object-oriented languages may find the lack of classes more bearable. UFCS is implemented in shockingly few languages, and so Puck joins the tiny club that previously consisted of just D and Nim. - -```puck -``` - -Boolean logic and integer operations are standard and as one would expect out of a typed language: `and`, `or`, `xor`, `not`, `shl`, `shr`, `+`, `-`, `*`, `/`, `<`, `>`, `<=`, `>=`, `div`, `mod`, `rem`. Notably: -- the words `and`/`or`/`not`/`shl`/`shr` are used instead of the symbolic `&&`/`||`/`!`/`<<`/`>>` -- integer division is expressed with the keyword `div` while floating point division uses `/` -- `%` is absent and replaced with distinct modulus and remainder operators -- boolean operators are bitwise and also apply to integers and floats -- more operators are available via the standard library - -The above operations are performed with *operators*, special functions that take a prefixed first argument and (often) a suffixed second argument. Custom operators may be implemented, but they must consist of only a combination of the symbols `=` `+` `-` `*` `/` `<` `>` `@` `$` `~` `&` `%` `|` `!` `?` `^` `\` for the purpose of keeping the grammar context-free. They are are declared identically to functions. - -Term (in)equality is expressed with the `==` and `!=` operators. Type equality is expressed with `is`. Subtyping relations may be queried with `of`, which has the additional property of introducing new bindings in the current scope (more on this in the [types document](TYPES.md)). - -```puck -let phrase: str = "I am a string! Wheeee! ✨" -for c in phrase: - stdout.write(c) # I am a string! Wheeee! ✨ -for b in phrase.bytes(): - stdout.write(b.chr) # Error: cannot convert between u8 and chr -print phrase.last() # ✨ -``` - -String concatenation uses a distinct `&` operator rather than overloading the `+` operator (as the complement `-` has no natural meaning for strings). Strings are unified, mutable, internally a byte array, externally a char array, and are stored as a pointer to heap data after their length and capacity (fat pointer). Chars are four bytes and represent a Unicode character in UTF-8 encoding. Slices of strings are stored as a length followed by a pointer to string data, and have non-trivial interactions with the memory management system. More details can be found in the [type system overview](TYPES.md). - -```puck -``` - -Basic conditional control flow uses standard `if`/`elif`/`else` statements. The `when` statement provides a compile-time `if`. It also takes `elif` and `else` branches and is syntactic sugar for an `if` statement within a `static` block (more on those later). - -All values in Puck must be handled, or explicitly discarded. This allows for conditional statements and many other control flow constructs to function as *expressions*, and evaluate to a value, when an unbound value is left at the end of each of their branches' scopes. This is particularly relevant for *functions*, where it is often idiomatic to omit an explicit `return` statement. There is no attempt made to differentiate without context, and so expressions and statements often look identical in syntax. - -```puck -``` - -Exhaustive structural pattern matching is available with the `match`/`of` statement, and is particularly useful for the `struct` and `union` types. `of` branches of a `match` statement take a *pattern*, of which the unbound identifiers within will be injected into the branch's scope. Multiple patterns may be used for one branch provided they all bind the same identifiers of the same type. Branches may be *guarded* with the `where` keyword, which takes a conditional, and will necessarily remove the branch from exhaustivity checks. - - - -The `of` statement also stands on its own as an operator for querying subtype equality. Used as a conditional in `if` statements or `while` loops, it retains the variable injection properties of its `match` counterpart. This allows it to be used as a compact alternative to `if let` statements in other languages. - -```puck -func may_fail: Result[T, ref Err] -``` - -Error handling is done via a fusion of imperative `try`/`catch` statements and functional `Option`/`Result` types, with much syntactic sugar. Functions may `raise` errors, but should return `Option[T]` or `Result[T, E]` types instead by convention. The compiler will note functions that `raise` errors, and force explicit qualification of them via `try`/`catch` statements. - -A bevy of helper functions and macros are available for `Option`/`Result` types, and are documented and available in the `std.options` and `std.results` modules (included in the prelude by default). Two in particular are of note: the `?` macro accesses the inner value of a `Result[T, E]` or propagates (returns in context) the `Error(e)`, and the `!` accesses the inner value of an `Option[T]` / `Result[T, E]` or raises an error on `None` / the specific `Error(e)`. Both operators take one parameter and so are postfix. (There is additionally another `?` postfix macro, taking in a type, as a shorthand for `Option[T]`) - -The utility of the `?` macro is readily apparent to anyone who has written code in Rust or Swift. The utility of the `!` function is perhaps less so obvious. These errors raised by `!`, however, are known to the compiler: and they may be comprehensively caught by a single or sequence of `catch` statements. This allows for users used to a `try`/`catch` error handling style to do so with ease, with only the need to add one additional character to a function call. - -More details may be found in [error handling overview](ERRORS.md). - -```puck -loop: - break -``` - -Three types of loops are available: `for` loops, `while` loops, and infinite loops (`loop` loops). For loops take a binding (which may be structural, see pattern matching) and an iterable object and will loop until the iterable object is spent. While loops take a condition that is executed upon the beginning of each iteration to determine whether to keep looping. Infinite loops are infinite are infinite are infinite are infinite are infinite are infinite and must be manually broken out of. - -There is no special concept of iterators: iterable objects are any object that implements the `Iter[T]` interface (more on those in [the type system document](TYPES.md)), that is, provides a `self.next()` function returning an `Option[T]`. As such, iterators are first-class constructs. For loops can be thought of as while loops that unwrap the result of the `next()` function and end iteration upon a `None` value. While loops, in turn, can be thought of as infinite loops with an explicit conditional break. - -The `break` keyword immediately breaks out of the current loop, and the `continue` keyword immediately jumps to the next iteration of the current loop. Loops may be used in conjunction with blocks for more fine-grained control flow manipulation. - -```puck -block: - statement - -let x = block: - let y = read_input() - transform_input(y) - -block foo: - for i in 0 ..= 100: - block bar: - if i == 10: break foo - print i -``` - -Blocks provide arbitrary scope manipulation. They may be labelled or unlabelled. The `break` keyword additionally functions inside of blocks and without any parameters will jump out of the current enclosing block (or loop). It may also take a block label as a parameter for fine-grained scope control. - -```puck -``` - -Code is segmented into modules. Modules may be made explicit with the `mod` keyword followed by a name, but there is also an implicit module structure in every codebase that follows the structure and naming of the local filesystem. For compatibility with filesystems, and for consistency, module names are exclusively lowercase (following the same rules as Windows). - -A module can be imported into another module by use of the `use` keyword, taking a path to a module or modules. Contrary to the majority of languages ex. Python, unqualified imports are *encouraged* - in fact, are idiomatic (and the default) - type-based disambiguation and official LSP support are intended to remove any ambiguity. - -Within a module, functions, types, constants, and other modules may be *exported* for use by other modules with the `pub` keyword. All such identifiers are private by default and only accessible module-locally without. Modules are first-class and may be bound, inspected, modified, and returned. As such, imported modules may be *re-exported* for use by other modules by binding them to a public constant, i.e. `use my_module; pub const my_module = my_module`. - -More details may be found in the [modules document](MODULES.md). - -```puck -``` - -Compile-time programming may be done via the previously-mentioned `const` keyword and `when` statements: or via `const` *blocks*. All code within a `const` block is evaluated at compile-time and all assignments and allocations made are propagated to the compiled binary as static data. - -Further compile-time programming may be done via metaprogramming: compile-time manipulation of the abstract syntax tree. The macro system is complex, and a description may be found in the [metaprogramming document](METAPROGRAMMING.md). - -```puck -func await(promise: Promise) -pub async func - -await -``` - -The async system is *colourblind*: the special `async` macro will turn any function *call* returning a `T` into an asynchronous call returning a `Future[T]`. The special `await` function will wait for any `Future[T]` and return a `T` (or an error). Async support is included in the standard library in `std.async` in order to allow for competing implementations. More details may be found in the [async document](ASYNC.md). - -Threading support is complex and also regulated to external libraries. OS-provided primitives will likely provide a `spawn` function, and there will be substantial restrictions for memory safety. I really haven't given much thought to this. - -```puck -``` - -Details on memory safety, references and pointers, and deep optimizations may be found in the [memory management overview](MEMORY_MANAGEMENT.md). -The memory model intertwines deeply with the type system. - -```puck -``` - -Finally, a few notes on the type system are in order. - -Types are declared with the `type` keyword and are transparent aliases. -That is, `type Foo = Bar` means that any function defined for `Bar` is defined for `Foo` - that is, objects of type `Foo` can be used any time an object of type `Bar` is called for. -If such behavior is not desired, the `distinct` keyword forces explicit qualification and conversion of types. `type Foo = distinct Baz` will force a type `Foo` to be wrapped in a call to the constructor `Baz()` before being passed to such functions. - -Types, like functions, can be *generic*: declared with "holes" that may be filled in with other types upon usage. A type must have all its holes filled before it can be constructed. The syntax for generics in types much resembles the syntax for generics in functions, and *constraints* and the like also apply. - -```puck -type MyStruct = struct - a: str - b: str -type MyTuple = tuple[str, b: str] - -let a: MyTuple = ("hello", "world") -print a.1 # world -``` - -Struct and tuple types are declared with `struct[]` and `tuple[]`, respectively. Their declarations make them look similar at a glance, but they differ fairly fundamentally. Structs are *unordered*, and every field must be named. They may be constructed with `{}` brackets. Tuples are *ordered* and so field names are optional - names are just syntactic sugar for positional access. Tuples may be constructed with `()` parenthesis. - -I am undecided whether to allow *structural subtyping*: that is, `{a: Type, b: Type, c: Type}` being valid in a context expecting `{a: Type, b: Type}`. This has benefits (multiple inheritance with no boilerplate) but also downsides (obvious). - -It is worth noting that there is no concept of `pub` at a field level on structs - a type is either fully transparent, or fully opaque. This is because such partial transparency breaks with structural initialization (how could one provide for hidden fields?). An idiomatic workaround is to model the desired field structure with a public-facing interface. - -```puck -type Expr = union - Literal(int) - Variable(str) - Abstraction(param: str, body: ref Expr) - Application(body: ref Expr, arg: ref Expr) -``` - -Union types are composed of a list of *variants*. Each variant has a *tag* and an *inner type* the union wraps over. Before the inner type can be accessed, the tag must be pattern matched upon, in order to handle all possible values. These are also known as *sum types* or *tagged unions* in other languages. - -Union types are the bread and butter of structural pattern matching. Composed with structs and tuples, unions provide for a very general programming construct commonly referred to as an *algebraic data type*. -This is often useful as an idiomatic and safer replacement for inheritance. - -```puck -pub type Iter[T] = interface - next(mut Self): T? - -pub type Peek[T] = interface - next(mut Self): T? - peek(mut Self): T? - peek_nth(mut Self, int): T? -``` - -Interface types function much as type classes in Haskell or traits in Rust do. They are not concrete types, and cannot be constructed - instead, their utility is via indirection, as parameters or as `ref` types, providing constraints that some concrete type must meet. They consist of a list of function signatures, implementations of which must exist for the given type in order to compile. - -Their major difference, however, is that Puck's interfaces are *implicit*: there is no `impl` block that implementations of their associated functions have to go under. If functions for a concrete type exist satisfying some interface, the type implements that interface. This does run the risk of accidentally implementing an interface one does not desire to, but the author believes such situations are few and far between, well worth the decreased syntactic and semantic complexity, and mitigatable with tactical usage of the `distinct` keyword. - -As the compiler makes no such distinction between fields and single-argument functions on a type when determining identifier conflicts, interfaces similarly make no such distinction. They *do* distinguish mutable and immutable parameters, those being part of the type signature. - -Interfaces are widely used throughout the standard library to provide general implementations of such conveniences like iteration, debug and display printing, generic error handling, and much more. diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md new file mode 100644 index 0000000..df4b22f --- /dev/null +++ b/docs/OVERVIEW.md @@ -0,0 +1,236 @@ +# An Overview of Puck + +Puck is an experimental, high-level, memory-safe, statically-typed, whitespace-sensitive, interface-oriented, imperative programming language with functional underpinnings. It attempts to explore designs in making functional programming paradigms comfortable to those familiar with imperative and object-oriented languages, as well as deal with some more technical problems along the way, such as integrated refinement types and cross-language interop. Primarily, however, this is the language I keep in my head. It reflects the way I think and reason about code. + +I do hope others enjoy it. + +```puck +let ident: int = 413 +# type annotations are optional +var phrase = "Hello, world!" +const compile_time = when linux: "linux" else: "windows" +``` + +Variables may be mutable (`var`), immutable (`let`), or compile-time evaluated and immutable (`const`). +Type annotations on variables and other bindings follow the name of the binding (with `: Type`), and are typically optional. +Variables are conventionally written in `snake_case`. Types are conventionally written in `PascalCase`. +The type system is comprehensive, and complex enough to warrant delaying full coverage of until the end. Some basic types are of note, however: +- `int`, `uint`: signed and unsigned integers + - `i8`/`i16`/`i32`/`i64`/`i128`: their fixed-size counterparts + - `u8`/`u16`/`u32`/`u64`/`u128`: their fixed-size counterparts +- `float`, `decimal`: floating-point numbers + - `f32`/`f64`/`f128`: their fixed-size counterparts + - `dec64`/`dec128`: their fixed-size counterparts +- `byte`: an alias to `u8`, representing one byte +- `chr`: an alias to `u32`, representing one Unicode character +- `bool`: defined as `union[false, true]` +- `array[T, S]`: primitive fixed-size (`S`) arrays +- `list[T]`: dynamic lists +- `str`: mutable strings. internally a `list[byte]`, externally a `list[chr]` +- `slice[T]`: borrowed "views" into the three types above + +Comments are declared with `#` and run until the end of the line. +Documentation comments are declared with `##` and may be parsed by language servers and other tooling. +Multi-line comments are declared with `#[ ]#` and may be nested. +Taking cues from the Lisp family of languages, any expression may be commented out with a preceding `#;`. + +```puck +func reverse(s: str): str = + let half_len = s.len div 2 + s.get(half_len, s.len)!.reverse() & s.get(half_len, s.len)!.reverse() + +pub func... + +# May fail! `yeet` denotes functions that can throw +pub yeet func pretty_print[T](value: T) = + # the ! converts optionals into throwing exceptions + print!(typeof(value)) + print!(value) +``` + +Functions are declared with the `func` keyword. They take an (optional) list of generic parameters (in brackets), an (optional) list of parameters (in parentheses), and **must** be annotated with a return type if they return a type. Every function parameter must be annotated with a type. Their type may optionally be prefixed with either `mut` or `static`: denoting a *mutable* type (types are copied into functions and thus immutable by default), or a *static* type (known to the compiler at compile time, and usable in `const` exprs). Generic parameters may each be optionally annotated with a type functioning as a _constraint_. + + + +Whitespace is significant but flexible: functions may be declared entirely on one line if so desired. A new level of indentation after certain tokens (`:`, `=`) denotes a new level of scope. There are some places where arbitrary indentation and line breaks are allowed - as a general rule of thumb, after operators, commas, and opening parentheses. The particular rules governing indentation may be found in the [syntax guide](SYNTAX.md#indentation-rules). + +```puck +``` + +Puck supports *uniform function call syntax*: and so any function may be called using the typical syntax for method calls, that is, the first parameter of any function may be appended with a `.` and moved to precede it, in the style of a typical method. (There are no methods in Puck. All functions are statically dispatched. This may change in the future.) + +This allows for a number of syntactic cleanups. Arbitrary functions with compatible types may be chained with no need for a special pipe operator. Object field access, module member access, and function calls are unified, reducing the need for getters and setters. Given a first type, IDEs using dot-autocomplete can fill in all the functions defined for that type. Programmers from object-oriented languages may find the lack of classes more bearable. UFCS is implemented in shockingly few languages, and so Puck joins the tiny club that previously consisted of just D and Nim. + +```puck +``` + +Boolean logic and integer operations are standard and as one would expect out of a typed language: `and`, `or`, `xor`, `not`, `shl`, `shr`, `+`, `-`, `*`, `/`, `<`, `>`, `<=`, `>=`, `div`, `mod`, `rem`. Notably: +- the words `and`/`or`/`not`/`shl`/`shr` are used instead of the symbolic `&&`/`||`/`!`/`<<`/`>>` +- integer division is expressed with the keyword `div` while floating point division uses `/` +- `%` is absent and replaced with distinct modulus and remainder operators +- boolean operators are bitwise and also apply to integers and floats +- more operators are available via the standard library + +The above operations are performed with *operators*, special functions that take a prefixed first argument and (often) a suffixed second argument. Custom operators may be implemented, but they must consist of only a combination of the symbols `=` `+` `-` `*` `/` `<` `>` `@` `$` `~` `&` `%` `|` `!` `?` `^` `\` for the purpose of keeping the grammar context-free. They are are declared identically to functions. + +Term (in)equality is expressed with the `==` and `!=` operators. Type equality is expressed with `is`. Subtyping relations may be queried with `of`, which has the additional property of introducing new bindings in the current scope (more on this in the [types document](TYPES.md)). + +```puck +let phrase: str = "I am a string! Wheeee! ✨" +for c in phrase: + stdout.write(c) # I am a string! Wheeee! ✨ +for b in phrase.bytes(): + stdout.write(b.chr) # Error: cannot convert between u8 and chr +print phrase.last() # ✨ +``` + +String concatenation uses a distinct `&` operator rather than overloading the `+` operator (as the complement `-` has no natural meaning for strings). Strings are unified, mutable, internally a byte array, externally a char array, and are stored as a pointer to heap data after their length and capacity (fat pointer). Chars are four bytes and represent a Unicode character in UTF-8 encoding. Slices of strings are stored as a length followed by a pointer to string data, and have non-trivial interactions with the memory management system. More details can be found in the [type system overview](TYPES.md). + +```puck +``` + +Basic conditional control flow uses standard `if`/`elif`/`else` statements. The `when` statement provides a compile-time `if`. It also takes `elif` and `else` branches and is syntactic sugar for an `if` statement within a `static` block (more on those later). + +All values in Puck must be handled, or explicitly discarded. This allows for conditional statements and many other control flow constructs to function as *expressions*, and evaluate to a value, when an unbound value is left at the end of each of their branches' scopes. This is particularly relevant for *functions*, where it is often idiomatic to omit an explicit `return` statement. There is no attempt made to differentiate without context, and so expressions and statements often look identical in syntax. + +```puck +``` + +Exhaustive structural pattern matching is available with the `match`/`of` statement, and is particularly useful for the `struct` and `union` types. `of` branches of a `match` statement take a *pattern*, of which the unbound identifiers within will be injected into the branch's scope. Multiple patterns may be used for one branch provided they all bind the same identifiers of the same type. Branches may be *guarded* with the `where` keyword, which takes a conditional, and will necessarily remove the branch from exhaustivity checks. + + + +The `of` statement also stands on its own as an operator for querying subtype equality. Used as a conditional in `if` statements or `while` loops, it retains the variable injection properties of its `match` counterpart. This allows it to be used as a compact alternative to `if let` statements in other languages. + +```puck +func may_fail: Result[T, ref Err] +``` + +Error handling is done via a fusion of imperative `try`/`catch` statements and functional `Option`/`Result` types, with much syntactic sugar. Functions may `raise` errors, but should return `Option[T]` or `Result[T, E]` types instead by convention. The compiler will note functions that `raise` errors, and force explicit qualification of them via `try`/`catch` statements. + +A bevy of helper functions and macros are available for `Option`/`Result` types, and are documented and available in the `std.options` and `std.results` modules (included in the prelude by default). Two in particular are of note: the `?` macro accesses the inner value of a `Result[T, E]` or propagates (returns in context) the `Error(e)`, and the `!` accesses the inner value of an `Option[T]` / `Result[T, E]` or raises an error on `None` / the specific `Error(e)`. Both operators take one parameter and so are postfix. (There is additionally another `?` postfix macro, taking in a type, as a shorthand for `Option[T]`) + +The utility of the `?` macro is readily apparent to anyone who has written code in Rust or Swift. The utility of the `!` function is perhaps less so obvious. These errors raised by `!`, however, are known to the compiler: and they may be comprehensively caught by a single or sequence of `catch` statements. This allows for users used to a `try`/`catch` error handling style to do so with ease, with only the need to add one additional character to a function call. + +More details may be found in [error handling overview](ERRORS.md). + +```puck +loop: + break +``` + +Three types of loops are available: `for` loops, `while` loops, and infinite loops (`loop` loops). For loops take a binding (which may be structural, see pattern matching) and an iterable object and will loop until the iterable object is spent. While loops take a condition that is executed upon the beginning of each iteration to determine whether to keep looping. Infinite loops are infinite are infinite are infinite are infinite are infinite are infinite and must be manually broken out of. + +There is no special concept of iterators: iterable objects are any object that implements the `Iter[T]` interface (more on those in [the type system document](TYPES.md)), that is, provides a `self.next()` function returning an `Option[T]`. As such, iterators are first-class constructs. For loops can be thought of as while loops that unwrap the result of the `next()` function and end iteration upon a `None` value. While loops, in turn, can be thought of as infinite loops with an explicit conditional break. + +The `break` keyword immediately breaks out of the current loop, and the `continue` keyword immediately jumps to the next iteration of the current loop. Loops may be used in conjunction with blocks for more fine-grained control flow manipulation. + +```puck +block: + statement + +let x = block: + let y = read_input() + transform_input(y) + +block foo: + for i in 0 ..= 100: + block bar: + if i == 10: break foo + print i +``` + +Blocks provide arbitrary scope manipulation. They may be labelled or unlabelled. The `break` keyword additionally functions inside of blocks and without any parameters will jump out of the current enclosing block (or loop). It may also take a block label as a parameter for fine-grained scope control. + +```puck +``` + +Code is segmented into modules. Modules may be made explicit with the `mod` keyword followed by a name, but there is also an implicit module structure in every codebase that follows the structure and naming of the local filesystem. For compatibility with filesystems, and for consistency, module names are exclusively lowercase (following the same rules as Windows). + +A module can be imported into another module by use of the `use` keyword, taking a path to a module or modules. Contrary to the majority of languages ex. Python, unqualified imports are *encouraged* - in fact, are idiomatic (and the default) - type-based disambiguation and official LSP support are intended to remove any ambiguity. + +Within a module, functions, types, constants, and other modules may be *exported* for use by other modules with the `pub` keyword. All such identifiers are private by default and only accessible module-locally without. Modules are first-class and may be bound, inspected, modified, and returned. As such, imported modules may be *re-exported* for use by other modules by binding them to a public constant, i.e. `use my_module; pub const my_module = my_module`. + +More details may be found in the [modules document](MODULES.md). + +```puck +``` + +Compile-time programming may be done via the previously-mentioned `const` keyword and `when` statements: or via `const` *blocks*. All code within a `const` block is evaluated at compile-time and all assignments and allocations made are propagated to the compiled binary as static data. + +Further compile-time programming may be done via metaprogramming: compile-time manipulation of the abstract syntax tree. The macro system is complex, and a description may be found in the [metaprogramming document](METAPROGRAMMING.md). + +```puck +func await(promise: Promise) +pub async func + +await +``` + +The async system is *colourblind*: the special `async` macro will turn any function *call* returning a `T` into an asynchronous call returning a `Future[T]`. The special `await` function will wait for any `Future[T]` and return a `T` (or an error). Async support is included in the standard library in `std.async` in order to allow for competing implementations. More details may be found in the [async document](ASYNC.md). + +Threading support is complex and also regulated to external libraries. OS-provided primitives will likely provide a `spawn` function, and there will be substantial restrictions for memory safety. I really haven't given much thought to this. + +```puck +``` + +Details on memory safety, references and pointers, and deep optimizations may be found in the [memory management overview](MEMORY_MANAGEMENT.md). +The memory model intertwines deeply with the type system. + +```puck +``` + +Finally, a few notes on the type system are in order. + +Types are declared with the `type` keyword and are transparent aliases. +That is, `type Foo = Bar` means that any function defined for `Bar` is defined for `Foo` - that is, objects of type `Foo` can be used any time an object of type `Bar` is called for. +If such behavior is not desired, the `distinct` keyword forces explicit qualification and conversion of types. `type Foo = distinct Baz` will force a type `Foo` to be wrapped in a call to the constructor `Baz()` before being passed to such functions. + +Types, like functions, can be *generic*: declared with "holes" that may be filled in with other types upon usage. A type must have all its holes filled before it can be constructed. The syntax for generics in types much resembles the syntax for generics in functions, and *constraints* and the like also apply. + +```puck +type MyStruct = struct + a: str + b: str +type MyTuple = tuple[str, b: str] + +let a: MyTuple = ("hello", "world") +print a.1 # world +``` + +Struct and tuple types are declared with `struct[]` and `tuple[]`, respectively. Their declarations make them look similar at a glance, but they differ fairly fundamentally. Structs are *unordered*, and every field must be named. They may be constructed with `{}` brackets. Tuples are *ordered* and so field names are optional - names are just syntactic sugar for positional access. Tuples may be constructed with `()` parenthesis. + +I am undecided whether to allow *structural subtyping*: that is, `{a: Type, b: Type, c: Type}` being valid in a context expecting `{a: Type, b: Type}`. This has benefits (multiple inheritance with no boilerplate) but also downsides (obvious). + +It is worth noting that there is no concept of `pub` at a field level on structs - a type is either fully transparent, or fully opaque. This is because such partial transparency breaks with structural initialization (how could one provide for hidden fields?). An idiomatic workaround is to model the desired field structure with a public-facing interface. + +```puck +type Expr = union + Literal(int) + Variable(str) + Abstraction(param: str, body: ref Expr) + Application(body: ref Expr, arg: ref Expr) +``` + +Union types are composed of a list of *variants*. Each variant has a *tag* and an *inner type* the union wraps over. Before the inner type can be accessed, the tag must be pattern matched upon, in order to handle all possible values. These are also known as *sum types* or *tagged unions* in other languages. + +Union types are the bread and butter of structural pattern matching. Composed with structs and tuples, unions provide for a very general programming construct commonly referred to as an *algebraic data type*. +This is often useful as an idiomatic and safer replacement for inheritance. + +```puck +pub type Iter[T] = interface + next(mut Self): T? + +pub type Peek[T] = interface + next(mut Self): T? + peek(mut Self): T? + peek_nth(mut Self, int): T? +``` + +Interface types function much as type classes in Haskell or traits in Rust do. They are not concrete types, and cannot be constructed - instead, their utility is via indirection, as parameters or as `ref` types, providing constraints that some concrete type must meet. They consist of a list of function signatures, implementations of which must exist for the given type in order to compile. + +Their major difference, however, is that Puck's interfaces are *implicit*: there is no `impl` block that implementations of their associated functions have to go under. If functions for a concrete type exist satisfying some interface, the type implements that interface. This does run the risk of accidentally implementing an interface one does not desire to, but the author believes such situations are few and far between, well worth the decreased syntactic and semantic complexity, and mitigatable with tactical usage of the `distinct` keyword. + +As the compiler makes no such distinction between fields and single-argument functions on a type when determining identifier conflicts, interfaces similarly make no such distinction. They *do* distinguish mutable and immutable parameters, those being part of the type signature. + +Interfaces are widely used throughout the standard library to provide general implementations of such conveniences like iteration, debug and display printing, generic error handling, and much more. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..35374e8 --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,44 @@ +# Summary + +[The Puck Programming Language](../README.md) + +- [Basic Usage](OVERVIEW.md) + - [Variables and Comments]() + - [Basic Types]() + - [Functions and Calls]() + - [Boolean and Integer Operations]() + - [Conditionals and Control Flow]() + - [Error Handling]() + - [Loops and Iterators]() + - [Modules]() + - [Compile-time Programming]() + - [Async and Threading]() + - [Advanced Types]() +- [Syntax](SYNTAX.md) + - [Indentation Rules]() + - [Reserved Keywords]() + - [A Formal Grammar]() +- [Type System](TYPES.md) + - [Basic Types]() + - [Parameter Types]() + - [Reference Types]() + - [Abstract Types]() + - [Advanced Types]() +- [Module System [todo]](MODULES.md) + - [Implicit Modules]() + - [Namespacing]() + - [Interfaces, Again]() +- [Error Handling](ERRORS.md) +- [Async System](ASYNC.md) + - [Threading]() +- [Metaprogramming](METAPROGRAMMING.md) +- [Memory Management [todo]](MEMORY_MANAGEMENT.md) + - [Reference Counting Optimizations]() + - [Annotations and Ownership]() +- [Language Interop [draft]](INTEROP.md) + - [Rust, Swift, Nim]() + - [Java, Kotlin]() + - [Python, Racket, C]() +- [Refinement Types [draft]](REFINEMENTS.md) +- [Dependent Types [draft]](DEPENDENT_TYPES.md) +- [Effects System [draft]](EFFECTS.md) -- cgit v1.2.3-70-g09d2