marrub
/
zscript-doc
mirror of https://github.com/marrub--/zscript-doc
1
0
Fork 0
Code Releases Activity

change header styles

pull/1/head
an 2019-04-02 11:28:16 -04:00
parent 0634ea76af
commit 31552790d1
14 changed files with 118 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
README.md
View File

@ -1,5 +1,4 @@
ZScriptDoc
==========
# ZScriptDoc
This is documentation for the ZScript language. CC0 public domain. See
[LICENSE](LICENSE.txt) for more information.

57
api.md
View File

@ -1,8 +1,11 @@
# API
<!-- vim-markdown-toc GFM -->
* [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)
<!-- vim-markdown-toc -->
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
<!-- toc actor -->
<!-- inter-toc actor -->
* [State](api-actor-State.md)
<!-- toc end -->
<!-- end -->
TODO
# Base
<!-- toc base -->
<!-- inter-toc 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)
<!-- toc end -->
<!-- end -->
TODO
# Drawing
<!-- toc drawing -->
<!-- inter-toc 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)
<!-- toc end -->
<!-- end -->
TODO
# Event Handling
<!-- toc events -->
<!-- inter-toc events -->
<!-- toc end -->
<!-- end -->
TODO
# Files
<!-- toc files -->
<!-- inter-toc files -->
* [Wads](api-files-Wads.md)
<!-- toc end -->
<!-- end -->
TODO
# Intermission Screens
<!-- toc inter -->
<!-- inter-toc inter -->
* [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)
<!-- toc end -->
<!-- end -->
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
<!-- toc level -->
<!-- inter-toc level -->
* [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)
<!-- toc end -->
<!-- end -->
TODO
# Players
<!-- toc player -->
<!-- inter-toc player -->
* [PlayerClass](api-player-PlayerClass.md)
* [PlayerSkin](api-player-PlayerSkin.md)
* [Team](api-player-Team.md)
<!-- toc end -->
<!-- end -->
TODO
# Sounds
<!-- toc sound -->
<!-- inter-toc sound -->
* [SeqNode](api-sound-SeqNode.md)
<!-- toc end -->
<!-- end -->
TODO
# Weapons
<!-- toc wep -->
<!-- inter-toc wep -->
* [PSprite](api-wep-PSprite.md)
<!-- toc end -->
<!-- end -->
TODO
# Global Objects
<!-- toc global-data -->
<!-- inter-toc global-data -->
* [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)
<!-- toc end -->
<!-- end -->
These variables are accessible in any context and are not bound by any specific
object. Generally these mirror global information within the engine itself.
<!-- toc global-func -->
<!-- inter-toc global-func -->
* [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)
<!-- toc end -->
<!-- end -->
These functions are accessible in any context and are not bound by any specific
object. Generally these are utility functions.
<!-- toc global -->
<!-- inter-toc global -->
* [DEHInfo](api-global-DEHInfo.md)
* [FOptionMenuSettings](api-global-FOptionMenuSettings.md)
* [GameInfoStruct](api-global-GameInfoStruct.md)
* [LevelLocals](api-global-LevelLocals.md)
<!-- toc end -->
<!-- end -->
These are the types used by global variables.

39
entry.md
View File

@ -1,5 +1,4 @@
Entry Points
============
# Entry Points
<!-- vim-markdown-toc GFM -->
@ -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.

9
glossary.md
View File

@ -1,16 +1,15 @@
Glossary
========
# Glossary
<!-- toc glossary -->
<!-- inter-toc -->
* [Classes](glossary-Classes.md)
* [Concepts](glossary-Concepts.md)
* [Structures](glossary-Structures.md)
* [Versions](glossary-Versions.md)
<!-- toc end -->
<!-- end -->
Miscallaneous information about ZScript, including code examples and version
Miscallaneous information about ZScript, including class lists and version
differences.
<!-- EOF -->

21
lang-Classes.md
View File

@ -1,5 +1,4 @@
Class Definitions
=================
# Class Definitions
<!-- vim-markdown-toc GFM -->
@ -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

6
lang-Constants.md
View File

@ -1,5 +1,4 @@
Constant Definitions
====================
# Constant Definitions
<!-- vim-markdown-toc GFM -->
@ -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:

9
lang-Expressions.md
View File

@ -1,5 +1,4 @@
Expressions and Operators
=========================
# Expressions and Operators
<!-- vim-markdown-toc GFM -->
@ -23,8 +22,7 @@ Expressions and Operators
<!-- vim-markdown-toc -->
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.

6
lang-Members.md
View File

@ -1,5 +1,4 @@
Member Declarations
===================
# Member Declarations
<!-- vim-markdown-toc GFM -->
@ -30,8 +29,7 @@ private int m_CoolPrivateInt;
protected meta int m_CoolMetaInt;
```
Member Declaration Flags
========================
# Member Declaration Flags
| Flag | Description |
| ---- | ----------- |

9
lang-Methods.md
View File

@ -1,5 +1,4 @@
Method Definitions
==================
# Method Definitions
<!-- vim-markdown-toc GFM -->
@ -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 |
| ---- | ----------- |

33
lang-Statements.md
View File

@ -1,5 +1,4 @@
Statements
==========
# Statements
<!-- vim-markdown-toc GFM -->
@ -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.

9
lang-Structures.md
View File

@ -1,5 +1,4 @@
Structure Definitions
=====================
# Structure Definitions
<!-- vim-markdown-toc GFM -->
@ -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:

48
lang-Types.md
View File

@ -1,5 +1,4 @@
Types
=====
# Types
<!-- vim-markdown-toc GFM -->
@ -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<Type, Type>`. 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<Type>`. 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<Type>`. 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:

25
lang.md
View File

@ -1,5 +1,4 @@
Language
========
# Language
<!-- vim-markdown-toc GFM -->
@ -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:
<!-- toc glossary -->
<!-- inter-toc -->
* [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)
<!-- toc end -->
<!-- end -->
<!-- EOF -->

17
tools/tocgen.rb
View File

@ -15,7 +15,8 @@ def filter_emit r
end
def find_toc_areas f
f.to_enum(:scan, /^(<!-- toc (.+) -->)(?:.|\n)*?(<!-- toc end -->)/i).map{$~}
re = /^(<!-- inter-toc ([^\s]+)\s+-->)(?:.|\n)*?(<!-- end -->)/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