Skip to content

Latest commit

 

History

History
84 lines (67 loc) · 3.51 KB

lua-primer.md

File metadata and controls

84 lines (67 loc) · 3.51 KB

Lua Primer

While the Lua reference manual is indispensable, here are the most important parts of Lua you'll need to get started. This is meant to give a very brief overview and let you know where in the manual to look for further details, not to teach Lua.

Important functions

  • tonumber: converts its string argument to a number; takes optional base
  • tostring: converts its argument to a string
  • print: prints tostring of all its arguments separated by tab characters
  • type: returns a string describing the type of its argument
  • pcall: calls a function in protected mode so errors are not fatal
  • error: halts execution and break to the nearest pcall
  • assert: raises an error if a condition is nil or false
  • ipairs: iterates over sequential tables
  • pairs: iterates over any table, sequential or not, in undefined order
  • unpack: turns a sequential table into multiple values
  • require: loads and returns a given module

Note that tostring on tables will give unsatisfactory results; you will want to use fennelview or another pretty-printer for debugging and development.

Important modules

You can explore a module with (each [k v (pairs math)] (print k v)) in the repl to see all the functions and values it contains.

  • math: all your standard math things including trig and random
  • table: concat, insert, remove, and sort are the main things
  • string: all common string operations (except split which is absent)
  • io: mostly filesystem functions (directory listing is notably absent)
  • os: operating system functions like exit, time, getenv, etc

In particular table.insert and table.remove are intended for sequential tables; they will shift over the indices of every element after the specified index. To remove something from a non-sequential table simply set the field to nil.

Note that Lua does not implement regular expressions but its own more limited pattern language for string.find, string.match, etc.

Advanced

  • getfenv/setfenv: access to first-class function environments in Lua 5.1; in 5.2 onward use the _ENV table instead
  • getmetatable/setmetatable: metatables allow you to override the behavior of tables in flexible ways with functions of your choice
  • coroutine: the coroutine module allows you to do flexible control transfer in a first-class way
  • package: this module tracks and controls the loading of modules
  • arg: table of command-line arguments passed to the process
  • ...: arguments passed to the current function; acts as multiple values
  • select: most commonly used with ... to find the number of arguments
  • xpcall: acts like pcall but accepts a handler; used to get a full stack trace rather than a single line number for errors

Lua loading

These are used for loading Lua code. The load* functions return a "chunk" function which must be called before the code gets run, but dofile executes immediately.

  • dofile
  • load
  • loadfile
  • loadstring

Obscure

  • _G: a table of all globals
  • _VERSION: the current version of Lua being used as a string
  • collectgarbage: you hopefully will never need this
  • debug: see the Lua manual for this module
  • next: needed for implementing your own iterators
  • rawequal/rawget/rawlen/rawset: operations which bypass metatables