diff --git a/README.md b/README.md index 322a4ab..3521351 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -ZScriptDoc -========== +# ZScriptDoc This is documentation for the ZScript language. CC0 public domain. See [LICENSE](LICENSE.txt) for more information. diff --git a/api.md b/api.md index 0124c91..b10a2b1 100644 --- a/api.md +++ b/api.md @@ -1,8 +1,11 @@ # API + + * [Actors](#actors) * [Base](#base) * [Drawing](#drawing) +* [Event Handling](#event-handling) * [Files](#files) * [Intermission Screens](#intermission-screens) * [Level Data](#level-data) @@ -11,6 +14,8 @@ * [Weapons](#weapons) * [Global Objects](#global-objects) + + The ZScript API (Advanced Programming Interface) is vast and has some holes which are hard to explain. Some parts are implemented in ways that don't make sense to user code, but are fine to the engine. Because of this, the API shall @@ -25,17 +30,17 @@ are part of the API. # Actors - + * [State](api-actor-State.md) - + TODO # Base - + * [Array](api-base-Array.md) * [Color](api-base-Color.md) @@ -47,13 +52,13 @@ TODO * [Thinker](api-base-Thinker.md) * [Vector](api-base-Vector.md) - + TODO # Drawing - + * [BrokenLines](api-drawing-BrokenLines.md) * [Console](api-drawing-Console.md) @@ -64,33 +69,33 @@ TODO * [TexMan](api-drawing-TexMan.md) * [TextureID](api-drawing-TextureID.md) - + TODO # Event Handling - + - + TODO # Files - + * [Wads](api-files-Wads.md) - + TODO # Intermission Screens - + * [InterBackground](api-inter-InterBackground.md) * [PatchInfo](api-inter-PatchInfo.md) @@ -98,7 +103,7 @@ TODO * [WBPlayerStruct](api-inter-WBPlayerStruct.md) * [WBStartStruct](api-inter-WBStartStruct.md) - + For legacy reasons, many intermission-related things may be prefixed with `WI` or `WB`. The abbreviation `WI` means *World Intermission* (the intermission @@ -108,7 +113,7 @@ for [statistics drivers](https://doomwiki.org/wiki/Statistics_driver). # Level Data - + * [F3DFloor](api-level-F3DFloor.md) * [FColorMap](api-level-FColorMap.md) @@ -121,45 +126,45 @@ for [statistics drivers](https://doomwiki.org/wiki/Statistics_driver). * [Side](api-level-Side.md) * [Vertex](api-level-Vertex.md) - + TODO # Players - + * [PlayerClass](api-player-PlayerClass.md) * [PlayerSkin](api-player-PlayerSkin.md) * [Team](api-player-Team.md) - + TODO # Sounds - + * [SeqNode](api-sound-SeqNode.md) - + TODO # Weapons - + * [PSprite](api-wep-PSprite.md) - + TODO # Global Objects - + * [Client](api-global-data-Client.md) * [Constants](api-global-data-Constants.md) @@ -167,12 +172,12 @@ TODO * [Information](api-global-data-Information.md) * [Player](api-global-data-Player.md) - + These variables are accessible in any context and are not bound by any specific object. Generally these mirror global information within the engine itself. - + * [Classes](api-global-func-Classes.md) * [Game](api-global-func-Game.md) @@ -181,19 +186,19 @@ object. Generally these mirror global information within the engine itself. * [Sound](api-global-func-Sound.md) * [System](api-global-func-System.md) - + These functions are accessible in any context and are not bound by any specific object. Generally these are utility functions. - + * [DEHInfo](api-global-DEHInfo.md) * [FOptionMenuSettings](api-global-FOptionMenuSettings.md) * [GameInfoStruct](api-global-GameInfoStruct.md) * [LevelLocals](api-global-LevelLocals.md) - + These are the types used by global variables. diff --git a/entry.md b/entry.md index b0599a1..5138aeb 100644 --- a/entry.md +++ b/entry.md @@ -1,5 +1,4 @@ -Entry Points -============ +# Entry Points @@ -23,8 +22,7 @@ itself, many interactions with the engine are not defined in ZScript. This section describes all ZScript interactions with the engine, both inside and outside of ZScript itself. -ACS -=== +# ACS ACS has several functions for interfacing with ZScript: `SetUserVariable` (callfunc `24`,) `GetUserVariable` (callfunc `25`,) `SetUserArray` (callfunc @@ -57,8 +55,7 @@ values, although more than one value will be ignored. The returned value may be `double` (converted to fixed-point,) `name`, `sound` or `string` (converted to ACS string.) If it is not one of these types, it will be ignored. -Actors -====== +# Actors Actor classes can be replaced by the `replaces` class flag, which during dynamic actor replacement will choose to spawn this class over its replaced @@ -73,52 +70,44 @@ class MyActor : Actor replaces OtherActor {} // OtherActor will be dynamically r class MyOtherActor : Actor replaces OtherActor {} // OtherActor will now be replaced with MyOtherActor instead of MyActor ``` -Console Commands -================ +# Console Commands While ZScript cannot be directly called by console commands, one can use the `event` and `netevent` console commands. `event` will call the `ConsoleProcess` event handler, or `NetworkProcess` if it was not called by a player. `netevent` acts the same as `EventHandler::SendNetworkEvent`. -CVARINFO -======== +# CVARINFO Any CVars declared as a server CVar in `CVARINFO` or by the engine will be accessible as a global variable in ZScript, which has a special type that can be implicitly cast to the type of the CVar. They cannot be set this way, only accessed. -DECALDEF -======== +# DECALDEF `DECALDEF` can set the decal generator for a specific `Actor` class with the `generator` keyword. An actor can also define its generator and inherited classes' generators with the `Decal` property. -DECORATE -======== +# DECORATE TODO: lots of things to note here -LOCKDEFS -======== +# LOCKDEFS Key and lock groups in `LOCKDEFS` are defined as groups of `Inventory` or `Key` descendants. -GLDEFS -====== +# GLDEFS Lights can be associated with `Actor` classes and frames in `GLDEFS`. -KEYCONF -======= +# KEYCONF TODO: this can be used for custom buttons -MAPINFO -======= +# MAPINFO In `MAPINFO`, the `GameInfo` block (referred to as `MAPINFO`/GameInfo in this document) the following properties interact directly with ZScript: @@ -135,13 +124,11 @@ document) the following properties interact directly with ZScript: TODO: there are other things here as well, like map event handlers -MENUDEF -======= +# MENUDEF TODO: this directly uses ZScript classes -TERRAIN -======= +# TERRAIN The `SmallSplash`, `SplashBase` and `SplashChunk` properties of `Splash` blocks use `Actor`s. diff --git a/glossary.md b/glossary.md index e852d0d..f939346 100644 --- a/glossary.md +++ b/glossary.md @@ -1,16 +1,15 @@ -Glossary -======== +# Glossary - + * [Classes](glossary-Classes.md) * [Concepts](glossary-Concepts.md) * [Structures](glossary-Structures.md) * [Versions](glossary-Versions.md) - + -Miscallaneous information about ZScript, including code examples and version +Miscallaneous information about ZScript, including class lists and version differences. diff --git a/lang-Classes.md b/lang-Classes.md index a6fba64..a7e3b1b 100644 --- a/lang-Classes.md +++ b/lang-Classes.md @@ -1,5 +1,4 @@ -Class Definitions -================= +# Class Definitions @@ -112,8 +111,7 @@ int m_MyMember; // end of file ``` -Class Flags -=========== +# Class Flags | Flag | Description | | ---- | ----------- | @@ -127,8 +125,7 @@ Class Flags `Replace-class` in this context is an `Identifier` denoting a class which inherits `Actor`. -Class Content -============= +# Class Content Class contents are an optional list of various things logically contained within the class, including: @@ -144,8 +141,7 @@ within the class, including: - Constant definitions - Static array definitions -Property Definitions -==================== +# Property Definitions Property definitions are used within classes to define defaultable attributes on actors. They are not valid on classes not derived from Actor. @@ -185,8 +181,7 @@ class MyCoolActor : Actor } ``` -Flag Definitions -================ +# Flag Definitions *Version 3.7.0 and newer.* @@ -243,8 +238,7 @@ class MyCoolActorWithFlags : Actor } ``` -Default Blocks -============== +# Default Blocks Default blocks are used on classes derived from Actor to create an overridable list of defaults to properties, allowing for swift creation of flexible actor @@ -297,8 +291,7 @@ actor. Here is a list of them: Note that like any other property, they require a semicolon after them, although they do not use an expression. -State Definitions -================= +# State Definitions These are the same as `DECORATE`, but states that do not have function blocks require terminating semicolons. Double quotes around `#` and `-` are no longer diff --git a/lang-Constants.md b/lang-Constants.md index a9a3086..f4c8d2f 100644 --- a/lang-Constants.md +++ b/lang-Constants.md @@ -1,5 +1,4 @@ -Constant Definitions -==================== +# Constant Definitions @@ -26,8 +25,7 @@ Making an integer constant from a double. const MY_COOL_INT = int(777.7777); ``` -Static array definitions -========================= +# Static array definitions Similar to constants, static arrays are named values, but for an array. They are created with the syntax: diff --git a/lang-Expressions.md b/lang-Expressions.md index 8f408aa..48d44dd 100644 --- a/lang-Expressions.md +++ b/lang-Expressions.md @@ -1,5 +1,4 @@ -Expressions and Operators -========================= +# Expressions and Operators @@ -23,8 +22,7 @@ Expressions and Operators -Literals -======== +# Literals Much like C or most other programming languages, ZScript has object literals, including string literals, integer literals, float literals, name literals, @@ -157,8 +155,7 @@ The null pointer literal is spelled `null` and represents an object that does not exist in memory. Like C, it is not equivalent to the integer literal `0`, and is more similar to C++'s `nullptr`. -Expressions -=========== +# Expressions Expressions contain literals or other such *expressions* of objects, including arithmetic and various conditions. diff --git a/lang-Members.md b/lang-Members.md index 861bdbc..de871df 100644 --- a/lang-Members.md +++ b/lang-Members.md @@ -1,5 +1,4 @@ -Member Declarations -=================== +# Member Declarations @@ -30,8 +29,7 @@ private int m_CoolPrivateInt; protected meta int m_CoolMetaInt; ``` -Member Declaration Flags -======================== +# Member Declaration Flags | Flag | Description | | ---- | ----------- | diff --git a/lang-Methods.md b/lang-Methods.md index 030bd84..b5f8ae0 100644 --- a/lang-Methods.md +++ b/lang-Methods.md @@ -1,5 +1,4 @@ -Method Definitions -================== +# Method Definitions @@ -43,8 +42,7 @@ All methods which are not `static` have an implicit `self` parameter which refers to this object, although if you wish to refer to a member of `self`, you do not need to reference it directly, as it is already implicitly in scope. -Method Argument List -==================== +# Method Argument List Method arguments must all have a name and type, and optionally the last arguments in the list may have a default value, (*Version 3.3.0 and newer*) @@ -86,8 +84,7 @@ Fn(5, 6, 7); Fn(7, 8, 9, 10); ``` -Method Definition Flags -======================= +# Method Definition Flags | Flag | Description | | ---- | ----------- | diff --git a/lang-Statements.md b/lang-Statements.md index 7ed7724..1c2a212 100644 --- a/lang-Statements.md +++ b/lang-Statements.md @@ -1,5 +1,4 @@ -Statements -========== +# Statements @@ -25,8 +24,7 @@ All functions are made up of a list of *statements* enclosed with left and right braces, which in and of itself is a statement called a *compound statement*, or *block*. -Compound Statements -=================== +# Compound Statements A compound statement is formed as: @@ -39,8 +37,7 @@ A compound statement is formed as: Note that the statement list is optional, so an empty compound statement `{}` is entirely valid. -Expression Statements -===================== +# Expression Statements An expression statement is the single most common type of statement in just about any programming language. In ZScript, exactly like C and C++, an @@ -64,8 +61,7 @@ m_MyCoolMember = 500; 5 * 5; // does nothing of course, but valid ``` -Conditional Statements -====================== +# Conditional Statements A conditional statement will, conditionally, choose a statement (or none) to execute. They work the same as in C and ACS: @@ -95,8 +91,7 @@ else e = f; ``` -Switch Statements -================= +# Switch Statements A switch statement takes an expression of integer or name type and selects a labeled statement to run. They work the same as in C and ACS: @@ -121,8 +116,7 @@ default: } ``` -Loop Statements -=============== +# Loop Statements ZScript has five loop statements, `for`, `while`, `until`, `do while` and `do until`. `for`, `while` and `do while` work the same as in C, C++ and ACS, while @@ -160,8 +154,7 @@ do until ( Expression ) ``` -Control Flow Statements -======================= +# Control Flow Statements As in C, there are three control flow statements that manipulate where the program will execute statements next, which are available contextually. They @@ -238,8 +231,7 @@ int, int ReturnsTwoInts() } ``` -Local Variable Statements -========================= +# Local Variable Statements Local variable statements are formed in one of 2 ways. The `let` keyword can be used to automatically determine the type of the variable from the initializer, @@ -259,8 +251,7 @@ let Identifier = Expression ; Type Variable $[ , Variable]$... ; ``` -Multi-assignment Statements -=========================== +# Multi-assignment Statements Expressions or functions that return multiple values can be assigned into multiple variables with the syntax: @@ -281,13 +272,11 @@ bool spawned; [spawned, mo] = A_SpawnItemEx("MyCoolActor"); ``` -Static Array Statements -======================= +# Static Array Statements Static arrays can be defined normally as a statement. -Null Statements -=============== +# Null Statements A null statement does nothing, and is formed `;`. It is similar to an empty compound statement. diff --git a/lang-Structures.md b/lang-Structures.md index d1caaf4..8545670 100644 --- a/lang-Structures.md +++ b/lang-Structures.md @@ -1,5 +1,4 @@ -Structure Definitions -===================== +# Structure Definitions @@ -46,8 +45,7 @@ struct MyCoolStructure } ``` -Structure Flags -=============== +# Structure Flags | Flag | Description | | ---- | ----------- | @@ -57,8 +55,7 @@ Structure Flags | `ui` | Structure has UI scope. | | `version ( "ver" )` | Restricted to ZScript version `ver` or higher. | -Structure Content -================= +# Structure Content Structure contents are an optional list of various things logically contained within the structure, including: diff --git a/lang-Types.md b/lang-Types.md index 17a7e6e..b715c33 100644 --- a/lang-Types.md +++ b/lang-Types.md @@ -1,5 +1,4 @@ -Types -===== +# Types @@ -36,8 +35,7 @@ Most basic types have methods attached to them, and both integer and floating-point type names have symbols accessible from them. See the API section for more information. -Integer Types -============= +# Integer Types Integer types are basic integral numbers. They include: @@ -72,8 +70,7 @@ for instance `int.Max`. Minimum value of type. -Floating-point Types -==================== +# Floating-point Types Floating-point types hold exponents, generally represented as regular decimal numbers. There are two such types available to ZScript: @@ -138,8 +135,7 @@ Floating-point types have symbols attached which can be accessed by Not-a-Number value of type. -Strings -======= +# Strings | Name | Usable as argument | | ---- | :----------------: | @@ -149,8 +145,7 @@ The `string` type is a mutable, garbage-collected string reference type. Strings are not structures or classes, however there are methods attached to the type, detailed in the API section. -Names -===== +# Names | Name | Usable as argument | | ---- | :----------------: | @@ -165,8 +160,7 @@ Names can be converted to `int` with an explicit cast, and the negative of `int(name())` may be used to create an integer representation of a string usable by action specials, most prominently `ACS_NamedExecute`. -Colors -====== +# Colors | Name | Usable as argument | | ---- | :----------------: | @@ -180,8 +174,7 @@ color(R, G, B) color(A, R, G, B) ``` -Vectors -======= +# Vectors | Name | Usable as argument | | ---- | :----------------: | @@ -196,8 +189,7 @@ as a `vector2` with `xy`. Vectors can use many operators and even have special ones to themselves. See the Expressions and Operators section for more information. -Fixed-size Arrays -================= +# Fixed-size Arrays | Name | Usable as argument | | ---- | :----------------: | @@ -212,8 +204,7 @@ or greater. Note that this kind of type can also be declared in variable names themselves. -Dynamic-size Arrays -=================== +# Dynamic-size Arrays | Name | Usable as argument | | ---- | :----------------: | @@ -239,8 +230,7 @@ Will result in an array with 5 elements. Dynamically sized arrays also cannot store other dynamically sized arrays, or user-defined `struct` objects. -Maps -==== +# Maps | Name | Usable as argument | | ---- | :----------------: | @@ -248,8 +238,7 @@ Maps Map types take the form `map`. They are not yet implemented. -Class Types -=========== +# Class Types | Name | Usable as argument | | ---- | :----------------: | @@ -261,8 +250,7 @@ object. They simply take the form `class`, and can be restrained to descendants of a type with the syntax `class`. Strings are implicitly cast to class type references. -User Types -========== +# User Types | Name | Usable as argument | | ---- | :----------------: | @@ -281,8 +269,7 @@ A type name that is within a specific scope can be accessed by prefixing it with a `.`. The type `.MyClass.MySubStructure` will resolve to the type `MySubStructure` contained within `MyClass`. -Read-only Types -=============== +# Read-only Types | Name | Usable as argument | | ---- | :----------------: | @@ -292,8 +279,7 @@ A read-only type, as its name implies, may only be read from, and is effectively immutable. They take the form `readonly`. Do note that this is separate from the member declaration flag. -Other Types -=========== +# Other Types | Name | Usable as argument | Description | | ---- | :----------------: | ----------- | @@ -308,8 +294,7 @@ Other Types Strings will implicitly convert to `sound` and `statelabel`. -Variable Name -============= +# Variable Name Variable names can have an array's size on them, instead of on the type, or none. Variable names are formed as either: @@ -319,8 +304,7 @@ Identifier Identifier Array-size ``` -Array Size -========== +# Array Size Array sizes can be multi-dimensional or automatically sized, so all of the following syntaxes are available: diff --git a/lang.md b/lang.md index 8b9ad55..6edd208 100644 --- a/lang.md +++ b/lang.md @@ -1,5 +1,4 @@ -Language -======== +# Language @@ -40,8 +39,7 @@ the hope that it is useful reference and serves as a solid basis for further writings. This document was originally written by Alison Sanderson (Marrub.) Attribution is encouraged but not required. -Reading This Document -===================== +# Reading This Document This document's syntaxes are written in a specific way to be easy to read but still close enough to a formal syntax that, for instance, someone writing a @@ -58,8 +56,7 @@ element spellings: | `$[` and `]$` | An optional syntax element, which may be omitted by the user. | | `"text"` | Any string literal, contents do not necessarily have to be what is inside unless explicitly stated. | -Translation Unit -================ +# Translation Unit Full ZScript files are referred to as "translation units." This terminology comes from the C standard, and refers simply to the entirety of a ZScript @@ -73,8 +70,7 @@ Included translation units may not have version directives. All keywords and identifiers in ZScript are case insensitive. -Versions -======== +# Versions A version directive may be placed at the very beginning of a ZScript file, the syntax being: @@ -88,8 +84,7 @@ Where `num` is the ZScript version to use. By default ZScript is version by this documentation and it is highly encouraged to always use the latest version of ZScript. The minimum version supported by this documentation is 3.0. -Top-level -========= +# Top-level A ZScript file can have one of several things at the top level of the file, following a version directive: @@ -101,8 +96,7 @@ following a version directive: - Include directives -Include directives -================== +# Include directives Include directives include other files to be processed by the ZScript compiler, allowing you to organize and separate code into different files. Their syntax @@ -127,12 +121,11 @@ Basic includes. #include "zscript/MyCoolMod/MyCoolClasses.zsc" ``` -Table of Contents -================= +# Table of Contents Finally, here is a table of contents for each language element: - + * [Classes](lang-Classes.md) * [Constants](lang-Constants.md) @@ -144,6 +137,6 @@ Finally, here is a table of contents for each language element: * [Structures](lang-Structures.md) * [Types](lang-Types.md) - + diff --git a/tools/tocgen.rb b/tools/tocgen.rb index a8b7a67..709bf2b 100644 --- a/tools/tocgen.rb +++ b/tools/tocgen.rb @@ -15,7 +15,8 @@ def filter_emit r end def find_toc_areas f - f.to_enum(:scan, /^()(?:.|\n)*?()/i).map{$~} + re = /^()(?:.|\n)*?()/i + f.to_enum(:scan, re).map{$~} end def filter_toc_areas f @@ -41,8 +42,16 @@ def rewrite fnam File.write fnam, o end -rewrite "api.md" do |f| filter_toc_areas f do |a| /api-#{a}-(\w+).md/ end end -rewrite "glossary.md" do |f| filter_toc_areas f do |a| /glossary-(\w+).md/ end end -rewrite "lang.md" do |f| filter_toc_areas f do |a| /lang-(\w+).md/ end end +rewrite "api.md" do |f| + filter_toc_areas f do |a| /api-#{a}-(\w+).md/ end +end + +rewrite "glossary.md" do |f| + filter_toc_areas f do |a| /glossary-(\w+).md/ end +end + +rewrite "lang.md" do |f| + filter_toc_areas f do |a| /lang-(\w+).md/ end +end ## EOF