Skip to content

Latest commit

 

History

History
171 lines (117 loc) · 7.22 KB

libmewa.md

File metadata and controls

171 lines (117 loc) · 7.22 KB
Raw

Mewa API

The Mewa module imported with require "mewa" has the following functions.

Table of Contents

  1. mewa.compiler ~ Create a Compiler Object
  2. mewa.typedb ~ Create a Type Database Object
  3. mewa.tostring ~ Serialization for Debugging Purposes
  4. mewa.version ~ Get the current Mewa version
  5. mewa.stacktrace ~ An Alternative to debug.traceback
  6. mewa.llvm_float_tohex ~ Display of 32bit floating point numbers for output to LLVM IR
  7. mewa.llvm_double_tohex ~ Display of 64bit floating point numbers (double) for output to LLVM IR

Create a compiler object

mewa = require("mewa")
compiler = mewa.compiler( compilerdef)

compilerdef is the structure created from the grammar definition by the mewa program.

Run the Compiler

The compiler has one method run that takes up to 5 arguments from which two are optional:

compiler:run( targetfile, options, inputfile, outputfile, dbgout)

targetfile specifies the path to the file that is the template used for a specific target where {Code} and {Source} are substituted by the output printed and the name of the source file. options specifies some options defined by the command line parser inputfile specifies the path to the file to compile. outputfile specifies the path to the file to write the compiler output to. If not specified the output is written to stdandard output. dbgout specifies the path to the file to write the compiler debug output to. The debug output logs the actions of the compiler and may be helpful during the early stages of development.

Note

The compiler that is called from the script generated from the grammar description by the mewa program.

Create a Type Database Object

mewa = require("mewa")
typedb = mewa.typedb()

The Type Database API

A type database object provides some functions to build the type system of your compiler. A documentation can be found here.

Serialization for debugging purposes

mewa.tostring

Parameter

# Name Type Description
1st obj any type object to dump the contents from
2nd maxdepth integer Maximum depth of the tree to print (used to handle cirular references in the table)
3rd indent boolean (optional) true if to use indentiation, false if not, Default is false.
Return string The serialized contents of the object passed as string

Remark

The serialization is not complete. Serialization is done only for raw tables, numbers and strings. It just does the job suitable for Mewa.

Version of Mewa

mewa.version

Get the 3 parts of the version of Mewa.

Parameter

# Name Type Description
Return 1st integer Major version of Mewa.
Return 2nd integer Minor version of Mewa.
Return 3rd integer Patch version of Mewa.

An Alternative to debug.traceback

mewa.stacktrace

Parameter

# Name Type Description
1st depth integer (optional) number of steps to trace back. Default is no limit.
2nd ignore array of strings (optional) List of substrings of functions ignored (*), Default is empty.
Return table Array of stack trace elements

Stack Trace Element Structure

A stack trace element of the list returned is a table containing the following elements:

Name Type Description
line integer Line number of the function header in the Lua script source
file string Path of the Lua script
function string Name of the function

Remark (*)

If the ignore list contains for example the elements {"traverse", "error"} then all stack trace elements referring to functions with names either containing a substring "traverse" or are containing a substring "error" are ignored and not part of the result. Remind that substrings are not regular expression matches but simple contains substring matches.

Remark

The stack trace function has been written for compilers written with Mewa. It has its limitations that makes it not suitable for other purposes.

Display of 32bit floating point numbers (float) for output to LLVM IR

This is a helper function to convert a floating point number to its hexadecimal representation accepted in all cases by LLVM. The following code leads to an error:

	store float 4.21, float* %r1

while

	store float 4.25, float* %r1

is accepted. The representation as hexadecimal code is allways accepted by LLVM:

	store float 0x4010D70A40000000, float* %r1

To get the hexadecimal code for a 32 bit floating point number you have to call:

	hexcode = "0x" .. llvm_float_tohex( 4.21)

and you get

	hexcode = "0x4010D70A40000000"

Note

This function does not belong here but should be part of a separate lua library for handling LLVM IR issues. IMHO: It should be possible in LLVM IR to configure how floating point numbers are rounded and as consequence it should be possible to use floating point constants in the LLVM IR output.

Display of 64bit floating point numbers (double) for output to LLVM IR

This does the same as mewa.llvm_float_tohex, but returns the representation of a 64 bit double precision floating point number.

	hexcode = "0x" .. llvm_double_tohex( 4.212121212121)

and you get

	hexcode = "0x4010D9364D9363EA"

Note

This function does not belong here but should be part of a separate lua library for handling LLVM IR issues. IMHO: It should be possible in LLVM IR to configure how floating point numbers are rounded and as consequence it should be possible to use floating point constants in the LLVM IR output.