nitasema  Check-in [48d289b8b2]

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:fix readme
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 48d289b8b20943f69fdb197ebcf4617ee85b05a9fde9eac1dadbe0e48d06f762
User & Date: lexi 2019-04-28 04:17:16
Context
2019-04-28
04:39
more markup fixes Leaf check-in: 0d977d116f user: lexi tags: trunk
04:17
fix readme check-in: 48d289b8b2 user: lexi tags: trunk
03:40
initial commit ← git check-in: 75008c4bb6 user: lexi tags: trunk
Changes

Changes to README.md.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

102
103

104
105
106
107
108
109
110
111
112
113
114

115
116
117
118

119
120
121
122
123
124
125
126
127
128

129
130
131

132
133
134
135
136
137
138
139
140
141
142
143
144

145
146

147
148
149
150
151
152
153
154
155

156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
# nitasema
nitasema strives to be a versatile interactive fiction generator. it takes a script file and produces a self-contained html file that can be played in a web brower. nitasema has minimal dependencies and is fast. the name is Swahili and means "I will speak."

## dependencies
* a C++11 compiler (default is `clang++`)
* libc
* libstdc++

## building
to build, run `./make.sh` from the root directory.

## file format
the nitasema *.n file format is based on simplified s-exps. it is designed primarily as an intermediate format for a forthcoming GUI editor but in the meantime it's perfectly intelligible to humans to and only slightly verbose.

lines can be commented out with the `;` character. there are currently no multiline comments.

whitespace is used to delimit values and is otherwise insignificant.

the data types are atoms, strings, and lists. strings are delimited by single-quotes (`'`) and can span any number of lines. lists are delimited by `[` and `]`. atoms may contain any character in the ascii range '-' ~ 'z' | 'A' ~ 'Z' and any unicode character outside the ascii range. backslash (`\`) can escape single quotes in a string.

the first term in the *.n file must be a string naming the story. it may be followed by atoms to mark various flags.

### flags
* `by`: sets the author. takes a string argument. currently has no effect on output. (`by 'alexis hale'`)
* `flags`: declares booleans. must be followed by a list of booleans. (`flags [bloodsoaked screaming bleeding]`)
* `vars`: declares variables. must be followed by a list of variables. (`vars [health sanity terror]`)
* `no-select`: disables text selection to make the story seem more app-like.
* `start`: indicates the starting passage. takes an atom argument. required. (`start the-beginning-of-the-end`)

### passages
a [passage name (stylesheet) ...] declaration creates a passage. the first term must be the id of the passage as an atom. optionally a stylesheet name may follow. all following terms must be nodes.

```
[passage the-beginning-of-the-end doom-passage]
```

creates a passage with the id `the-beginning-of-the-end` with stylesheet `doom-passage`. ids are used only in the front end of the compiler and do not appear in the compiled html.

```
[passage the-beginning-of-the-end
	'doom had at long last come to Las Vegas.'
]
```

creates a passage with the id `the-beginning-of-the-end` and adds a text node. all macro nodes regardless of position are evaluated before the passage renders, though macros in conditionals will only be evaluated if the conditional evaluates correctly.

```
[passage the-beginning-of-the-end
	[p 'doom had at long last come to Las Vegas.']
	[p 'soon the mushrooms clouds of thermonuclear armageddon would envelop the globe.']
]
```

instead of creating text nodes, this example creates paragraph nodes. paragraph nodes are a better way to organize text.

to link to another passage, use the `[link id 'title']` node.

```
[passage the-beginning-of-the-end
	[p 'doom had at long last come to Las Vegas.']
	[p 'soon the mushroom clouds of ' [link doooom 'thermonuclear armageddon'] ' would envelop the globe.']
]
```

to create a link to another passage that can only be clicked once (and will afterwards disappear forever), use `action`

```
[passage the-beginning-of-the-end
	[p 'doom had at long last come to Las Vegas.']
	[p 'soon the mushrooms clouds of thermonuclear armageddon would envelop the globe.']
	[p [action make-tea 'make tea.']]
]
```

to set a flag, use the `[set flag]` and `[clear flag]`.

```
[passage doooom
	[set world-destroyed]
	[clear hankering-for-brunch]
	[p 'welp looks like everyone\'s dead now. i hope you learned a'
	   'valuable lesson on the futility of existence.']
]
```

to test a flag, use the `[flag? flag [#t-pred] ([#f-pred])]` node. #f-preds (else clauses) are optional.

```
[passage tea-with-aunt-holly
	[flag? world-destroyed [
		[p 'unfortunately, the world where both all tea in the universe and'
		   'aunt holly were located has been destroyed in thermonuclear'
		   'armageddon.']
		[p 'better luck next time, sport!']
	][
		[clear hankering-for-brunch]
		[p 'you enjoy a lovely evening sipping tea with aunt holly.']
		[p 'you have been cured of <b>HANKERING FOR BRUNCH</b>!']
	]]
]
```

a link can invoke a passage as a subroutine.
```

[passage bed
	[p 'you are in bed.']
	[sub inventory 'inventory']]
[passage bridge
	[p 'you are on the bridge of the Unrelenting Fist of Endless Imperial Wrath.']
	[p 'crew bustle about, trying to make a good impression for your inspection.']
	[sub inventory 'inventory']]
[passage inventory
	[p 'you have <b>HALF-EATEN FISH HEAD</b>, <b>HORRIFIC STENCH</b>, and <b>REGRETS</b>.']
	[p [ret 'back']]]
```

an action can also invoke a subroutine, with the `sub-action` node. its syntax is identical to `action`.

to make nodes appear only once, and not on subsequent views, use `once`
```

[passage start
	[once [[p 'you wake up and immediately wish you hadn\'t, wish you\'d never wake up again.']]]
	[p 'you are in your office.']
	[p 'the papers that need grading are still here.']
	[once [
		[p 'you pick one up, wondering if they could possibly be as bad as you remembered.']
		[p 'they\'re not. they\'re worse.']
	]]
]
```

to create an event that will interrupt the story only on the first click of a link, use `gate`.

```

[passage home
	[p 'you are home with a nice cup of tea.']
	[p [gate fight-monster outside 'go outside.']]
]
[passage outside
	[p 'you admire the splendour of the great outdoors.']
]
[passage fight-monster
	[p 'a dreadful beast covered in the intestines of its victims bursts from the sewers!']
	[p [ret 'kill monster with umbrella.']]
]
```


`once` takes two lists of nodes, the second optional. the second will be displayed on any subsequent visits.
```

[passage offal-gardens
	[once [
		[p 'it is said the offal gardens of betelgeuse must be seen to be believed.']
		[p 'well, they\'re not wrong.']
	][
		[p 'the offal gardens stretch away into the distance. you wish they didn\'t.']
	]]
]
```

## colors

colors may be set by the "colors" declaration. this overrides the default stylesheet.

```
colors [
	bg '#121212'
]
```

the colors that may be changed are `bg`, `fg`, `shadow`, `link`, `hover`, and `shadow-hover`. any valid CSS color specification may be used. `url()` can also be used to set a background image:

```
colors [
	bg 'url(bg.png)'
]
```

## stylesheets

the default stylesheet is set by the `colors` declaration. different passages may have different stylesheets. stylesheets are declared as follows:

```
[style name
	[global-rule 'expression']
	[.link
		[local-rule 'expression']
	]
]
```

"rules" are simply css rules. `[rule 'expression']` is translated to `rule: expression;` at compile time.

anything in the global scope affects the entire passage. to set the background to slowly turn black on passages tagged "doom":

```
[style doom
	[background 'black']
	[transition '10s']
]
```

to style links, use the `.link` selector. to style text, use the `.text` selector.

to suppress the default stylesheet completely, use the `no-style` declaration.

## invocation
```
./nitasema input-file.n > output-file.html
```

the html file can be opened by any browser.

## issues
* code needs major refactoring
* i wrote the entire thing in a 12-hour bout of insanity and was up until 8am working on it, so there's bound to be lots wrong.

## todo
* fully implement all node types
* implement other types of variable assignment besides =
* show line number & context on compile errors, not just parse errors
* add multiline comments
* change colors, stylesheet
* tags
* title screens
* gui??
* enable determining whether a passage was invoked as a subroutine

nitasema is developed by alexis summer hale and released under the GPLv3 license.




|




|


|





|

|









|

<
|
<



<
|
|
|
<



<
|
|
|
|
<





<
|
|
|
|
<



<
|
|
|
|
|
<



<
|
|
|
|
|
|
<



<
|
|
|
|
|
|
|
|
|
|
|
|
<
>

<
>
|
|
|
|
|
|
|
|
|
|
<
>



<
>
|
|
|
|
|
|
|
|
|
<
>


<
>
|
|
|
|
|
|
|
|
|
|
|
<
|
>

<
>
|
|
|
|
|
|
|
|
<
>




<
|
|
|
<



<
|
|
|
<





<
|
|
|
|
|
|
<





<
|
|
|
|
<






|
|
|





|












|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

33

34
35
36

37
38
39

40
41
42

43
44
45
46

47
48
49
50
51

52
53
54
55

56
57
58

59
60
61
62
63

64
65
66

67
68
69
70
71
72

73
74
75

76
77
78
79
80
81
82
83
84
85
86
87

88
89

90
91
92
93
94
95
96
97
98
99
100

101
102
103
104

105
106
107
108
109
110
111
112
113
114

115
116
117

118
119
120
121
122
123
124
125
126
127
128
129

130
131
132

133
134
135
136
137
138
139
140
141

142
143
144
145
146

147
148
149

150
151
152

153
154
155

156
157
158
159
160

161
162
163
164
165
166

167
168
169
170
171

172
173
174
175

176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
# nitasema
nitasema strives to be a versatile interactive fiction generator. it takes a script file and produces a self-contained html file that can be played in a web brower. nitasema has minimal dependencies and is fast. the name is Swahili and means "I will speak."

## dependencies
* a C++11 compiler (default is `c++`)
* libc
* libstdc++

## building
to build, run `make rel`, `make dbg`, or `./make.sh` from the root directory. the only difference between the `rel` and `dbg` targets is that `dbg` includes debugging symbols and doesn't strip the resulting binary. `./make.sh` is the same as running `rel`, provided for systems without make installed.

## file format
the nitasema \*.n file format is based on simplified s-exps. it is designed primarily as an intermediate format for a forthcoming GUI editor but in the meantime it's perfectly intelligible to humans to and only slightly verbose.

lines can be commented out with the `;` character. there are currently no multiline comments.

whitespace is used to delimit values and is otherwise insignificant.

the data types are atoms, strings, and lists. strings are delimited by single-quotes (`'`) and can span any number of lines. lists are delimited by `[` and `]` (not the more usual parentheses, for ease of typing). atoms may contain any character in the ascii range '-' ~ 'z' | 'A' ~ 'Z' and any unicode character outside the ascii range. backslash (`\\`) can escape single quotes in a string.

the first term in the \*.n file must be a string naming the story. it may be followed by atoms to mark various flags.

### flags
* `by`: sets the author. takes a string argument. currently has no effect on output. (`by 'alexis hale'`)
* `flags`: declares booleans. must be followed by a list of booleans. (`flags [bloodsoaked screaming bleeding]`)
* `vars`: declares variables. must be followed by a list of variables. (`vars [health sanity terror]`)
* `no-select`: disables text selection to make the story seem more app-like.
* `start`: indicates the starting passage. takes an atom argument. required. (`start the-beginning-of-the-end`)

### passages
a `[passage name (stylesheet) ...]` declaration creates a *passage.* a passage is a screenful of nodes; passages are rendered and displayed to the player once at a time and users can navigate from passage to passage with links. the first term must be the id of the passage as an atom. optionally a stylesheet name may follow. all following terms must be nodes.


    [passage the-beginning-of-the-end doom-passage]


creates a passage with the id `the-beginning-of-the-end` with stylesheet `doom-passage`. ids are used only in the front end of the compiler and do not appear in the compiled html.


    [passage the-beginning-of-the-end
    	'doom had at long last come to Las Vegas.'
    ]


creates a passage with the id `the-beginning-of-the-end` and adds a text node. all macro nodes regardless of position are evaluated before the passage renders, though macros in conditionals will only be evaluated if the conditional evaluates correctly.


    [passage the-beginning-of-the-end
    	[p 'doom had at long last come to Las Vegas.']
    	[p 'soon the mushrooms clouds of thermonuclear armageddon would envelop the globe.']
    ]


instead of creating text nodes, this example creates paragraph nodes. paragraph nodes are a better way to organize text.

to link to another passage, use the `[link id 'title']` node.


    [passage the-beginning-of-the-end
    	[p 'doom had at long last come to Las Vegas.']
    	[p 'soon the mushroom clouds of ' [link doooom 'thermonuclear armageddon'] ' would envelop the globe.']
    ]


to create a link to another passage that can only be clicked once (and will afterwards disappear forever), use `action`


    [passage the-beginning-of-the-end
    	[p 'doom had at long last come to Las Vegas.']
    	[p 'soon the mushrooms clouds of thermonuclear armageddon would envelop the globe.']
    	[p [action make-tea 'make tea.']]
    ]


to set a flag, use the `[set flag]` and `[clear flag]`.


    [passage doooom
    	[set world-destroyed]
    	[clear hankering-for-brunch]
    	[p 'welp looks like everyone\'s dead now. i hope you learned a'
    	   'valuable lesson on the futility of existence.']
    ]


to test a flag, use the `[flag? flag [#t-pred] ([#f-pred])]` node. #f-preds (else clauses) are optional.


    [passage tea-with-aunt-holly
    	[flag? world-destroyed [
    		[p 'unfortunately, the world where both all tea in the universe and'
    		   'aunt holly were located has been destroyed in thermonuclear'
    		   'armageddon.']
    		[p 'better luck next time, sport!']
    	][
    		[clear hankering-for-brunch]
    		[p 'you enjoy a lovely evening sipping tea with aunt holly.']
    		[p 'you have been cured of <b>HANKERING FOR BRUNCH</b>!']
    	]]
    ]


a link can invoke a passage as a subroutine.


    [passage bed
    	[p 'you are in bed.']
    	[sub inventory 'inventory']]
    [passage bridge
    	[p 'you are on the bridge of the Unrelenting Fist of Endless Imperial Wrath.']
    	[p 'crew bustle about, trying to make a good impression for your inspection.']
    	[sub inventory 'inventory']]
    [passage inventory
    	[p 'you have <b>HALF-EATEN FISH HEAD</b>, <b>HORRIFIC STENCH</b>, and <b>REGRETS</b>.']
    	[p [ret 'back']]]


an action can also invoke a subroutine, with the `sub-action` node. its syntax is identical to `action`.

to make nodes appear only once, and not on subsequent views, use `once`

    
    [passage start
    	[once [[p 'you wake up and immediately wish you hadn\'t, wish you\'d never wake up again.']]]
    	[p 'you are in your office.']
    	[p 'the papers that need grading are still here.']
    	[once [
    		[p 'you pick one up, wondering if they could possibly be as bad as you remembered.']
    		[p 'they\'re not. they\'re worse.']
    	]]
    ]

    
to create an event that will interrupt the story only on the first click of a link, use `gate`.


    
    [passage home
    	[p 'you are home with a nice cup of tea.']
    	[p [gate fight-monster outside 'go outside.']]
    ]
    [passage outside
    	[p 'you admire the splendour of the great outdoors.']
    ]
    [passage fight-monster
    	[p 'a dreadful beast covered in the intestines of its victims bursts from the sewers!']
    	[p [ret 'kill monster with umbrella.']]
    ]

    

`once` takes two lists of nodes, the second optional. the second will be displayed on any subsequent visits.

    
    [passage offal-gardens
    	[once [
    		[p 'it is said the offal gardens of betelgeuse must be seen to be believed.']
    		[p 'well, they\'re not wrong.']
    	][
    		[p 'the offal gardens stretch away into the distance. you wish they didn\'t.']
    	]]
    ]

    
## colors

colors may be set by the "colors" declaration. this overrides the default stylesheet.


    colors [
    	bg '#121212'
    ]


the colors that may be changed are `bg`, `fg`, `shadow`, `link`, `hover`, and `shadow-hover`. any valid CSS color specification may be used. `url()` can also be used to set a background image:


    colors [
    	bg 'url(bg.png)'
    ]


## stylesheets

the default stylesheet is set by the `colors` declaration. different passages may have different stylesheets. stylesheets are declared as follows:


    [style name
    	[global-rule 'expression']
    	[.link
    		[local-rule 'expression']
    	]
    ]


"rules" are simply css rules. `[rule 'expression']` is translated to `rule: expression;` at compile time.

anything in the global scope affects the entire passage. to set the background to slowly turn black on passages tagged "doom":


    [style doom
    	[background 'black']
    	[transition '10s']
    ]


to style links, use the `.link` selector. to style text, use the `.text` selector.

to suppress the default stylesheet completely, use the `no-style` declaration.

## invocation
nitasema takes a filename on the commandline and prints its output to `stdout`.

    ./nitasema input-file.n > output-file.html

the html file can be opened by any browser.

## issues
* code needs major refactoring
* i wrote the entire thing in a 12-hour-long fugue and was up until 8am working on it, so there's bound to be lots wrong.

## todo
* fully implement all node types
* implement other types of variable assignment besides =
* show line number & context on compile errors, not just parse errors
* add multiline comments
* change colors, stylesheet
* tags
* title screens
* gui??
* enable determining whether a passage was invoked as a subroutine

nitasema is developed by lexi hale and released under the AGPL license. (see LICENSE)