Debug

You will make mistakes. Here we will discuss the types of errors you will encounter and how to read the error output.

Types of errors

The types of error you will encounter are:

Failure to load the initial script
Failure to compile some template file
Failure to load a lua module
- Whether Lua code or a compiled template file
An error during evaluation of the Lua code

How to Read Errors

We will revisit the specifics of this error later, but for now, let's cover some general information on reading the error.

resolved script_fpath: '/home/runner/work/htt/htt/docs/examples/debug/run-err-stx.lua'
resolved htt_root: '/home/runner/work/htt/htt/docs/examples/debug'

Error loading Lua module '//err-stx.htt':
	err-stx.out.lua:8: 'then' expected near 'end'
stack traceback:
	[HTT Library]:532: in function <[HTT Library]:490>
	[C]: in function 'require'
	.../runner/work/htt/htt/docs/examples/debug/run-err-stx.lua:1: in main chunk
	[C]: in function 'xpcall'
	[HTT Library]:138: in function <[HTT Library]:120>

Resolved script fpath/htt root

script_fpath refers to the script file you used as a starting-point when calling HTT, see script file for details.

htt_root refers to the parent directory of the script file. This is the starting-point which is used when importing additional Lua modules or HTT template files, see HTT root for details.

References to [HTT Library]

Many lua functions in HTT are provided in addition to the Lua standard API. [HTT Library]:<number> refers to a line within the ./src/prelude.lua, which holds the definitions for this expanded standard library.

How to read the stack trace

The stack trace is read from bottom (outermost) to top (innermost), meaning the error originated at the line mentioned at the first like after stack traceback:.

In this case, that is in the bundled library code ([[HTT Library]]), line 432. In the copy of HTT used, this line marks the start of the loader function which HTT installs to intercept calls to require "//<path/to/template>.htt, which compile HTT templates into lua modules before loading them in as usual.

Error Compiling HTT Template

Compile errors happen when a HTT file cannot be compiled to a Lua module because there is a syntax- or semantic error, which the compiler detected.

Here's a trivial example. Content (output) cannot appear outside of a component, so the first line causes a compile error:

This line causes a compile failure
% 
% local x = false
% if x then
% end
%

These errors should be the easiest to follow. They point out the file, line- and column number. In case you want to know more, it also prints which parse state the compiler was in when encountering the error:

resolved script_fpath: '/home/runner/work/htt/htt/docs/examples/debug/run-err-compile.lua'
resolved htt_root: '/home/runner/work/htt/htt/docs/examples/debug'

Error compiling HTT template '//err-compile.htt'
	File: 'err-compile.htt'
	Line: 1
	Column: 0
	Type: illegal_toplevel_content
	Reason: content must be inside a component
stack traceback:
	[HTT Library]:524: in function <[HTT Library]:490>
	[C]: in function 'require'
	...ner/work/htt/htt/docs/examples/debug/run-err-compile.lua:1: in main chunk
	[C]: in function 'xpcall'
	[HTT Library]:138: in function <[HTT Library]:120>

Error loading Lua module

The initial script is loaded in a special way. For all other modules, whether written in plain Lua or compiled from HTT templates, Error loading Lua module means the module contains code which is not valid Lua.

In this case, we wrote if x, not if x then as is required:

% <one>
% local x = false
% if x
% end
% </one>

And here is the resulting error:

resolved script_fpath: '/home/runner/work/htt/htt/docs/examples/debug/run-err-stx.lua'
resolved htt_root: '/home/runner/work/htt/htt/docs/examples/debug'

Error loading Lua module '//err-stx.htt':
	err-stx.out.lua:8: 'then' expected near 'end'
stack traceback:
	[HTT Library]:532: in function <[HTT Library]:490>
	[C]: in function 'require'
	.../runner/work/htt/htt/docs/examples/debug/run-err-stx.lua:1: in main chunk
	[C]: in function 'xpcall'
	[HTT Library]:138: in function <[HTT Library]:120>

The stack trace is uninteresting in this case. We see the issue stems from a require on line 1 of the start.lua file, which is the intial script we passed to htt.

However, note the error, Error loading Lua module, and also note the name of the module, //err-stx.htt, which is a HTT template. For HTT templates, the module name reflects the path with // being the start of the path, relative to the HTT root directory.

The second thing to note is the actual error from Lua, err-stx.out.lua:7, the result of compiling err-stx.htt to Lua is saved in err-stx.out.lua, and the error in the Lua code is on line 7.

In this case, the actual error message from Lua, 'then' expected near 'end' is easy to follow. Other times, opening the compiled output is needed. Don't worry, the compiled output is written to be easy to follow.

Reading the compiled HTT templates

Every HTT template file is compiled, and the resulting Lua module is saved on disk. The result of compiling foo.htt is saved as foo.out.lua in the same directory.

The compiled output should make for easy reading, and sometimes a difficult to understand error becomes obvious when you read the relevant line in the compiled output.

Error during execution

Template code can cause errors. If an error happens, you can determine where by examining the stack.

In this example, we have two components, parent and child, both defined in //examples/debug/err-exec.htt. The parent calls child which causes a runtime error.

% <parent>
% local x = false
% if x then
% end
Call child {{@ child {} }}
% </parent>

% <child>
% error("I am raising an error")
% </child>

Note in output that we see the error itself, and before that, we can see the call-stack for components, //examples/debug/err-exec.htt.parent is the parent component, and the stack shows how it calls //examples/debug/err-exec.htt.child (child).

resolved script_fpath: '/home/runner/work/htt/htt/docs/examples/debug/run-err-exec.lua'
resolved htt_root: '/home/runner/work/htt/htt/docs/examples/debug'

Error during execution:
	err-exec.out.lua:6: I am raising an error
stack traceback:
	err-exec.out.lua:6: in function 
	(...tail calls...)
	[HTT Library]:475: in field 'render'
	err-exec.out.lua:17: in function 
	(...tail calls...)
	[HTT Library]:475: in local 'render_'
	[HTT Library]:486: in field 'render'
	[HTT Loader]:19: in function 'render'
	...runner/work/htt/htt/docs/examples/debug/run-err-exec.lua:2: in main chunk
	[C]: in function 'xpcall'
	[HTT Library]:138: in function <[HTT Library]:120>

HTT Documentation