From 82fd8a73dadf2be33f7031d7180040ad857fd051 Mon Sep 17 00:00:00 2001 From: ellemenno Date: Sun, 16 Dec 2018 02:59:40 -0500 Subject: [PATCH 01/10] prefer ssl urls --- README.md | 2 +- docs/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c103473..65d1956 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ This site attempts to form a language reference out of the hours and hours of vi Other unofficial jai summaries: -- http://www.mrphilgames.com/jai/ +- https://www.mrphilgames.com/jai/ - https://github.com/BSVino/JaiPrimer/blob/master/JaiPrimer.md - https://inductive.no/jai/ diff --git a/docs/index.md b/docs/index.md index f69e3cf..0f6a927 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,7 +15,7 @@ This site attempts to distill a language reference out of the hours and hours of Other unofficial jai summaries: -- +- - - From 168b88bb524c26dc7f127457f87806fdc7765c79 Mon Sep 17 00:00:00 2001 From: ellemenno Date: Sat, 22 Dec 2018 18:57:41 -0500 Subject: [PATCH 02/10] improve footnote rendering; factor video info into data file --- docs/_data/videos.yaml | 30 +++++ docs/_features/General-Syntax.md | 130 +++++++++++++++---- docs/_features/Language-Features.md | 178 ++++++++++++++++++++------ docs/_includes/footnotes.liquid | 33 +++++ docs/_overview/Basic-premises.md | 121 +++++++++++++---- docs/_overview/Meaning-of-the-name.md | 44 +++++-- 6 files changed, 441 insertions(+), 95 deletions(-) create mode 100644 docs/_data/videos.yaml create mode 100644 docs/_includes/footnotes.liquid diff --git a/docs/_data/videos.yaml b/docs/_data/videos.yaml new file mode 100644 index 0000000..2594477 --- /dev/null +++ b/docs/_data/videos.yaml @@ -0,0 +1,30 @@ +## +## Videos referenced in the documentation +## MLA style format: "Title of Video." YouTube, uploaded by Username, Date, URL (without the http://). +## from: https://libanswers.snhu.edu/faq/48006 +## + +ideas_20140919: + mla: |- + “Ideas about a new programming language for games.” _YouTube_, uploaded by Jonathan Blow, Sep 19, 2014 + url: https://youtu.be/TH9VCN6UkyQ + +ideas_20140926: + mla: |- + “A Programming Language for Games, talk #2.” _YouTube_, uploaded by Jonathan Blow, Sep 26, 2014 + url: https://youtu.be/5Nc68IdNKdg + +demo_20141031: + mla: |- + “Demo: Base language, compile-time execution.” _YouTube_, uploaded by Jonathan Blow, Oct 31, 2014 + url: https://youtu.be/UTqZNujQOlA + +reboot_2017: + mla: |- + “Reboot Develop 2017 - Jonathan Blow, Thekla Inc. / Making Game Programming Less Terrible.” _YouTube_, uploaded by Reboot Develop, May 22, 2017 + url: https://youtu.be/De0Am_QcZiQ + +gamelab_2018: + mla: |- + “#Gamelab2018 - Jon Blow's Design decisions on creating Jai, a new language for game programmers.” _YouTube_, uploaded by Social Gamelab, Jul 13, 2018 + url: https://youtu.be/uZgbKrDEzAs diff --git a/docs/_features/General-Syntax.md b/docs/_features/General-Syntax.md index a908acb..56e51fd 100644 --- a/docs/_features/General-Syntax.md +++ b/docs/_features/General-Syntax.md @@ -1,8 +1,72 @@ --- layout: page title: General Syntax + +footnotes: + - + label: basic-types + video: demo_20141031 + time: 803 + text: the basic language types. + - + label: for-iteration + video: demo_20141031 + time: 1678 + text: iteration over elements with `for`. + - + label: for-statements + video: demo_20141031 + time: 1968 + text: |- + `for`.. `break`, `continue`, `return`. + - + label: defer + video: demo_20141031 + time: 1365 + text: defer is not a macro, it is a core part of the language understood by the compiler and debugger. + - + label: enum-declaration + video: demo_20141031 + time: 1058 + text: enums are typed, can be named or anonymous, and can refer to values declared elsewhere. + - + label: function-declaration + video: ideas_20140926 + time: 2686 + text: basic function syntax. + - + label: new-delete + video: demo_20141031 + time: 1265 + text: |- + `new` and `delete` are cleaner than c++. + - + label: prevent-initialization + text: 'FIXME: find this video reference' + - + label: scalar-declaration + video: ideas_20140926 + time: 1666 + text: declarations and assignment. + - + label: scope-capture + video: ideas_20140926 + time: 3041 + text: capture is a property of the code block and not the function header. + - + label: syntax-comments + video: demo_20141031 + time: 705 + text: c-style comments, but with proper nesting support. + - + label: void-pointer-hack + video: demo_20141031 + time: 1780 + text: void pointer may have been removed from language since this video. + --- + # {{ page.title }} - TOC @@ -21,10 +85,9 @@ title: General Syntax ## Atomic Types [^basic-types] - -- `---` - uninitialized +- `---` - uninitialized [^prevent-initialization] - `null` - null pointer, unequal to any pointer to any object or function -- `void` - void pointer, maybe a temporary idea {% comment %} # FIXME: is this still in? see: https://youtu.be/UTqZNujQOlA?t=1780 {% endcomment %} +- `void` - void pointer, maybe a temporary idea [^void-pointer-hack] {% comment %} # FIXME: is this still in? see: https://youtu.be/UTqZNujQOlA?t=1780 {% endcomment %} - `bool` - [`true`, `false`] - `int` - integer number (thirty-two bit) - `float` - floating point number @@ -85,15 +148,18 @@ Vector3 :: struct { } ``` -### Enums +### Enums [^enum-declaration] ```cpp My_Enum :: enum u16 { - FIRST, - SECOND, - THIRD = 80, - FOURTH, + VALUE_ZERO = 0, + VALUE_ONE, + VALUE_THREE = VALUE_TWO, + VALUE_FOUR = MIDDLE_VALUE, // declared outside of enum + VALUE_HIGH, // trailing comma is fine } + +MIDDLE_VALUE := 8; ``` ### Functions and lambdas [^function-declaration] @@ -144,9 +210,37 @@ answer, error := ???; ``` +## Initialization + +> variable declarations are automatically initialized to type defaults.
+> initialization can be implicit (accept default), explicit (provide value), or blocked (`---`).
+ +[^prevent-initialization]: []() + +```cpp +Vector2_implicit :: struct { + x: float; + y: float; +} +Vector2_explicit :: struct { + x: float = 3; + y: float = 5; +} +Vector2_blocked :: struct { + x: float = ---; + y: float = ---; +} + +vi: Vector2_implicit; print("% %\n", vi.x, vi.y); // "0 0" +ve: Vector2_explicit; print("% %\n", ve.x, ve.y); // "3 5" +vb: Vector2_blocked; print("% %\n", vb.x, vb.y); // compiler error? +veb: Vector2_explicit = ---; print("% %\n", ve.x, ve.y); // compiler error? +``` + + ## Iteration -### for [^for1] [^for2] +### for [^for-iteration] [^for-statements] `for` - supports named or implicit iterators (`it`)
`break` - exits current scope
@@ -209,20 +303,4 @@ main := () { `delete` - frees memory ---- - -## footnotes - -{% capture external_link %}{% include icon.liquid id='external-link' %}{% endcapture %} -{% capture ideas2_2014 %}A Programming Language for Games, talk #2{% endcapture %} -{% capture demo_2014-10-31 %}Demo: Base language, compile-time execution{% endcapture %} - -[^basic-types]: the basic types. [_{{ demo_2014-10-31 }}_ {{ external_link }}](https://youtu.be/UTqZNujQOlA?t=803) -[^for1]: iteration over elements with `for`. [_{{ demo_2014-10-31 }}_ {{ external_link }}](https://youtu.be/UTqZNujQOlA?t=1678) -[^for2]: `for`.. `break`, `continue`, `return`. [](https://youtu.be/UTqZNujQOlA?t=1968) -[^defer]: defer is not a macro, it is a core part of the language understood by the compiler and debugger. [_{{ demo_2014-10-31 }}_ {{ external_link }}](https://youtu.be/UTqZNujQOlA?t=1365) -[^function-declaration]: basic function syntax. [_{{ ideas2_2014 }}_ {{ external_link }}](https://youtu.be/5Nc68IdNKdg?t=2686) -[^new-delete]: `new` and `delete` are cleaner than c++. [_{{ demo_2014-10-31 }}_ {{ external_link }}](https://youtu.be/UTqZNujQOlA?t=1265) -[^scalar-declaration]: declarations and assignment. [_{{ ideas2_2014 }}_ {{ external_link }}](https://youtu.be/5Nc68IdNKdg?t=1666) -[^scope-capture]: capture is a property of the code block and not the function header. [_{{ ideas2_2014 }}_ {{ external_link }}](https://youtu.be/5Nc68IdNKdg?t=3041) -[^syntax-comments]: c-style comments, but with proper nesting support. [_{{ demo_2014-10-31 }}_ {{ external_link }}](https://youtu.be/UTqZNujQOlA?t=705) +{% include footnotes.liquid references=page.footnotes %} diff --git a/docs/_features/Language-Features.md b/docs/_features/Language-Features.md index 8241173..3931228 100644 --- a/docs/_features/Language-Features.md +++ b/docs/_features/Language-Features.md @@ -1,8 +1,147 @@ --- layout: page title: Language Features + +footnotes: + - + label: ast-access + video: reboot_2017 + time: 2551 + text: data structures for all the code in the program. + - + label: build-options + video: reboot_2017 + time: 1759 + text: you have a struct that defines the build options, and you apply those build options to the compiler workspace. + - + label: build-routine + video: demo_20141031 + time: 3859 + text: using the `#run` directive to run a build routine at compile time. + - + label: capture-for-any-block + video: ideas_20140926 + time: 3344 + text: i can just apply a capture to any block. + - + label: code-maturation + video: ideas_20140926 + time: 2171 + text: your programming language should be designed to support the transition from humble beginnings to final product. + - + label: code-modification + video: reboot_2017 + time: 2571 + text: you can modify compile-time data structures and resubmit them. + - + label: compiler-does-everything + video: ideas_20140919 + time: 5166 + text: you shouldn't need wacky different tools on every operating system. you should need the compiler and your source code and that's all. + - + label: concurrency + video: ideas_20140919 + time: 4810 + text: concurrency is huge. It's going to get huger for games. + - + label: directive-assert + video: demo_20141031 + time: 3078 + text: a flavor of `#run`, allowing arbitrary code at compile time to run as part of an assertion check. + - + label: directive-check-call + video: demo_20141031 + time: 2362 + text: |- + `#checkcall` invokes arbitrary user-provided checking methods at compile time. + - + label: directive-run + video: demo_20141031 + time: 2701 + text: |- + `#run` directive to execute code at compile time. + - + label: directive-compile-time + video: demo_20141031 + time: 5443 + text: boolean indication of running at compile time. + - + label: factorability-drudge + video: ideas_20140926 + time: 1837 + text: we want to avoid meaningless syntactic changes that create drudge work as I gradually factor my program from its beginning state into its final state. + - + label: factorability-lift + video: ideas_20140926 + time: 3549 + text: we have this whole sequence of stages we can lift a block of code on. + - + label: ffi-printf + video: demo_20141031 + time: 1599 + text: a straight-forward foreign function interface allows things like calling out to C for `printf`. + - + label: file-path-name-line + video: demo_20141031 + time: 3876 + text: current filepath, filename, and code line are available as directives at compile time. + - + label: introspection + video: reboot_2017 + time: 1945 + text: introspection / reflection. + - + label: memory-memory-memory + video: ideas_20140919 + time: 2296 + text: it's about memory and memory only. + - + label: no-exceptions + video: ideas_20140919 + time: 2379 + text: exceptions are silly at best, and horribly damaging at worst. + - + label: no-garbage-collection + video: ideas_20140919 + time: 407 + text: you can't build a sufficiently low-level system with sufficiently high performance characteristics in a garbage collected language. + - + label: no-header-files + video: ideas_20140919 + time: 4484 + text: no god damn header files. + - + label: no-preprocessor + video: demo_20141031 + time: 4058 + text: directives are part of the language; there is no preprocessor system. + - + label: no-smart-pointers + video: ideas_20140919 + time: 2718 + text: we're not afraid of pointers in the game industry. we need to use them. + - + label: no-template-metaprogamming + text: 'FIXME: find this video reference' + - + label: owned-pointer + video: ideas_20140919 + time: 2979 + text: notation to indicate memory ownership. + - + label: permissive-license + video: ideas_20140919 + time: 5195 + text: a language we adopt should have a permissive license. + - + label: run-in-compiler + video: reboot_2017 + time: 1526 + text: full compile-time execution. + --- + # {{ page.title }} - TOC @@ -45,6 +184,7 @@ Jai will be released under a permissive license, but the details have not been s - `#load "file.jai";` - bring a source code file into scope - `#no_inline ` - do not inline this function definition - `#run ` - execute `` at compile time (not run time) [^directive-run] +- `#running_at_compile_time` - boolean; `true` if execution is occuring during compile time [^directive-compile-time] ## Full compile-time code execution [^run-in-compiler] @@ -135,7 +275,7 @@ struct Mesh { Code has a maturation cycle; you don't just write the final thing initially, because you don't know what it should be. You work your way there. [^code-maturation] -Scalars and functions do not require meaningless syntax changes when changing scope, capturing scope [^capture-for-any-block], or switching between being named or unnamed. [^factorability1] [^factorability2] +Scalars and functions do not require meaningless syntax changes when changing scope, capturing scope [^capture-for-any-block], or switching between being named or unnamed. [^factorability-drudge] [^factorability-lift] ```cpp { ... } // Anonymous code block @@ -186,39 +326,5 @@ Equivalent data structures are provided for the entire text of the program (at c - `printf()` - calls out to C's printf [^ffi-printf] - OpenGL ---- -## footnotes - -{% capture external_link %}{% include icon.liquid id='external-link' %}{% endcapture %} -{% capture ideas1_2014 %}Ideas about a new programming language for games{% endcapture %} -{% capture ideas2_2014 %}A Programming Language for Games, talk #2{% endcapture %} -{% capture demo_2014-10-31 %}Demo: Base language, compile-time execution{% endcapture %} -{% capture reboot_2017 %}Reboot Develop 2017 - Jonathan Blow, Thekla Inc. / Making Game Programming Less Terrible{% endcapture %} - -[^ast-access]: data structures for all the code in the program. [_{{ reboot_2017 }}_ {{ external_link }}](https://youtu.be/De0Am_QcZiQ?t=2551) -[^build-options]: you have a struct that definces the build options, and you apply those build options to the compiler workspace. [_{{ reboot_2017 }}_ {{ external_link }}](https://youtu.be/De0Am_QcZiQ?t=1759) -[^build-routine]: using the `#run` directive to run a build routine at compile time. [_{{ demo_2014-10-31 }}_ {{ external_link }}](https://youtu.be/UTqZNujQOlA?t=3859) -[^capture-for-any-block]: i can just apply a capture to any block. [_{{ ideas2_2014 }}_ {{ external_link }}](https://youtu.be/5Nc68IdNKdg?t=3344) -[^code-maturation]: your programming language should be designed to support the transition from humble beginnings to final product. [_{{ ideas2_2014 }}_ {{ external_link }}](https://youtu.be/5Nc68IdNKdg?t=2171) -[^code-modification]: you can modify compile-time data structures and resubmit them. [_{{ reboot_2017 }}_ {{ external_link }}](https://youtu.be/De0Am_QcZiQ?t=2571) -[^compiler-does-everything]: you shouldn't need wacky different tools on every operating system. you should need the compiler and your source code and that's all. [_{{ ideas1_2014 }}_ {{ external_link }}](https://youtu.be/TH9VCN6UkyQ?t=5166) -[^concurrency]: concurrency is huge. It's going to get huger for games. [_{{ ideas1_2014 }}_ {{ external_link }}](https://youtu.be/TH9VCN6UkyQ?t=4810) -[^directive-assert]: a flavor of `#run`, allowing arbitrary code at compile time to run as part of an assertion check. [_{{ demo_2014-10-31 }}_ {{ external_link }}](https://youtu.be/UTqZNujQOlA?t=3078) -[^directive-check-call]: `#checkcall` invokes arbitrary user-provided checking methods at compile time [](https://youtu.be/UTqZNujQOlA?t=2362) -[^directive-run]: run directive to execute code at compile time. [_{{ demo_2014-10-31 }}_ {{ external_link }}](https://youtu.be/UTqZNujQOlA?t=2701) -[^factorability1]: we want to avoid meaningless syntactic changes that create drudge work as I gradually factor my program from its beginning state into its final state. [_{{ ideas2_2014 }}_ {{ external_link }}](https://youtu.be/5Nc68IdNKdg?t=1837) -[^factorability2]: we have this whole sequence of stages we can lift a block of code on. [_{{ ideas2_2014 }}_ {{ external_link }}](https://youtu.be/5Nc68IdNKdg?t=3549) -[^ffi-printf]: a straight-forward foreign function interface allows things like calling out to C for `printf`. [_{{ demo_2014-10-31 }}_ {{ external_link }}](https://youtu.be/UTqZNujQOlA?t=1599) -[^file-path-name-line]: current filepath, filename, and code line are available as directives at compile time. [_{{ demo_2014-10-31 }}_ {{ external_link }}](https://youtu.be/UTqZNujQOlA?t=3876) -[^introspection]: introspection / reflection. [_{{ reboot_2017 }}_ {{ external_link }}](https://youtu.be/De0Am_QcZiQ?t=1945) -[^memory-memory-memory]: it's about memory and memory only. [_{{ ideas1_2014 }}_ {{ external_link }}](https://youtu.be/TH9VCN6UkyQ?t=2296) -[^no-exceptions]: exceptions are silly. [_{{ ideas1_2014 }}_ {{ external_link }}](https://youtu.be/TH9VCN6UkyQ?t=2379) -[^no-garbage-collection]: you can't build a sufficiently low-level system with sufficiently high performance characteristics in a garbage collected language. [_{{ ideas1_2014 }}_ {{ external_link }}](https://youtu.be/TH9VCN6UkyQ?t=407) -[^no-header-files]: no god damn header files. [_{{ ideas1_2014 }}_ {{ external_link }}](https://youtu.be/TH9VCN6UkyQ?t=4484) -[^no-preprocessor]: directives are part of the language; there is no preprocessor system [_{{ demo_2014-10-31 }}_ {{ external_link }}](https://youtu.be/UTqZNujQOlA?t=4058) -[^no-smart-pointers]: we're not afraid of pointers in the game industry. we need to use them. [_{{ ideas1_2014 }}_ {{ external_link }}](https://youtu.be/TH9VCN6UkyQ?t=2718) -[^no-template-metaprogamming]: xxx. [_{{ ideas1_2014 }}_ {{ external_link }}](https://youtu.be/TH9VCN6UkyQ?t=2379) -[^owned-pointer]: notation to indicate memory ownership. [_{{ ideas1_2014 }}_ {{ external_link }}](https://youtu.be/TH9VCN6UkyQ?t=2979) -[^permissive-license]: A language we adopt should have a permissive license. [_{{ ideas1_2014 }}_ {{ external_link }}](https://youtu.be/TH9VCN6UkyQ?t=5195) -[^run-in-compiler]: full compile-time execution. [_{{ reboot_2017 }}_ {{ external_link }}](https://youtu.be/De0Am_QcZiQ?t=1526) +{% include footnotes.liquid references=page.footnotes %} diff --git a/docs/_includes/footnotes.liquid b/docs/_includes/footnotes.liquid new file mode 100644 index 0000000..8f81e22 --- /dev/null +++ b/docs/_includes/footnotes.liquid @@ -0,0 +1,33 @@ +{% comment %} +Render helper for footnotes + +parameters: + references - list of objects with the following properties: + label - footnote id, e.g. [^