hammerspoon Documentation

Technical Documentation: Hammerspoon/hammerspoon

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Hammerspoon

Discord: Click to join

What is Hammerspoon? Copy Chapter

This is a tool for powerful automation of OS X. At its core, Hammerspoon is just a bridge between the operating system and a Lua scripting engine.

What gives Hammerspoon its power is a set of extensions that expose specific pieces of system functionality, to the user. With these, you can write Lua scripts to control many aspects of your OS X environment.

How do I install it? Copy Chapter

Manually Copy Section

• Download the latest release
• Drag Hammerspoon.app from your Downloads folder to Applications

Homebrew Copy Section

• brew install hammerspoon --cask

What next? Copy Chapter

Out of the box, Hammerspoon does nothing - you will need to create ~/.hammerspoon/init.lua and fill it with useful code. There are several resources which can help you:

• Getting Started Guide
• API docs
• FAQ
• Sample Configurations supplied by various users
• Contribution Guide for developers looking to get involved
• An IRC channel for general chat/support/development (#hammerspoon on Libera)
• Google Group for support

What is the history of the project? Copy Chapter

Hammerspoon is a fork of Mjolnir. Mjolnir aims to be a very minimal application, with its extensions hosted externally and managed using a Lua package manager. We wanted to provide a more integrated experience.

What is the future of the project? Copy Chapter

Our intentions for Hammerspoon broadly fall into these categories:

• Ever wider coverage of system APIs in Extensions
• Tighter integration between extensions
• Smoother user experience

Overview (`Pods/ASCIImage/README.md`) Copy Section

ASCIImage

Create UIImage / NSImage instances from NSString, by combining ASCII art and Kindergarten skills.

Useful links Copy Chapter

• ASCIImage reference site: asciimage.org
• Original blog post presenting ASCIImage: Replacing Photoshop with NSString
• Slides from the presentation of ASCIImage at NSConference 7: ASCCImage slides and editor
• ASCIImage Super Studio: source on Github
• For ASCII art lovers: MonoDraw (not affiliated with ASCIImage; just an awesome app that I like)

FAQs Copy Chapter

Why ASCIImage?

The original blog post explains the genesis of ASCIImage, but it might still be confusing why anybody would use it, and for what purpose. Its main strength is that it combines two things: (1) having the image directly in code, and (2) seeing the image. The code is the image, the image is the code. It really only works like this for simple images composed of a few lines and / or simple shapes. Anything more complicated defeats point (2), and might not even be feasible with ASCIImage purposedly-limited options.

Pixels or vectors?

While it was initially developed with bitmaps in mind, and while the ASCII representation looks like pixels, the connect-the-numbers approach makes it a vector-drawing tool, with forced pixel alignment. This can be confusing. Even I was confused without realizing: I did not use the word 'vector' once in my original blog post. Only when the first editor was developed (ASCIImage Super Studio) did I realize it could draw very large images with smooth curves, and output things I had never envisioned. That is because behind the scenes, shapes are first made into NSBezierPath. In the end, of course, everything on a screen ends up as pixels.

What's next?

The idea and initial implementation was mostly a one-day hack. But I did refine a few details over the year that followed, before finally making it public in March 2015. As a result of these tweaks, it is really filling out all my needs for what I use it for. I may add a few more options to the drawing "context" in the block-based API, in particular to exploit the vector aspect more, with scaling and smooting options. I am also curious to see what others do with it. But I think I want to really keep it simple and restricted to the original spirit: code and image in one place, with instant gratification. For more complex things, designers, real image editors and real formats should be used.

What apps are using ASCIImage?

Please let me know if you use ASCIImage in a shipping app, and I'll add it to the list here.

For now, I only know of Findings (disclaimer: I, the author of ASCIImage, makes a living from Findings).

Why not just use SVG?

Sigh.

Documentation Copy Chapter

Installation Copy Section

ASCIImage is available through CocoaPods. To install
it, simply add the following line to your Podfile:

pod "ASCIImage"

Characters and Pixels

An image is defined by an array of strings, where each string represents a row. Here is an example:

NSArray *asciiRepresentation =
@[
@"· · · 1 2 · · · · · ",
@"· · · A # # · · · · ",
@"· · · · # # # · · · ",
@"· · · · · # # # · · ",
@"· · · · · · 9 # 3 · ",
@"· · · · · · 8 # 4 · ",
@"· · · · · # # # · · ",
@"· · · · # # # · · · ",
@"· · · 7 # # · · · · ",
@"· · · 6 5 · · · · · ",
];

In this documentation, I'll just represent it as follows:

· · · 1 2 · · · · · 
· · · A # # · · · · 
· · · · # # # · · · 
· · · · · # # # · · 
· · · · · · 9 # 3 · 
· · · · · · 8 # 4 · 
· · · · · # # # · · 
· · · · # # # · · · 
· · · 7 # # · · · · 
· · · 6 5 · · · · ·

Whitespace is ignored. The 2 representations below are thus equivalent. It should be clear why using extra whitespace is recommended: it really helps make the content appear at the right aspect ratio.

· · · 1 2 · · · · ·          ···12·····
· · · A # # · · · ·          ···A##····
· · · · # # # · · ·          ····###···
· · · · · # # # · ·          ·····###··
· · · · · · 9 # 3 ·          ······9#3·
· · · · · · 8 # 4 ·          ······8#4·
· · · · · # # # · ·          ·····###··
· · · · # # # · · ·          ····###···
· · · 7 # # · · · ·          ···7##····
· · · 6 5 · · · · ·          ···65·····

Each row should have the same number of non-whitespace character or else you get nothing but a mysterious console log. These representations are invalid:

! ! I N V A L I D !             N O # G O O D ! 
· ····1 2 · · · · ·               1 2           
· · · A # # · · · ·               A # #         
· · · · # # # · · ·                 # # #       
· · · · · # # # · ·                   # # #     
· · · · · · 9 # 3 ·                     9 # 3   
· · · · · · 8 # 4 ·                     8 # 4   
· · · · · # # # · ·                   # # #     
· · · · # # # · · ·                 # # #       
· · · 7 # # · · · ·               7 # #         
· · · 6 5 · · · · ·               6 5

Special Characters

While all non-whitespace characters count as part of the pixel grid, most characters are passive. Only the following characters are considered as part of shapes:

1 2 3 4 5 6 7 8 9 A B C D E F G H I J K L M N O P
Q R S T U V W X Y Z a b c d e f g h i j k l m n p
q r s t u v w x y z

Note that the O (zero) and o (lowercase letter O) are ignored. The current implementation does not ignore the uppercase letter O. Any of those 3 things could be considered a bug, but that's just the way I thought it would be best. Maybe I'll regret it. Probably not.

All the other characters are ignored when it comes time to extract shapes from the grid of characters.

All the following representations are thus equivalent. The '#' signs in those examples are very useful as a guide for the eyes, and I use them all the time (@ works well too). But they can also be used for evil obfuscation! Bad!

· 1 2 · · · · ·        · 1 2 · · · · ·         · 1 2 · · · · ·        # 1 2 # # # # # 
· A # # · · · ·        · A @ @ · · · ·         · A · · · · · ·        # A # # # # # # 
· · # # # · · ·        · · @ @ @ · · ·         · · · · · · · ·        # # # # # # # # 
· · · # # # · ·        · · · @ @ @ · ·         · · · · · · · ·        # # # # # # # # 
· · · · 9 # 3 ·        · · · · 9 @ 3 ·         · · · · 9 · 3 ·        # # # # 9 # 3 # 
· · · · 8 # 4 ·        · · · · 8 @ 4 ·         · · · · 8 · 4 ·        # # # # 8 # 4 # 
· · · # # # · ·        · · · @ @ @ · ·         · · · · · · · ·        # # # # # # # # 
· · # # # · · ·        · · @ @ @ · · ·         · · · · · · · ·        # # # # # # # # 
· 7 # # · · · ·        · 7 @ @ · · · ·         · 7 · · · · · ·        # 7 # # # # # # 
· 6 5 · · · · ·        · 6 5 · · · · ·         · 6 5 · · · · ·        # 6 5 # # # # #

Bezier Paths

Before being rendered into an NSImage, the ASCII grid is transformed into a series of NSBezierPath. The next sections describe the different types of Bezier paths that may be created.

Polygons

The simplest use of the above characters is to draw polygons using the famous 'connect-the-numbers' technique. Each polygon is defined by a series of sequential characters, and a new polygon is started as soon as you skip a character in the above list. So the first polygon could be defined by the series '123456', the next shape with '89ABCDEF', the next with 'HIJKLMNOP', etc. For polygons, each character can only be used once (or never). If you run out of characters, you are probably abusing ASCIImage!

Here is an example with 3 polygons, defined with the series [1,2,3,4,5,6,7,8,9,A], then [C,D,E] and finally [G,H,I,J,K,L]. Note that the characters B and F were skipped to separate the three polygons. The second example next to it is equivalent, but the last polygon uses the series [a,b,c,d,e,f] for no good reason (but also no bad reason).

· · · · · · · · C · · E         · · · · · · · · C · · E 
· · · 1 2 · · · · · · ·         · · · 1 2 · · · · · · · 
· · · A · · · · · · · ·         · · · A · · · · · · · · 
· · · · · · · · · · · D         · · · · · · · · · · · D 
G · H · · · · · · · · ·         a · b · · · · · · · · · 
· · · · · · 9 · 3 · · ·         · · · · · · 9 · 3 · · · 
· · I J · · 8 · 4 · · ·         · · c d · · 8 · 4 · · · 
L · · K · · · · · · · ·         f · · e · · · · · · · · 
· · · · · · · · · · · ·         · · · · · · · · · · · · 
· · · 7 · · · · · · · ·         · · · 7 · · · · · · · · 
· · · 6 5 · · · · · · ·         · · · 6 5 · · · · · · · 
· · · · · · · · · · · ·         · · · · · · · · · · · ·

Single points

When a polygon is composed of just 1 character, it is made into a square filling out the corresponding point. The following representation contains 5 separate points.

· · 1 · · · · · · 5 · T 
· · · · 3 · · · · · · · 
· · · · · · · · · · 7 · 
· · · · · · · · · · · ·

Lines

When a character is used exactly twice, the corresponding shape will be a line joining the two points (center to center, with square ends, which will fill the pixels exactly when using a 1-point width for drawing). Since such characters are used more than once, they cannot be part of a polygon, and there is no need to skip characters between a line and any other shape. Here is an example with 3 lines and a triangle. Note how we don't skip any character (but we could).

· · 1 # # # # # # 1 6 · 
· · · · · · · · · · # · 
· · · · 2 · 3 · · · # · 
· · · · · 4 · · · · # · 
· · · · · · · · · · # · 
· · 5 # # # # # # 5 6 ·

Ellipses

When a character is used three or more time, the corresponding shape will be an ellipse defined by the largest rectangles that include all the points. All the following representations will produce the same 11-point-diameter circle:

· · · 1 1 1 1 1 · · ·      · · · · · 1 · · · · ·      · · · · · 1 · · · · ·    
· · 1 · · · · · 1 · ·      · · · · · · · · · · ·      · · · · · · · · · · ·    
· 1 · · · · · · · 1 ·      · · · · · · · · · · ·      · · · · · · · · · · ·    
1 · · · · · · · · · 1      · · · · · · · · · · ·      · · · · · · · · · · ·    
1 · · · · · · · · · 1      · · · · · · · · · · ·      · · · · · · · · · · ·    
1 · · · · · · · · · 1      1 · · · · · · · · · 1      · · · · · · · · · · ·    
1 · · · · · · · · · 1      · · · · · · · · · · ·      · · · · · · · · · · ·    
1 · · · · · · · · · 1      · · · · · · · · · · ·      · · · · · · · · · · ·    
· 1 · · · · · · · 1 ·      · · · · · · · · · · ·      · · · · · · · · · · ·    
· · 1 · · · · · 1 · ·      · · · · · · · · · · ·      · · · · · · · · · · ·    
· · · 1 1 1 1 1 · · ·      · · · · · 1 · · · · ·      1 · · · · · · · · · 1

APIs

The word 'API' is a bit grandiose for ASCIImage. It is just an NSImage category, with 2 class methods.

The simplest method that I use 99% of the time:

+ (PARImage *)imageWithASCIIRepresentation:(NSArray *)rep
                                     color:(PARColor *)color
                           shouldAntialias:(BOOL)shouldAntialias;

With this simple form, the single points, polygons and ellipses will be filled with the color, while lines will be 'stroked' with that same color. Simple.

The second method offers more advanced options that can be set on each "shape", using the contextHandler block. The mutable dictionary passed by the block can be modified using the keys listed in the constants below. The dictionary initially contains the ASCIIContextShapeIndex key to signal which shape the context will be applied to.

+ (PARImage *)imageWithASCIIRepresentation:(NSArray *)rep
                            contextHandler:(void(^)(NSMutableDictionary *ctx))handler;

And here are the keys for the dictionary context:

extern NSString * const ASCIIContextShapeIndex;
extern NSString * const ASCIIContextFillColor;
extern NSString * const ASCIIContextStrokeColor;
extern NSString * const ASCIIContextLineWidth;
extern NSString * const ASCIIContextShouldClose;
extern NSString * const ASCIIContextShouldAntialias;

Note that some of these options are in fact applied to the Bezier paths (line width, should close), while others are applied to the actual graphic context. The antialiasing option can alter both. ASCIImage is doing a few things behind the scenes to keep the illusion going.

Author Copy Chapter

cparnot, [email protected]

License Copy Chapter

ASCIImage is available under the MIT license. See the LICENSE file for more info.

Overview (`Pods/CocoaLumberjack/README.md`) Copy Section

CocoaLumberjack

CocoaLumberjack is a fast & simple, yet powerful & flexible logging framework for macOS, iOS, tvOS and watchOS.

How to get started Copy Chapter

First, install CocoaLumberjack via CocoaPods, Carthage, Swift Package Manager or manually.
Then use DDOSLogger for iOS 10 and later, or DDTTYLogger and DDASLLogger for earlier versions to begin logging messages.

CocoaPods Copy Section

platform :ios, '11.0'

target 'SampleTarget' do
  use_frameworks!
  pod 'CocoaLumberjack/Swift'
end

Note: Swift is a subspec which will include all the Obj-C code plus the Swift one, so this is sufficient.
For more details about how to use Swift with Lumberjack, see this conversation.

For Objective-C use the following:

platform :ios, '11.0'

target 'SampleTarget' do
    pod 'CocoaLumberjack'
end

Carthage Copy Section

Carthage is a lightweight dependency manager for Swift and Objective-C. It leverages CocoaTouch modules and is less invasive than CocoaPods.

To install with Carthage, follow the instruction on Carthage

Cartfile

github "CocoaLumberjack/CocoaLumberjack"

Swift Package Manager Copy Section

As of CocoaLumberjack 3.6.0, you can use the Swift Package Manager as integration method.
If you want to use the Swift Package Manager as integration method, either use Xcode to add the package dependency or add the following dependency to your Package.swift:

.package(url: "https://github.com/CocoaLumberjack/CocoaLumberjack.git", from: "3.8.0"),

Note that you may need to add both products, CocoaLumberjack and CocoaLumberjackSwift to your target since SPM sometimes fails to detect that CocoaLumerjackSwift depends on CocoaLumberjack.

Install manually Copy Section

If you want to install CocoaLumberjack manually, read the manual installation guide for more information.

Swift Usage Copy Section

Usually, you can simply import CocoaLumberjackSwift. If you installed CocoaLumberjack using CocoaPods, you need to use import CocoaLumberjack instead.

DDLog.add(DDOSLogger.sharedInstance) // Uses os_log

let fileLogger: DDFileLogger = DDFileLogger() // File Logger
fileLogger.rollingFrequency = 60 * 60 * 24 // 24 hours
fileLogger.logFileManager.maximumNumberOfLogFiles = 7
DDLog.add(fileLogger)

...

DDLogVerbose("Verbose")
DDLogDebug("Debug")
DDLogInfo("Info")
DDLogWarn("Warn")
DDLogError("Error")

Obj-C usage Copy Section

If you're using Lumberjack as a framework, you can @import CocoaLumberjack;.
Otherwise, #import <CocoaLumberjack/CocoaLumberjack.h>

[DDLog addLogger:[DDOSLogger sharedInstance]]; // Uses os_log

DDFileLogger *fileLogger = [[DDFileLogger alloc] init]; // File Logger
fileLogger.rollingFrequency = 60 * 60 * 24; // 24 hour rolling
fileLogger.logFileManager.maximumNumberOfLogFiles = 7;
[DDLog addLogger:fileLogger];

...

DDLogVerbose(@"Verbose");
DDLogDebug(@"Debug");
DDLogInfo(@"Info");
DDLogWarn(@"Warn");
DDLogError(@"Error");

Objective-C ARC Semantic Issue Copy Section

When integrating Lumberjack into an existing Objective-C it is possible to run into Multiple methods named 'tag' found with mismatched result, parameter type or attributes build error.

Add #define DD_LEGACY_MESSAGE_TAG 0 before importing CocoaLumberjack or add #define DD_LEGACY_MESSAGE_TAG 0 or add -DDD_LEGACY_MESSAGE_TAG=0 to Other C Flags/OTHER_CFLAGS in your Xcode project.

[swift-log](https://github.com/apple/swift-log) backend Copy Chapter

CocoaLumberjack also ships with a backend implementation for swift-log.
Simply add CocoaLumberjack as dependency to your SPM target (see above) and also add the CocoaLumberjackSwiftLogBackend product as dependency to your target.

You can then use DDLogHandler as backend for swift-log, which will forward all messages to CocoaLumberjack's DDLog. You will still configure the loggers and log formatters you want via DDLog, but writing log messages will be done using Logger from swift-log.

In your own log formatters, you can make use of the swiftLogInfo property on DDLogMessage to retrieve the details of a message that is logged via swift-log.

To use swift-log with CocoaLumberjack, take a look the following code snippet to see how to get started.

import CocoaLumberjack
import CocoaLumberjackSwiftLogBackend
import Logging

// In your application's entry point (e.g. AppDelegate):
DDLog.add(DDOSLogger.sharedInstance) // Configure loggers
LoggingSystem.bootstrapWithCocoaLumberjack() // Use CocoaLumberjack as swift-log backend

More information Copy Chapter

• read the Getting started guide, check out the FAQ section or the other docs
• if you find issues or want to suggest improvements, create an issue or a pull request
• for all kinds of questions involving CocoaLumberjack, use the Google group or StackOverflow (use #lumberjack).

CocoaLumberjack 3 Copy Chapter

Migrating to 3.x Copy Section

• To be determined

Features Copy Chapter

Lumberjack is Fast & Simple, yet Powerful & Flexible. Copy Section

It is similar in concept to other popular logging frameworks such as log4j, yet is designed specifically for Objective-C, and takes advantage of features such as multi-threading, grand central dispatch (if available), lockless atomic operations, and the dynamic nature of the Objective-C runtime.

Lumberjack is Fast Copy Section

In most cases it is an order of magnitude faster than NSLog.

Lumberjack is Simple Copy Section

It takes as little as a single line of code to configure lumberjack when your application launches. Then simply replace your NSLog statements with DDLog statements and that's about it. (And the DDLog macros have the exact same format and syntax as NSLog, so it's super easy.)

Lumberjack is Powerful: Copy Section

One log statement can be sent to multiple loggers, meaning you can log to a file and the console simultaneously. Want more? Create your own loggers (it's easy) and send your log statements over the network. Or to a database or distributed file system. The sky is the limit.

Lumberjack is Flexible: Copy Section

Configure your logging however you want. Change log levels per file (perfect for debugging). Change log levels per logger (verbose console, but concise log file). Change log levels per xcode configuration (verbose debug, but concise release). Have your log statements compiled out of the release build. Customize the number of log levels for your application. Add your own fine-grained logging. Dynamically change log levels during runtime. Choose how & when you want your log files to be rolled. Upload your log files to a central server. Compress archived log files to save disk space...

This framework is for you if: Copy Chapter

• You're looking for a way to track down that impossible-to-reproduce bug that keeps popping up in the field.
• You're frustrated with the super short console log on the iPhone.
• You're looking to take your application to the next level in terms of support and stability.
• You're looking for an enterprise level logging solution for your application (Mac or iPhone).

Documentation Copy Chapter

• Get started using Lumberjack
• Different log levels for Debug and Release builds
• Different log levels for each logger
• Use colors in the Xcode debugging console
• Write your own custom formatters
• FAQ
• Analysis of performance with benchmarks
• Common issues you may encounter and their solutions
• AppCode support
• Full Lumberjack documentation

Requirements Copy Chapter

The current version of Lumberjack requires:

• Xcode 14.1 or later
• Swift 5.5 or later
• macOS 10.13 or later
• iOS 11 or later
• tvOS 11 or later
• watchOS 4 or later

Backwards compatibility Copy Section

• for iOS/tvOS up to 10, watchOS up to 3, macOS up to 10.12, Xcode up to 13 and Swift up to 5.4, use the 3.7.4 version
• for Xcode 11 and Swift up to 5.2, use the 3.6.2 version
• for Xcode 10 and Swift 4.2, use the 3.5.2 version
• for iOS 8, use the 3.6.1 version
• for iOS 6, iOS 7, OS X 10.8, OS X 10.9 and Xcode 9, use the 3.4.2 version
• for iOS 5 and OS X 10.7, use the 3.3 version
• for Xcode 8 and Swift 3, use the 3.2 version
• for Xcode 7.3 and Swift 2.3, use the 2.4.0 version
• for Xcode 7.3 and Swift 2.2, use the 2.3.0 version
• for Xcode 7.2 and 7.1, use the 2.2.0 version
• for Xcode 7.0 or earlier, use the 2.1.0 version
• for Xcode 6 or earlier, use the 2.0.x version
• for OS X < 10.7 support, use the 1.6.0 version

Communication Copy Chapter

• If you need help, use Stack Overflow. (Tag 'lumberjack')
• If you'd like to ask a general question, use Stack Overflow.
• If you found a bug, open an issue.
• If you have a feature request, open an issue.
• If you want to contribute, submit a pull request.

Data Collection Practices Copy Chapter

Per App privacy details on the App Store, Apple is requesting app developers to provide info about their data collection, us SDK maintainers must provide them with the same data.

Data collection by the framework Copy Section

By default, CocoaLumberjack does NOT collect any data on its own.

See our Data Collection Practices list.

Indirect data collection through the framework Copy Section

CocoaLumberjack is a logging framework which makes it easy to send those logs to different platforms.

This is why collecting data might happen quite easily, if app developers include any sensitive data into their log messages.

Important note: app developers are fully responsible for any sensitive data collected through our logging system!

In consequence, you must comply to the Apple's privacy details policy (mentioned above) and document the ways in which user data is being collected.
Since the number of scenarios where data might be indirectly collected through CocoaLumberjack is quite large, it's up to you, as app developers, to properly review your app's code and identify those cases.
What we can do to help is raise awareness about potential data collection through our framework.

Private data includes but isn't limited to:

• user info (name, email, address, ...)
• location info
• contacts
• identifiers (user id, device id, ...)
• app usage data
• performance data
• health and fitness info
• financial info
• sensitive info
• user content
• history (browsing, search, ...)
• purchases
• diagnostics
• ...

Example: DDLogInfo("User: \(myUser)") will add the myUser info to the logs, so if those are forwarded to a 3rd party or sent via email, that may qualify as data collection.

Author Copy Chapter

• Robbie Hanson
• Love the project? Wanna buy me a coffee? (or a beer :D)

Collaborators Copy Chapter

• Ernesto Rivera
• Dmitry Vorobyov
• Bogdan Poplauschi
• C.W. Betts
• Koichi Yokota (sushichop)
• Nick Brook
• Florian Friedrich
• Stephan Diederich
• Kent Sutherland
• Dmitry Lobanov
• Hakon Hanesand

License Copy Chapter

• CocoaLumberjack is available under the BSD 3 license. See the LICENSE file.

Extensions Copy Chapter

• Birch-Lumberjack A remote logger for CocoaLumberjack
• BugfenderSDK-CocoaLumberjack A Bugfender logger for CocoaLumberjack
• LogIO-CocoaLumberjack A log.io logger for CocoaLumberjack
• XCDLumberjackNSLogger CocoaLumberjack logger which sends logs to NSLogger

Architecture Copy Chapter

Overview (`Pods/MIKMIDI/README.md`) Copy Section

This README file is meant to give a broad overview of MIKMIDI. More complete documentation for MIKMIDI can be found here. Questions should be directed to Andrew Madsen.

MIKMIDI Copy Chapter

MIKMIDI is an easy-to-use Mac and iOS MIDI library created by Andrew Madsen and developed by him and Chris Flesner of Mixed In Key. It's useful for programmers writing Objective-C or Swift macOS or iOS apps that use MIDI. It includes the ability to communicate with external MIDI devices, to read and write MIDI files, to record and play back MIDI, etc. MIKMIDI is used to provide MIDI functionality in the Mac versions of our DJ app, Flow, our flagship app Mixed In Key, and our composition software, Odesi.

MIKMIDI can be used in projects targeting Mac OS X 10.7 and later, and iOS 6 and later. The example code in this readme is in Swift. However, MIKMIDI can also easily be used from Objective-C code.

MIKMIDI is released under an MIT license, meaning you're free to use it in both closed and open source projects. However, even in a closed source project, you must include a publicly-accessible copy of MIKMIDI's copyright notice, which you can find in the LICENSE file.

If you have any questions about, or suggestions for MIKMIDI, please contact the maintainer. Contributions are always welcome. Please see our contribution guidelines for more information. We'd also always love to hear about any cool projects you're using it in.

How To Use MIKMIDI Copy Chapter

MIKMIDI ships with a project to build frameworks for iOS and macOS. You can also install it using CocoaPods or Carthage. See this page on the MIKMIDI wiki for detailed instructions for adding MIKMIDI to your project.

A note about Swift: MIKMIDI is written in Objective-C, but fully supports Swift. The only caveat is that API changes that affect only Swift, but not Objective-C, such as improved nullability annotation, refined API names for Swift, etc., are not limited to major versions, but rather will sometimes be included in minor version releases. Bug fix/patch releases will not break Swift or Objective-C API. Objective-C API will be stable within a major version, e.g. 1.y.z.

MIKMIDI Overview Copy Chapter

MIKMIDI has an Objective-C interface -- as opposed to CoreMIDI's pure C API -- in order to make adding MIDI support to a Cocoa/Cocoa Touch app easier. At its core, MIKMIDI consists of relatively thin Objective-C wrappers around underlying CoreMIDI APIs. Much of MIKMIDI's design is informed and driven by CoreMIDI's design. For this reason, familiarity with the high level pieces of CoreMIDI can be helpful in understanding and using MIKMIDI.

MIKMIDI is not limited to Objective-C interfaces for existing CoreMIDI functionality. MIKMIDI provides a number of higher level features. These include: message routing, sequencing, recording, etc.. Also included is functionality intended to facilitate implementing a MIDI learning UI so that users may create custom MIDI mapping files. These MIDI mapping files associate physical controls on a particular piece of MIDI hardware with corresponding receivers (e.g. on-screen buttons, knobs, musical instruments, etc.) in your application.

To understand MIKMIDI, it's helpful to break it down into its major subsystems:

• Device support -- includes support for device discovery, connection/disconnection, and sending/receiving MIDI messages.
• Commands -- includes a number of classes that represent various MIDI message types as received from and sent to MIDI devices and endpoints.
• Mapping -- support for generating, saving, loading, and using files that associate physical MIDI controls with corresponding application features.
• Files -- support for reading and writing MIDI files.
• Synthesis -- support for turning MIDI into audio, e.g. playback of MIDI files and incoming MIDI keyboard input.
• Sequencing -- Recording and playback of MIDI.

Of course, these subsystems are used together to enable sophisticated features.

Device Support Copy Chapter

MIKMIDI's device support architecture is based on the underlying CoreMIDI architecture. There are several major classes used to represent portions of a device. All of these classes are subclasses of MIKMIDIObject. These classes are listed below. In parentheses is the corresponding CoreMIDI class.

• MIKMIDIObject (MIDIObjectRef) -- Abstract base class for all the classes listed below. Includes properties common to all MIDI objects.
• MIKMIDIDevice (MIDIDeviceRef) -- Represents a single physical device, e.g. a DJ controller, MIDI keyboard, MIDI drum set, etc.
• MIKMIDIEntity (MIDIEntityRef) -- Groups related endpoints. Owned by MIKMIDIDevice, contains MIKMIDIEndpoints.
• MIKMIDIEndpoint (MIDIEndpointRef) -- Abstract base class representing a MIDI endpoint. Not used directly, only via its subclasses MIKMIDISourceEndpoint and MIKMIDIDestinationEndpoint.
• MIKMIDISourceEndpoint -- Represents a MIDI source. MIDI sources receive messages that your application can hear and process.
• MIKMIDIDestinationEndpoint -- Represents a MIDI destination. Your application passes MIDI messages to a destination endpoint in order to send them to a device.

MIKMIDIDeviceManager is a singleton class used for device discovery, and to send and receive MIDI messages to and from endpoints. To get a list of MIDI devices available on the system, call -availableDevices on the shared device manager:

let availableDevices = MIKMIDIDeviceManager.shared.availableDevices

MIKMIDIDeviceManager also includes the ability to retrieve 'virtual' endpoints, to enable communicating with other MIDI apps, or with devices (e.g. Native Instruments controllers) which present as virtual endpoints rather than physical devices.

MIKMIDIDeviceManager's availableDevices, and virtualSources and virtualDestinations properties are Key Value Observing (KVO) compliant. This means that for example, availableDevices can be bound to an NSPopupMenu in an OS X app to provide an automatically updated list of connected MIDI devices. They can also be directly observed using key value observing to be notified when devices are connected or disconnected, etc. Additionally, MIKMIDIDeviceManager posts these notifications: MIKMIDIDeviceWasAddedNotification, MIKMIDIDeviceWasRemovedNotification, MIKMIDIVirtualEndpointWasAddedNotification, MIKMIDIVirtualEndpointWasRemovedNotification.

MIKMIDIDeviceManager is used to sign up to receive messages from MIDI devices as well as to send them. To receive messages from a MIKMIDIDevice, you must connect the device and supply an event handler block to be called anytime messages are received. This is done using the connect(_:, eventHandler:) method. When you no longer want to receive messages, you must call the disconnectConnection(forToken:) method. To send MIDI messages to an MIKMIDIDevice, get the appropriate MIKMIDIDestinationEndpoint from the device, then call MIKMIDIDeviceManager.send(_: [MIKMIDICommand], to:) passing an array of MIKMIDICommand instances. For example:

let noteOn = MIKMIDINoteOnCommand(note: 60, velocity: 127, channel: 0, timestamp: Date())
let noteOff = MIKMIDINoteOffCommand(note: 60, velocity: 127, channel: 0, timestamp: Date().advanced(by: 0.5))
try MIKMIDIDeviceManager.shared.send([noteOn, noteOff], to: destinationEndpoint)

If you've used CoreMIDI before, you may be familiar with MIDIClientRef and MIDIPortRef. These are used internally by MIKMIDI, but the "public" API for MIKMIDI does not expose them -- or their Objective-C counterparts -- directly. Rather, MIKMIDIDeviceManager itself allows sending and receiving messages to/from MIKMIDIEndpoints.

MIDI Messages Copy Chapter

In MIKMIDI, MIDI messages are objects. These objects are instances of concrete subclasses of MIKMIDICommand. Each MIDI message type (e.g. Control Change, Note On, System Exclusive, etc.) has a corresponding class (e.g. MIKMIDIControlChangeCommand). Each command class has properties specific to that message type. By default, MIKMIDICommands are immutable. Mutable variants of each command type are also available.

MIDI Mapping Copy Chapter

MIKMIDI includes features to help with adding MIDI mapping support to an application. MIDI mapping refers to the ability to map physical controls on a particular hardware controller to specific functions in the application. MIKMIDI's mapping support includes the ability to generate, save, load, and use mapping files that associate physical controls with an application's specific functionality. It also includes help with implementing a system that allows end users to easily generate their own mappings using a "MIDI learn" style interface.

The major components of MIKMIDI's MIDI mapping functionality are:

• MIKMIDIMapping - Model class containing information to map incoming messages to to the appropriate application functionality.
• MIKMIDIMappingManager - Singleton manager used to load, save, and retrieve both application-bundled, and user customized mapping files.
• MIKMIDIMappingGenerator - Class that can listen to incoming MIDI messages, and associate them with application functionality, creating a custom MIDI mapping file.

MIDI Files Copy Chapter

MIKMIDI includes features to make it easy to read and write MIDI files. This support is primarily provided by:

• MIKMIDISequence - This class is used to represent a MIDI sequence, and can be read from or written to a MIDI file.
• MIKMIDITrack - An MIKMIDISequence contains one or more MIKMIDITracks.
• MIKMIDIEvent - MIKMIDIEvent and its specific subclasses are used to represent MIDI events contained by MIKMIDITracks.

MIDI Synthesis Copy Chapter

MIDI synthesis is the process by which MIDI events/messages are turned into audio that you can hear. This is accomplished using MIKMIDISynthesizer. Also included is a subclass of MIKMIDISynthesizer, MIKMIDIEndpointSynthesizer which can very easily be hooked up to a MIDI endpoint to synthesize incoming MIDI messages:

let endpoint = midiDevice.entities.first!.sources.first!
let synth = try MIKMIDIEndpointSynthesizer(midiSource: endpoint)

MIDI Sequencing Copy Chapter

MIKMIDISequencer can be used to play and record to an MIKMIDISequence. It includes a number of high level features useful when implementing MIDI recording and playback. However, at the very simplest, MIKMIDISequencer can be used to load a MIDI file and play it like so:

let sequence = try! MIKMIDISequence(fileAt: midiFileURL)
let sequencer = MIKMIDISequencer(sequence: sequence)
sequencer.startPlayback()

Overview (`Pods/ORSSerialPort/README.md`) Copy Section

ORSSerialPort

ORSSerialPort is an easy-to-use Objective-C serial port library for macOS. It is useful for programmers writing Objective-C or Swift Mac apps that communicate with external devices through a serial port (most commonly RS-232). You can use ORSSerialPort to write apps that connect to Arduino projects, robots, data acquisition devices, ham radios, and all kinds of other devices. Using ORSSerialPort to open a port and send data can be as simple as this:

ORSSerialPort *serialPort = [ORSSerialPort serialPortWithPath:@"/dev/cu.KeySerial1"];
serialPort.baudRate = @4800;
[serialPort open];
[serialPort sendData:someData]; // someData is an NSData object
[serialPort close]; // Later, when you're done with the port

Or, in Swift:

let serialPort = ORSSerialPort(path: "/dev/cu.KeySerial1")
serialPort.baudRate = 4800
serialPort.open()
serialPort.sendData(someData) // someData is an NSData object
serialPort.close() // Later, when you're done with the port

ORSSerialPort is released under an MIT license, meaning you're free to use it in both closed and open source projects. However, even in a closed source project, you must include a publicly-accessible copy of ORSSerialPort's copyright notice, which you can find in the LICENSE file.

If you have any questions about, suggestions for, or contributions to ORSSerialPort, please contact me. I'd also love to hear about any cool projects you're using it in.

This readme provides an overview of the ORSSerialPort library and is meant to provide enough information to get up and running quickly. You can read complete technical documentation for ORSSerialPort on http://cocoadocs.org/docsets/ORSSerialPort/. The ORSSerialPort wiki also contains detailed documentation.

The example code in this readme is in Objective-C. However, ORSSerialPort can also easily be used from Swift code. The Examples folder contains Swift versions of all four example projects. See the Example Projects section below for more information.

How to Use ORSSerialPort

There are a number of ways to add ORSSerialPort to your project. You can use the included framework project, Carthage, CocoaPods, or manually include the ORSSerialPort source code in your project. See the Guide to Installing ORSSerialPort for detailed instructions for each of these methods.

Opening a Port and Setting It Up Copy Section

You can get an ORSSerialPort instance either of two ways. The easiest is to use ORSSerialPortManager's availablePorts array (explained below). The other way is to get a new ORSSerialPort instance using the serial port's BSD device path:

ORSSerialPort *port = [ORSSerialPort serialPortWithPath:@"/dev/cu.KeySerial1"];

Note that you must give +serialPortWithPath: the full path to the device, as shown in the example above.

After you've got a port instance, you can open it with the -open method. When you're done using the port, close it using the -close method.

Port settings such as baud rate, number of stop bits, parity, and flow control settings can be set using the various properties ORSSerialPort provides:

port.baudRate = @9600;
port.parity = ORSSerialPortParityNone;
port.numberOfStopBits = 1;
port.usesRTSCTSFlowControl = YES;

For more information, see the Getting Started Guide.

Sending Data Copy Section

Send raw data by passing an NSData object to the -sendData: method:

NSData *dataToSend = [self.sendTextField.stringValue dataUsingEncoding:NSUTF8StringEncoding];
[self.serialPort sendData:dataToSend];

Receiving Data Copy Section

To receive data, you can implement the ORSSerialPortDelegate protocol's -serialPort:didReceiveData: method, and set the ORSSerialPort instance's delegate property. As noted below, this method is always called on the main queue. An example implementation is included below:

- (void)serialPort:(ORSSerialPort *)serialPort didReceiveData:(NSData *)data
{
    NSString *string = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
    [self.receivedDataTextView.textStorage.mutableString appendString:string];
    [self.receivedDataTextView setNeedsDisplay:YES];
}

ORSSerialPortDelegate Copy Section

ORSSerialPort includes a delegate property, and a delegate protocol called ORSSerialPortDelegate. A port informs its delegate of events including receipt of data, port open/close events, removal from the system, and errors. For more information, see the Getting Started Guide, or read the documentation in ORSSerialPort.h.

ORSSerialPortManager Copy Section

ORSSerialPortManager is a singleton class (one instance per application) that can be used to get a list of available serial ports. Use the manager's availablePorts property to get a list of ports:

NSArray *ports = [[ORSSerialPortManager sharedSerialPortManager] availablePorts];

ORSSerialPortManager's availablePorts can be observed with Key Value Observing to be notified when a USB to serial adapter is plugged in or removed. Additionally, it posts NSNotifications when these events occur. It will also handle closing open serial ports when the Mac goes to sleep, and reopening them automatically on wake. This prevents problems I've seen with serial port drivers that can hang if the port is left open when putting the machine to sleep. Note that using ORSSerialPortManager is optional. It provides some nice functionality, but only ORSSerialPort is necessary to simply send and receive data.

For more information about ORSSerialPortManager, see the Getting Started Guide, or read the documentation in ORSSerialPortManager.h.

ORSSerialPacketDescriptor Copy Section

Incoming serial data is delivered to your application as it is received. A low level library like ORSSerialPort has no way of knowing anything about the structure and format of the data you're sending and receiving. For example, you may be expecting a complete packet of data, but receive callbacks for each byte. Normally, this requires you to maintain a buffer which you fill up with incoming data, only processing it when a complete packet has been received. In order to eliminate the need for manual management and buffering of incoming data, ORSSerialPort includes a packet parsing API. This is implemented by ORSSerialPacketDescriptor and associated methods on ORSSerialPort.

For more information about ORSSerialPort's packet parsing API, see the Packet Parsing API Guide, read the documentation in ORSSerialPacketDescriptor.h, and see the PacketParsingDemo example app.

ORSSerialRequest Copy Section

Often, applications will want to send a command to a device, then wait to receive a specific response before continuing. To ease implementing this kind of scenario, ORSSerialPort includes a request/response API. This is implemented by ORSSerialRequest and associated methods on ORSSerialPort.

For example, a program that read the temperature from a connected device might do the following:

- (void)readTemperature
{
    NSData *command = [@"$TEMP?;" dataUsingEncoding:NSASCIIStringEncoding];
    ORSSerialPacketDescriptor *responseDescriptor = 
    [[ORSSerialPacketDescriptor alloc] initWithMaximumPacketLength:9
                                                          userInfo:nil
                                                 responseEvaluator:^BOOL(NSData *data) {
        return [self temperatureFromResponsePacket:data] != nil;
    }];
    ORSSerialRequest *request = 
        [ORSSerialRequest requestWithDataToSend:command
                                       userInfo:nil
                                timeoutInterval:kTimeoutDuration
                             responseDescriptor:responseDescriptor];
    [self.serialPort sendRequest:request];
} 

- (void)serialPort:(ORSSerialPort *)port didReceiveResponse:(NSData *)data toRequest:(ORSSerialRequest *)request
{
    NSString *response = [[NSString alloc] initWithData:data usingEncoding:NSASCIIStringEncoding];
    NSLog(@"response = %@", response);
    self.temperature = [self temperatureFromResponsePacket:data];
}

- (void)serialPort:(ORSSerialPort *)port requestDidTimeout:(ORSSerialRequest *)request
{
    NSLog(@"command timed out!);
}

For more information about ORSSerialPort's request/response API, see the Request/Response API Guide, read the documentation in ORSSerialRequest.h, and see the RequestResponseDemo example app.

Example Projects

Included with ORSSerialPort is a folder called Examples, containing Xcode projects for small programs demonstrating the use of ORSSerialPort. Each example is available in both Objective-C and Swift. The following example apps are included:

• ORSSerialPortDemo - Simple graphical serial terminal example app. This is the main ORSSerialPort example.
• CommandLineDemo - Command line app example.
• PacketParsingDemo - GUI app demonstrating the use of ORSSerialPacketDescriptor.
• RequestResponseDemo - GUI app demonstrating the use of ORSSerialRequest.

You can read more about these examples on the ORSSerialPort wiki.

Contributing

Contributions to ORSSerialPort are very welcome. However, contributors are encouraged to read the contribution guidelines before starting work on any contributions. Please also feel free to open a GitHub issue or email with questions about specific contributions.

Overview (`Pods/PocketSocket/README.md`) Copy Section

PocketSocket

Objective-C websocket library for building things that work in realtime on iOS and OS X.

Features Copy Section

• Conforms fully to RFC6455 websocket protocol
• Support for websocket compression via the permessage-deflate extension
• Passes all ~519 Autobahn Client Tests & Server Tests with 100% compliance¹
• Client & Server modes (see notes below)
• TLS/SSL support
• Asynchronous IO
• Standalone PSWebSocketDriver for easy “Bring your own” networking IO

¹Some server tests are non-strict and drop connections earlier when receiving malformed WebSocket payloads.

Dependencies Copy Section

• CFNetworking.framework
• Foundation.framework
• Security.framework
• libSystem.dylib
• libz.dylib

Installation Copy Section

Installation is recommended via cocoapods. Add pod 'PocketSocket' to your Podfile and run pod install.

Major Components Copy Section

• PSWebSocketDriver - Networkless driver to deal with the websocket protocol. It solely operates with parsing raw bytes into events and sending events as raw bytes.
• PSWebSocket - Networking based socket around NSInputStream and NSOutputStream deals with ensuring a connection is maintained. Uses the PSWebSocketDriver internally on the input and output.
• PSWebSocketServer - Networking based socket server around CFSocket. It creates one PSWebSocket instance per incoming request.

Using PSWebSocket as a client Copy Section

The client supports both the ws and secure wss protocols. It will automatically negotiate the certificates for you from the certificate chain on the device it’s running. If you need custom SSL certificate support or pinning look at the webSocket:evaluateServerTrust: in PSWebSocketDelegate

The client will always request the server turn on compression via the permessage-deflate extension. If the server accepts the request it will be enabled for the entire duration of the connection and used on all messages.

If the initial NSURLRequest specifies a timeout greater than 0 the connection will timeout if it cannot open within that interval, otherwise it could wait forever depending on the system.

/* Detailed source-code truncated for AI context efficiency. */

Using PSWebSocket via PSWebSocketServer Copy Section

The server currently only supports the ws protocol. The server binds to the host address and port specified and accepts incoming connections. It parses the first HTTP request in each connection and then asks the delegate whether or not to accept it and complete the websocket handshake. The server expects to remain the delegate of all PSWebSocket instances it manages so be careful not to manage them yourself or detach them from the server.

/* Detailed source-code truncated for AI context efficiency. */

Using PSWebSocketDriver Copy Section

The driver is the core of PSWebSocket. It deals with the handshake request/response lifecycle, packing messages into websocket frames to be sent over the wire and parsing websocket frames received over the wire.

It supports both client and server mode and has an identical API for each.

To create an instance of it you use either clientDriverWithRequest: or serverDriverWithRequest: in the client mode you are to pass in a NSURLRequest that will be sent as a handshake request. In server mode you are to pass in the NSURLRequest that was the handshake request.

Beyond that have a look at the PSWebSocketDriverDelegate methods and the simple API for interacting with the driver.

Roadmap Copy Section

• Examples, examples, examples!

Running Tests Copy Section

1. Install autobahntestsuite sudo pip install autobahntestsuite
2. Start autobahn test server wstest -m fuzzingserver
3. Run tests in Xcode

Why a new library? Copy Section

Currently for Objective-C there is few options for websocket clients. SocketRocket, while probably the most notable, has a code base being entirely contained in a single file and proved difficult to build in new features such as permessage-deflate and connection timeouts.

PocketSocket firstly aims to provide a rich set of tools that are easy to dig into and modify when necessary. The decoupling of the network layer from the driver layer allows a lot of flexibility to incorporate the library with existing setups.

Secondly we intend on keeping PocketSocket at the top of it's game. As soon as any major websocket extensions come into play you can count on them being incorporated as soon as the drafts begin to stabalize.

Lastly we're set out to create the full picture from client to server all in a single, but decoupled toolkit for all use cases on iOS and OS X.

Authors Copy Section

• Robert Payne (@robertjpayne)

Contributors Copy Section

• Jens Alfke (@snej)

License Copy Section

Copyright 2014-Present Zwopple Limited

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Overview (`Pods/Sentry/README.md`) Copy Section

Bad software is everywhere, and we're tired of it. Sentry is on a mission to help developers write better software faster, so we can get back to enjoying technology. If you want to join us Check out our open positions

[!NOTE]
You are currently viewing the v8.x branch which contains the latest v8 release.

For the upcoming v9 release, please switch to the main branch and refer to the v9 CHANGELOG.

Official Sentry SDK for iOS / tvOS / macOS / watchOS ⁽¹⁾

Installation

SPM is the recommended way to include Sentry into your project, but we also support CocoaPods and Carthage, and provide pre-built XCFrameworks on our GitHub Releases page.

Initialization

Remember to call this as early in your application life cycle as possible
Ideally in applicationDidFinishLaunching in AppDelegate

import Sentry

// ....

SentrySDK.start { options in
    options.dsn = "___PUBLIC_DSN___"
    options.debug = true // Helpful to see what's going on
}

@import Sentry;

// ....

[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
    options.dsn = @"___PUBLIC_DSN___";
    options.debug = @YES; // Helpful to see what's going on
}];

For more information checkout the docs.

⁽¹⁾limited symbolication support and no crash handling.

Blog posts

Mobile Vitals - Four Metrics Every Mobile Developer Should Care About.

How to use Sentry Attachments with Mobile Applications.

Close the Loop with User Feedback.

A Sanity Listicle for Mobile Developers.

Resources

Overview (`Pods/SocketRocket/README.md`) Copy Section

SocketRocket

[

A conforming WebSocket (RFC 6455) client library for iOS, macOS and tvOS.

Test results for SocketRocket here.
You can compare to what modern browsers look like here.

SocketRocket currently conforms to all core ~300 of Autobahn's fuzzing tests
(aside from two UTF-8 ones where it is merely non-strict tests 6.4.2 and 6.4.4).

Features/Design Copy Chapter

• TLS (wss) support, including self-signed certificates.
• Seems to perform quite well.
• Supports HTTP Proxies.
• Supports IPv4/IPv6.
• Supports SSL certificate pinning.
• Sends ping and can process pong events.
• Asynchronous and non-blocking. Most of the work is done on a background thread.
• Supports iOS, macOS, tvOS.

Installing Copy Chapter

There are a few options. Choose one, or just figure it out:

• CocoaPods

Add the following line to your Podfile:

pod 'SocketRocket'

Run pod install, and you are all set.

• Carthage

Add the following line to your Cartfile:

github "facebook/SocketRocket"

Run carthage update, and you should now have the latest version of SocketRocket in your Carthage folder.

• Using SocketRocket as a sub-project

  You can also include SocketRocket as a subproject inside of your application if you'd prefer, although we do not recommend this, as it will increase your indexing time significantly. To do so, just drag and drop the SocketRocket.xcodeproj file into your workspace.

API Copy Chapter

`SRWebSocket` Copy Section

The Web Socket.

Note:

SRWebSocket will retain itself between -(void)open and when it closes, errors, or fails.
This is similar to how NSURLConnection behaves (unlike NSURLConnection, SRWebSocket won't retain the delegate).

Interface

@interface SRWebSocket : NSObject

// Make it with this
- (instancetype)initWithURLRequest:(NSURLRequest *)request;

// Set this before opening
@property (nonatomic, weak) id <SRWebSocketDelegate> delegate;

// Open with this
- (void)open;

// Close it with this
- (void)close;

// Send a Data
- (void)sendData:(nullable NSData *)data error:(NSError **)error;

// Send a UTF8 String
- (void)sendString:(NSString *)string error:(NSError **)error;

@end

`SRWebSocketDelegate` Copy Section

You implement this

@protocol SRWebSocketDelegate <NSObject>

@optional

- (void)webSocketDidOpen:(SRWebSocket *)webSocket;

- (void)webSocket:(SRWebSocket *)webSocket didReceiveMessageWithString:(NSString *)string;
- (void)webSocket:(SRWebSocket *)webSocket didReceiveMessageWithData:(NSData *)data;

- (void)webSocket:(SRWebSocket *)webSocket didFailWithError:(NSError *)error;
- (void)webSocket:(SRWebSocket *)webSocket didCloseWithCode:(NSInteger)code reason:(nullable NSString *)reason wasClean:(BOOL)wasClean;

@end

Testing Copy Chapter

Included are setup scripts for the python testing environment.
It comes packaged with vitualenv so all the dependencies are installed in userland.

To run the short test from the command line, run:

make test

To run all the tests, run:

make test_all

The short tests don't include the performance tests
(the test harness is actually the bottleneck, not SocketRocket).

The first time this is run, it may take a while to install the dependencies. It will be smooth sailing after that.

You can also run tests inside Xcode, which runs the same thing, but makes it easier to debug.

• Choose the SocketRocketTests target
• Make sure your running destination is either your Mac or any Simulator
• Run the test action (⌘+U)

TestChat Demo Application Copy Section

SocketRocket includes a demo app, TestChat.
It will "chat" with a listening websocket on port 9900.

TestChat Server

The sever takes a message and broadcasts it to all other connected clients.

It requires some dependencies though to run.
We also want to reuse the virtualenv we made when we ran the tests.
If you haven't run the tests yet, go into the SocketRocket root directory and type:

make test

This will set up your virtualenv.

Now, in your terminal:

source .env/bin/activate
pip install git+https://github.com/tornadoweb/tornado.git

In the same terminal session, start the chatroom server:

python TestChatServer/py/chatroom.py

There's also a Go implementation (with the latest weekly) where you can:

cd TestChatServer/go
go run chatroom.go

Chatting

Now, start TestChat.app (just run the target in the Xcode project).
If you had it started already you can hit the refresh button to reconnect.
It should say "Connected!" on top.

To talk with the app, open up your browser to http://localhost:9000 and start chatting.

WebSocket Server Implementation Recommendations Copy Chapter

SocketRocket has been used with the following libraries:

• Tornado
• Go's WebSocket package or Gorilla's version.
• Autobahn (using its fuzzing client).

The Tornado one is dirt simple and works like a charm.
(IPython notebook uses it too).
It's much easier to configure handlers and routes than in Autobahn/twisted.

Contributing Copy Chapter

We’re glad you’re interested in SocketRocket, and we’d love to see where you take it.
Please read our contributing guidelines prior to submitting a Pull Request.

Overview (`scripts/docs/README.md`) Copy Section

To write docs Copy Section

1. Any comment that starts with --- or /// is a doc-string (i.e. 3 comment-characters in a row)
2. Doc-strings continue on until a non-docstring line
3. Doc-strings for modules contain === my.modulename ===, then any number of lines describing it
4. Doc-strings for items (functions, variables, etc.) go like this:
   1. The first line starts with my.modulename.item or my.modulename:item -- this is the item name
   2. Any non-alphanumeric character ends the item name and is ignored, i.e. parentheses or spaces:
      1. my.modulename:foo()
      2. my.modulename:foo(bar) -> string
      3. my.modulename.foo(bar, fn(int) -> int)
      4. my.modulename.foo = {}
   3. The second line is a single capitalized word, like "Variable" or "Function" or "Method" or "Constant" or "Field"
   4. The remaining lines describe the item
5. Any comment that starts with 4 comment-characters is ignored
6. Only files ending in .lua or .m are scanned

To generate docs Copy Section

$ pip install --user -r requirements.txt
$ make docs

Your output will now be in build/ in the following forms:

• Hammerspoon.docset - Docs bundle for the excellent "Dash" browser
• html - HTML docs

Extensions Doc Hsdocs Index (`extensions/doc/hsdocs/index.md`) Copy Section

Project links Copy Section

Extensions Doc Hsdocs Hsminweb Index (`extensions/doc/hsdocs/hsminweb/index.md`) Copy Section

HSMINWEB Supporting Documentation Copy Section

This folder provides specific documentation and examples for getting the most out of hs.httpserver.hsminweb.

• Custom Error Functions
• Lua Template Files

Extensions Doc Lua.Json (`extensions/doc/lua.json`) Copy Section

[{"doc":"Built in Lua 5.4 functions and variables.\n\nThe text for this documentation is originally from http://www.lua.org\/manual\/5.4\/ but has been programmatically parsed and rearranged for use with the Hammerspoon internal documentation system. Any errors, mistakes, or omissions are likely the result of this processing and is in no way a reflection on Lua.org or their work. If in doubt about anything presented in this lua section of the Hammerspoon documentation, please check the above web site for the authoritative answer.\n","items":[{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__add","type":"builtin","def":"__add"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__band","type":"builtin","def":"__band"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__bnot","type":"builtin","def":"__bnot"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__bor","type":"builtin","def":"__bor"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__bxor","type":"builtin","def":"__bxor"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__call","type":"builtin","def":"__call"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__concat","type":"builtin","def":"__concat"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__div","type":"builtin","def":"__div"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__eq","type":"builtin","def":"__eq"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__idiv","type":"builtin","def":"__idiv"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__index","type":"builtin","def":"__index"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__le","type":"builtin","def":"__le"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__len","type":"builtin","def":"__len"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__lt","type":"builtin","def":"__lt"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__mod","type":"builtin","def":"__mod"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__mul","type":"builtin","def":"__mul"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__newindex","type":"builtin","def":"__newindex"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__pow","type":"builtin","def":"__pow"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__shl","type":"builtin","def":"__shl"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__shr","type":"builtin","def":"__shr"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__sub","type":"builtin","def":"__sub"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"__unm","type":"builtin","def":"__unm"},{"doc":"3.3.8 – To-be-closed Variables\n\nA to-be-closed variable behaves like a constant local variable, except that its value is closed whenever the variable goes out of scope, including normal block termination, exiting its block by break/goto/return, or exiting by an error.\n\nHere, to close a value means to call its __close metamethod. When calling the metamethod, the value itself is passed as the first argument and the error object that caused the exit (if any) is passed as a second argument; if there was no error, the second argument is nil.\n\nThe value assigned to a to-be-closed variable must have a __close metamethod or be a false value. (nil and false are ignored as to-be-closed values.)\n\nIf several to-be-closed variables go out of scope at the same event, they are closed in the reverse order that they were declared.\n\nIf there is any error while running a closing method, that error is handled like an error in the regular code where the variable was defined. However, Lua may call the method one more time.\n\nAfter an error, the other pending closing methods will still be called. Errors in these methods interrupt the respective method and generate a warning, but are otherwise ignored; the error reported is only the original one.\n\nIf a coroutine yields and is never resumed again, some variables may never go out of scope, and therefore they will never be closed. (These variables are the ones created inside the coroutine and in scope at the point where the coroutine yielded.) Similarly, if a coroutine ends with an error, it does not unwind its stack, so it does not close any variable. In both cases, you can either use finalizers or call coroutine.close to close the variables. However, if the coroutine was created through coroutine.wrap, then its corresponding function will close the coroutine in case of errors.","name":"__close","type":"builtin","def":"__close"},{"doc":"rawset (table, index, value)\n\nSets the real value of table[index] to value, without using the __newindex metavalue. table must be a table, index any value different from nil and NaN, and value any Lua value.\n\nThis function returns table.","name":"rawset","type":"builtin","def":"rawset"},{"doc":"2.5.4 – Weak Tables\n\nA weak table is a table whose elements are weak references. A weak reference is ignored by the garbage collector. In other words, if the only references to an object are weak references, then the garbage collector will collect that object.\n\nA weak table can have weak keys, weak values, or both. A table with weak values allows the collection of its values, but prevents the collection of its keys. A table with both weak keys and weak values allows the collection of both keys and values. In any case, if either the key or the value is collected, the whole pair is removed from the table. The weakness of a table is controlled by the __mode field of its metatable. This metavalue, if present, must be one of the following strings: "k", for a table with weak keys; "v", for a table with weak values; or "kv", for a table with both weak keys and values.\n\nA table with weak keys and strong values is also called an ephemeron table. In an ephemeron table, a value is considered reachable only if its key is reachable. In particular, if the only reference to a key comes through its value, the pair is removed.\n\nAny change in the weakness of a table may take effect only at the next collect cycle. In particular, if you change the weakness to a stronger mode, Lua may still collect some items from that table before the change takes effect.\n\nOnly objects that have an explicit construction are removed from weak tables. Values, such as numbers and light C functions, are not subject to garbage collection, and therefore are not removed from weak tables (unless their associated values are collected). Although strings are subject to garbage collection, they do not have an explicit construction and their equality is by value; they behave more like values than like objects. Therefore, they are not removed from weak tables.\n\nResurrected objects (that is, objects being finalized and objects accessible only through objects being finalized) have a special behavior in weak tables. They are removed from weak values before running their finalizers, but are removed from weak keys only in the next collection after running their finalizers, when such objects are actually freed. This behavior allows the finalizer to access properties associated with the object through weak tables.\n\nIf a weak table is among the resurrected objects in a collection cycle, it may not be properly cleared until the next cycle.","name":"__mode","type":"builtin","def":"__mode"},{"doc":"rawlen (v)\n\nReturns the length of the object v, which must be a table or a string, without invoking the __len metamethod. Returns an integer.","name":"rawlen","type":"builtin","def":"rawlen"},{"doc":"ipairs (t)\n\nReturns three values (an iterator function, the table t, and 0) so that the construction\n\n~~~\n\n for i,v in ipairs(t) do body end\n\n~~~\n\nwill iterate over the key–value pairs (1,t[1]), (2,t[2]), ..., up to the first absent index.","name":"ipairs","type":"builtin","def":"ipairs"},{"doc":"2.5.3 – Garbage-Collection Metamethods\n\nYou can set garbage-collector metamethods for tables and, using the C API, for full userdata (see §2.4). These metamethods, called finalizers, are called when the garbage collector detects that the corresponding table or userdata is dead. Finalizers allow you to coordinate Lua's garbage collection with external resource management such as closing files, network or database connections, or freeing your own memory.\n\nFor an object (table or userdata) to be finalized when collected, you must mark it for finalization.\n\nYou mark an object for finalization when you set its metatable and the metatable has a field indexed by the string "__gc". Note that if you set a metatable without a __gc field and later create that field in the metatable, the object will not be marked for finalization.\n\nWhen a marked object becomes dead, it is not collected immediately by the garbage collector. Instead, Lua puts it in a list. After the collection, Lua goes through that list. For each object in the list, it checks the object's __gc metamethod: If it is present, Lua calls it with the object as its single argument.\n\nAt the end of each garbage-collection cycle, the finalizers are called in the reverse order that the objects were marked for finalization, among those collected in that cycle; that is, the first finalizer to be called is the one associated with the object marked last in the program. The execution of each finalizer may occur at any point during the execution of the regular code.\n\nBecause the object being collected must still be used by the finalizer, that object (and other objects accessible only through it) must be resurrected by Lua. Usually, this resurrection is transient, and the object memory is freed in the next garbage-collection cycle. However, if the finalizer stores the object in some global place (e.g., a global variable), then the resurrection is permanent. Moreover, if the finalizer marks a finalizing object for finalization again, its finalizer will be called again in the next cycle where the object is dead. In any case, the object memory is freed only in a GC cycle where the object is dead and not marked for finalization.\n\nWhen you close a state (see lua_close), Lua calls the finalizers of all objects marked for finalization, following the reverse order that they were marked. If any finalizer marks objects for collection during that phase, these marks have no effect.\n\nFinalizers cannot yield. Except for that, they can do anything, such as raise errors, create new objects, or even run the garbage collector. However, because they can run in unpredictable times, it is good practice to restrict each finalizer to the minimum necessary to properly release its associated resource.\n\nAny error while running a finalizer generates a warning; the error is not propagated.","name":"__gc","type":"builtin","def":"__gc"},{"doc":"rawequal (v1, v2)\n\nChecks whether v1 is equal to v2, without invoking the __eq metamethod. Returns a boolean.","name":"rawequal","type":"builtin","def":"rawequal"},{"doc":"error (message [, level])\n\nRaises an error (see §2.3) with @{message} as the error object. This function never returns.\n\nUsually, error adds some information about the error position at the beginning of the message, if the message is a string. The level argument specifies how to get the error position. With level 1 (the default), the error position is where the error function was called. Level 2 points the error to where the function that called error was called; and so on. Passing a level 0 avoids the addition of error position information to the message.","name":"error","type":"builtin","def":"error"},{"doc":"6.1 – Basic Functions\n\nThe basic library provides core functions to Lua. If you do not include this library in your application, you should check carefully whether you need to provide implementations for some of its facilities.","name":"basic","type":"builtin","def":"basic"},{"doc":"_G\n\nA global variable (not a function) that holds the global environment (see §2.2). Lua itself does not use this variable; changing its value does not affect any environment, nor vice versa.","name":"_G","type":"builtin","def":"_G"},{"doc":"luaL_newmetatable\n\n[-0, +1, m]\n\n~~~\nint luaL_newmetatable (lua_State *L, const char *tname);\n~~~\n\nIf the registry already has the key tname, returns 0. Otherwise, creates a new table to be used as a metatable for userdata, adds to this new table the pair __name = tname, adds to the registry the pair [tname] = new table, and returns 1.\n\nIn both cases, the function pushes onto the stack the final value associated with tname in the registry.","name":"__name","type":"builtin","def":"__name"},{"doc":"next (table [, index])\n\nAllows a program to traverse all fields of a table. Its first argument is a table and its second argument is an index in this table. A call to next returns the next index of the table and its associated value. When called with nil as its second argument, next returns an initial index and its associated value. When called with the last index, or with nil in an empty table, next returns nil. If the second argument is absent, then it is interpreted as nil. In particular, you can use next(t) to check whether a table is empty.\n\nThe order in which the indices are enumerated is not specified, even for numeric indices. (To traverse a table in numerical order, use a numerical for.)\n\nThe behavior of next is undefined if, during the traversal, you assign any value to a non-existent field in the table. You may however modify existing fields. In particular, you may set existing fields to nil.","name":"next","type":"builtin","def":"next"},{"doc":"dofile ([filename])\n\nOpens the named file and executes its content as a Lua chunk. When called without arguments, dofile executes the content of the standard input (stdin). Returns all values returned by the chunk. In case of errors, dofile propagates the error to its caller. (That is, dofile does not run in protected mode.)","name":"dofile","type":"builtin","def":"dofile"},{"doc":"load (chunk [, chunkname [, mode [, env]]])\n\nLoads a chunk.\n\nIf chunk is a string, the chunk is this string. If chunk is a function, load calls it repeatedly to get the chunk pieces. Each call to chunk must return a string that concatenates with previous results. A return of an empty string, nil, or no value signals the end of the chunk.\n\nIf there are no syntactic errors, load returns the compiled chunk as a function; otherwise, it returns fail plus the error message.\n\nWhen you load a main chunk, the resulting function will always have exactly one upvalue, the _ENV variable (see §2.2). However, when you load a binary chunk created from a function (see string.dump), the resulting function can have an arbitrary number of upvalues, and there is no guarantee that its first upvalue will be the _ENV variable. (A non-main function may not even have an _ENV upvalue.)\n\nRegardless, if the resulting function has any upvalues, its first upvalue is set to the value of env, if that parameter is given, or to the value of the global environment. Other upvalues are initialized with nil. All upvalues are fresh, that is, they are not shared with any other function.\n\nchunkname is used as the name of the chunk for error messages and debug information (see §4.7). When absent, it defaults to chunk, if chunk is a string, or to "=(load)" otherwise.\n\nThe string mode controls whether the chunk can be text or binary (that is, a precompiled chunk). It may be the string "b" (only binary chunks), "t" (only text chunks), or "bt" (both binary and text). The default is "bt".\n\nLua does not check the consistency of binary chunks. Maliciously crafted binary chunks can crash the interpreter.","name":"load","type":"builtin","def":"load"},{"doc":"tonumber (e [, base])\n\nWhen called with no base, tonumber tries to convert its argument to a number. If the argument is already a number or a string convertible to a number, then tonumber returns this number; otherwise, it returns fail.\n\nThe conversion of strings can result in integers or floats, according to the lexical conventions of Lua (see §3.1). The string may have leading and trailing spaces and a sign.\n\nWhen called with base, then e must be a string to be interpreted as an integer numeral in that base. The base may be any integer between 2 and 36, inclusive. In bases above 10, the letter 'A' (in either upper or lower case) represents 10, 'B' represents 11, and so forth, with 'Z' representing 35. If the string e is not a valid numeral in the given base, the function returns fail.","name":"tonumber","type":"builtin","def":"tonumber"},{"doc":"getmetatable (object)\n\nIf object does not have a metatable, returns nil. Otherwise, if the object's metatable has a __metatable field, returns the associated value. Otherwise, returns the metatable of the given object.","name":"getmetatable","type":"builtin","def":"getmetatable"},{"doc":"getmetatable (object)\n\nIf object does not have a metatable, returns nil. Otherwise, if the object's metatable has a __metatable field, returns the associated value. Otherwise, returns the metatable of the given object.","name":"__metatable","type":"builtin","def":"__metatable"},{"doc":"setmetatable (table, metatable)\n\nSets the metatable for the given table. If metatable is nil, removes the metatable of the given table. If the original metatable has a __metatable field, raises an error.\n\nThis function returns table.\n\nTo change the metatable of other types from Lua code, you must use the debug library (§6.10).","name":"setmetatable","type":"builtin","def":"setmetatable"},{"doc":"_VERSION\n\nA global variable (not a function) that holds a string containing the running Lua version. The current value of this variable is "Lua 5.4".","name":"_VERSION","type":"builtin","def":"_VERSION"},{"doc":"print (···)\n\nReceives any number of arguments and prints their values to stdout, converting each argument to a string following the same rules of tostring.\n\nThe function print is not intended for formatted output, but only as a quick way to show a value, for instance for debugging. For complete control over the output, use string.format and io.write.","name":"print","type":"builtin","def":"print"},{"doc":"collectgarbage ([opt [, arg]])\n\nThis function is a generic interface to the garbage collector. It performs different functions according to its first argument, opt:\n\n * "collect": Performs a full garbage-collection cycle. This is the default option.\n\n * "stop": Stops automatic execution of the garbage collector. The collector will run only when explicitly invoked, until a call to restart it.\n\n * "restart": Restarts automatic execution of the garbage collector.\n\n * "count": Returns the total memory in use by Lua in Kbytes. The value has a fractional part, so that it multiplied by 1024 gives the exact number of bytes in use by Lua.\n\n * "step": Performs a garbage-collection step. The step "size" is controlled by arg. With a zero value, the collector will perform one basic (indivisible) step. For non-zero values, the collector will perform as if that amount of memory (in Kbytes) had been allocated by Lua. Returns true if the step finished a collection cycle.\n\n * "isrunning": Returns a boolean that tells whether the collector is running (i.e., not stopped).\n\n * "incremental": Change the collector mode to incremental. This option can be followed by three numbers: the garbage-collector pause, the step multiplier, and the step size (see §2.5.1). A zero means to not change that value.\n\n * "generational": Change the collector mode to generational. This option can be followed by two numbers: the garbage-collector minor multiplier and the major multiplier (see §2.5.2). A zero means to not change that value.\n\nSee §2.5 for more details about garbage collection and some of these options.","name":"collectgarbage","type":"builtin","def":"collectgarbage"},{"doc":"xpcall (f, msgh [, arg1, ···])\n\nThis function is similar to pcall, except that it sets a new message handler msgh.","name":"xpcall","type":"builtin","def":"xpcall"},{"doc":"rawget (table, index)\n\nGets the real value of table[index], without using the __index metavalue. table must be a table; index may be any value.","name":"rawget","type":"builtin","def":"rawget"},{"doc":"loadfile ([filename [, mode [, env]]])\n\nSimilar to load, but gets the chunk from file filename or from the standard input, if no file name is given.","name":"loadfile","type":"builtin","def":"loadfile"},{"doc":"select (index, ···)\n\nIf index is a number, returns all arguments after argument number index; a negative number indexes from the end (-1 is the last argument). Otherwise, index must be the string \"#\", and select returns the total number of extra arguments it received.","name":"select","type":"builtin","def":"select"},{"doc":"type (v)\n\nReturns the type of its only argument, coded as a string. The possible results of this function are "nil" (a string, not the value nil), "number", "string", "boolean", "table", "function", "thread", and "userdata".","name":"type","type":"builtin","def":"type"},{"doc":"tostring (v)\n\nReceives a value of any type and converts it to a string in a human-readable format.\n\nIf the metatable of v has a __tostring field, then tostring calls the corresponding value with v as argument, and uses the result of the call as its result. Otherwise, if the metatable of v has a __name field with a string value, tostring may use that string in its final result.\n\nFor complete control of how numbers are converted, use string.format.","name":"tostring","type":"builtin","def":"tostring"},{"doc":"tostring (v)\n\nReceives a value of any type and converts it to a string in a human-readable format.\n\nIf the metatable of v has a __tostring field, then tostring calls the corresponding value with v as argument, and uses the result of the call as its result. Otherwise, if the metatable of v has a __name field with a string value, tostring may use that string in its final result.\n\nFor complete control of how numbers are converted, use string.format.","name":"__tostring","type":"builtin","def":"__tostring"},{"doc":"require (modname)\n\nLoads the given module. The function starts by looking into the package.loaded table to determine whether modname is already loaded. If it is, then require returns the value stored at package.loaded[modname]. (The absence of a second result in this case signals that this call did not have to load the module.) Otherwise, it tries to find a loader for the module.\n\nTo find a loader, require is guided by the table package.searchers. Each item in this table is a search function, that searches for the module in a particular way. By changing this table, we can change how require looks for a module. The following explanation is based on the default configuration for package.searchers.\n\nFirst require queries package.preload[modname]. If it has a value, this value (which must be a function) is the loader. Otherwise require searches for a Lua loader using the path stored in package.path. If that also fails, it searches for a C loader using the path stored in package.cpath. If that also fails, it tries an all-in-one loader (see package.searchers).\n\nOnce a loader is found, require calls the loader with two arguments: modname and an extra value, a loader data, also returned by the searcher. The loader data can be any value useful to the module; for the default searchers, it indicates where the loader was found. (For instance, if the loader came from a file, this extra value is the file path.) If the loader returns any non-nil value, require assigns the returned value to package.loaded[modname]. If the loader does not return a non-nil value and has not assigned any value to package.loaded[modname], then require assigns true to this entry. In any case, require returns the final value of package.loaded[modname]. Besides that value, require also returns as a second result the loader data returned by the searcher, which indicates how require found the module.\n\nIf there is any error loading or running the module, or if it cannot find any loader for the module, then require raises an error.","name":"require","type":"builtin","def":"require"},{"doc":"pairs (t)\n\nIf t has a metamethod __pairs, calls it with t as argument and returns the first three results from the call.\n\nOtherwise, returns three values: the next function, the table t, and nil, so that the construction\n\n~~~\n\n for k,v in pairs(t) do body end\n\n~~~\n\nwill iterate over all key–value pairs of table t.\n\nSee function next for the caveats of modifying the table during its traversal.","name":"pairs","type":"builtin","def":"pairs"},{"doc":"pairs (t)\n\nIf t has a metamethod __pairs, calls it with t as argument and returns the first three results from the call.\n\nOtherwise, returns three values: the next function, the table t, and nil, so that the construction\n\n~~~\n\n for k,v in pairs(t) do body end\n\n~~~\n\nwill iterate over all key–value pairs of table t.\n\nSee function next for the caveats of modifying the table during its traversal.","name":"__pairs","type":"builtin","def":"__pairs"},{"doc":"warn (msg1, ···)\n\nEmits a warning with a message composed by the concatenation of all its arguments (which should be strings).\n\nBy convention, a one-piece message starting with '@' is intended to be a control message, which is a message to the warning system itself. In particular, the standard warning function in Lua recognizes the control messages "@off", to stop the emission of warnings, and "@on", to (re)start the emission; it ignores unknown control messages.","name":"warn","type":"builtin","def":"warn"},{"doc":"pcall (f [, arg1, ···])\n\nCalls the function f with the given arguments in protected mode. This means that any error inside f is not propagated; instead, pcall catches the error and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. In such case, pcall also returns all results from the call, after this first result. In case of any error, pcall returns false plus the error object. Note that errors caught by pcall do not call a message handler.","name":"pcall","type":"builtin","def":"pcall"},{"doc":"assert (v [, message])\n\nRaises an error if the value of its argument v is false (i.e., nil or false); otherwise, returns all its arguments. In case of error, message is the error object; when absent, it defaults to "assertion failed!"","name":"assert","type":"builtin","def":"assert"}],"name":"lua","desc":"Lua 5.4 Documentation"},{"doc":"4 – The Application Program Interface\n\nThis section describes the C API for Lua, that is, the set of C functions available to the host program to communicate with Lua. All API functions and related types and constants are declared in the header file lua.h.\n\nEven when we use the term "function", any facility in the API may be provided as a macro instead. Except where stated otherwise, all such macros use each of their arguments exactly once (except for the first argument, which is always a Lua state), and so do not generate any hidden side-effects.\n\nAs in most C libraries, the Lua API functions do not check their arguments for validity or consistency. However, you can change this behavior by compiling Lua with the macro LUA_USE_APICHECK defined.\n\nThe Lua library is fully reentrant: it has no global variables. It keeps all information it needs in a dynamic structure, called the Lua state.\n\nEach Lua state has one or more threads, which correspond to independent, cooperative lines of execution. The type lua_State (despite its name) refers to a thread. (Indirectly, through the thread, it also refers to the Lua state associated to the thread.)\n\nA pointer to a thread must be passed as the first argument to every function in the library, except to lua_newstate, which creates a Lua state from scratch and returns a pointer to the main thread in the new state.","items":[{"doc":"lua_rawget\n\n[-1, +1, –]\n\n~~~\nint lua_rawget (lua_State *L, int index);\n~~~\n\nSimilar to lua_gettable, but does a raw access (i.e., without metamethods).","name":"lua_rawget","type":"c-api","def":"lua_rawget"},{"doc":"lua_close\n\n[-0, +0, –]\n\n~~~\nvoid lua_close (lua_State *L);\n~~~\n\nClose all active to-be-closed variables in the main thread, release all objects in the given Lua state (calling the corresponding garbage-collection metamethods, if any), and frees all dynamic memory used by this state.\n\nOn several platforms, you may not need to call this function, because all resources are naturally released when the host program ends. On the other hand, long-running programs that create multiple states, such as daemons or web servers, will probably need to close states as soon as they are not needed.","name":"lua_close","type":"c-api","def":"lua_close"},{"doc":"lua_type\n\n[-0, +0, –]\n\n~~~\nint lua_type (lua_State *L, int index);\n~~~\n\nReturns the type of the value in the given valid index, or LUA_TNONE for a non-valid but acceptable index. The types returned by lua_type are coded by the following constants defined in lua.h: LUA_TNIL, LUA_TNUMBER, LUA_TBOOLEAN, LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION, LUA_TUSERDATA, LUA_TTHREAD, and LUA_TLIGHTUSERDATA.","name":"lua_type","type":"c-api","def":"lua_type"},{"doc":"lua_istable\n\n[-0, +0, –]\n\n~~~\nint lua_istable (lua_State *L, int index);\n~~~\n\nReturns 1 if the value at the given index is a table, and 0 otherwise.","name":"lua_istable","type":"c-api","def":"lua_istable"},{"doc":"lua_call\n\n[-(nargs+1), +nresults, e]\n\n~~~\nvoid lua_call (lua_State L, int nargs, int nresults);\n~~~\n\nCalls a function. Like regular Lua calls, lua_call respects the __call metamethod. So, here the word "function" means any callable value.\n\nTo do a call you must use the following protocol: first, the function to be called is pushed onto the stack; then, the arguments to the call are pushed in direct order; that is, the first argument is pushed first. Finally you call lua_call; nargs is the number of arguments that you pushed onto the stack. When the function returns, all arguments and the function value are popped and the call results are pushed onto the stack. The number of results is adjusted to nresults, unless nresults is LUA_MULTRET. In this case, all results from the function are pushed; Lua takes care that the returned values fit into the stack space, but it does not ensure any extra space in the stack. The function results are pushed onto the stack in direct order (the first result is pushed first), so that after the call the last result is on the top of the stack.\n\nAny error while calling and running the function is propagated upwards (with a longjmp).\n\nThe following example shows how the host program can do the equivalent to this Lua code:\n\n~~~\n\n a = f("how", t.x, 14)\n\n~~~\n\nHere it is in C:\n\n~~~\n\n lua_getglobal(L, "f"); / function to be called /\n lua_pushliteral(L, "how"); / 1st argument /\n lua_getglobal(L, "t"); / table to be indexed /\n lua_getfield(L, -1, "x"); / push result of t.x (2nd arg) /\n lua_remove(L, -2); / remove 't' from the stack /\n lua_pushinteger(L, 14); / 3rd argument /\n lua_call(L, 3, 1); / call 'f' with 3 arguments and 1 result /\n lua_setglobal(L, "a"); / set global 'a' */\n\n~~~\n\nNote that the code above is balanced: at its end, the stack is back to its original configuration. This is considered good programming practice.","name":"lua_call","type":"c-api","def":"lua_call"},{"doc":"lua_compare\n\n[-0, +0, e]\n\n~~~\nint lua_compare (lua_State *L, int index1, int index2, int op);\n~~~\n\nCompares two Lua values. Returns 1 if the value at index index1 satisfies op when compared with the value at index index2, following the semantics of the corresponding Lua operator (that is, it may call metamethods). Otherwise returns 0. Also returns 0 if any of the indices is not valid.\n\nThe value of op must be one of the following constants:\n\n * LUA_OPEQ: compares for equality (==)\n * LUA_OPLT: compares for less than (<)\n * LUA_OPLE: compares for less or equal (<=)","name":"lua_compare","type":"c-api","def":"lua_compare"},{"doc":"lua_rawequal\n\n[-0, +0, –]\n\n~~~\nint lua_rawequal (lua_State *L, int index1, int index2);\n~~~\n\nReturns 1 if the two values in indices index1 and index2 are primitively equal (that is, equal without calling the __eq metamethod). Otherwise returns 0. Also returns 0 if any of the indices are not valid.","name":"lua_rawequal","type":"c-api","def":"lua_rawequal"},{"doc":"lua_replace\n\n[-1, +0, –]\n\n~~~\nvoid lua_replace (lua_State *L, int index);\n~~~\n\nMoves the top element into the given valid index without shifting any element (therefore replacing the value at that given index), and then pops the top element.","name":"lua_replace","type":"c-api","def":"lua_replace"},{"doc":"lua_isuserdata\n\n[-0, +0, –]\n\n~~~\nint lua_isuserdata (lua_State *L, int index);\n~~~\n\nReturns 1 if the value at the given index is a userdata (either full or light), and 0 otherwise.","name":"lua_isuserdata","type":"c-api","def":"lua_isuserdata"},{"doc":"luaL_checkinteger\n\n[-0, +0, v]\n\n~~~\nlua_Integer luaL_checkinteger (lua_State *L, int arg);\n~~~\n\nChecks whether the function argument arg is an integer (or can be converted to an integer) and returns this integer.","name":"luaL_checkinteger","type":"c-api","def":"luaL_checkinteger"},{"doc":"the interpreter checks for an environment variable LUA_INIT_5_4 (or LUA_INIT if the versioned name is not defined) before running any argument. If the variable content has the format @filename, then lua executes the file. Otherwise, lua executes the string itself.\n\nWhen called with the option -E, Lua does not consult any environment variables. In particular, the values of package.path and package.cpath are set with the default paths defined in luaconf.h.\n\nThe options -e, -l, and -W are handled in the order they appear. For instance, an invocation like\n\n~~~\n\n $ lua -e 'a=1' -llib1 script.lua\n\n~~~\n\nwill first set a to 1, then require the library lib1, and finally run the file script.lua with no arguments. (Here $ is the shell prompt. Your prompt may be different.)\n\nBefore running any code, lua collects all command-line arguments in a global table called arg. The script name goes to index 0, the first argument after the script name goes to index 1, and so on. Any arguments before the script name (that is, the interpreter name plus its options) go to negative indices. For instance, in the call\n\n~~~\n\n $ lua -la b.lua t1 t2\n\n~~~\n\nthe table is like this:\n\n~~~\n\n arg = { [-2] = "lua", [-1] = "-la",\n [0] = "b.lua",\n [1] = "t1", [2] = "t2" }\n\n~~~\n\nIf there is no script in the call, the interpreter name goes to index 0, followed by the other arguments. For instance, the call\n\n~~~\n\n $ lua -e "print(arg[1])"\n\n~~~\n\nwill print "-e". If there is a script, the script is called with arguments arg[1], ···, arg[#arg]. Like all chunks in Lua, the script is compiled as a vararg function.\n\nIn interactive mode, Lua repeatedly prompts and waits for a line. After reading a line, Lua first try to interpret the line as an expression. If it succeeds, it prints its value. Otherwise, it interprets the line as a statement. If you write an incomplete statement, the interpreter waits for its completion by issuing a different prompt.\n\nIf the global variable _PROMPT contains a string, then its value is used as the prompt. Similarly, if the global variable _PROMPT2 contains a string, its value is used as the secondary prompt (issued during incomplete statements).\n\nIn case of unprotected errors in the script, the interpreter reports the error to the standard error stream. If the error object is not a string but has a metamethod __tostring, the interpreter calls this metamethod to produce the final message. Otherwise, the interpreter converts the error object to a string and adds a stack traceback to it. When warnings are on, they are simply printed in the standard error output.\n\nWhen finishing normally, the interpreter closes its main Lua state (see lua_close). The script can avoid this step by calling os.exit to terminate.\n\nTo allow the use of Lua as a script interpreter in Unix systems, Lua skips the first line of a file chunk if it starts with #. Therefore, Lua scripts can be made into executable programs by using chmod +x and the #! form, as in\n\n~~~\n\n #!/usr/local/bin/lua\n\n~~~\n\nOf course, the location of the Lua interpreter may be different in your machine. If lua is in your PATH, then\n\n~~~\n\n #!/usr/bin/env lua\n\n~~~\n\nis a more portable solution.","name":"LUA_INIT_5_4","type":"c-api","def":"LUA_INIT_5_4"},{"doc":"lua_callk\n\n[-(nargs + 1), +nresults, e]\n\n~~~\nvoid lua_callk (lua_State *L,\n int nargs,\n int nresults,\n lua_KContext ctx,\n lua_KFunction k);\n~~~\n\nThis function behaves exactly like lua_call, but allows the called function to yield (see §4.5).","name":"lua_callk","type":"c-api","def":"lua_callk"},{"doc":"luaL_argerror\n\n[-0, +0, v]\n\n~~~\nint luaL_argerror (lua_State *L, int arg, const char *extramsg);\n~~~\n\nRaises an error reporting a problem with argument arg of the C function that called it, using a standard message that includes extramsg as a comment:\n\n~~~\n\n bad argument #arg to 'funcname' (extramsg)\n\n~~~\n\nThis function never returns.","name":"luaL_argerror","type":"c-api","def":"luaL_argerror"},{"doc":"luaL_Buffer\n\n~~~\ntypedef struct luaL_Buffer luaL_Buffer;\n~~~\n\nType for a string buffer.\n\nA string buffer allows C code to build Lua strings piecemeal. Its pattern of use is as follows:\n\n * First declare a variable b of type luaL_Buffer.\n\n * Then initialize it with a call luaL_buffinit(L, &b).\n\n * Then add string pieces to the buffer calling any of the luaL_add* functions.\n\n * Finish by calling luaL_pushresult(&b). This call leaves the final string on the top of the stack.\n\nIf you know beforehand the maximum size of the resulting string, you can use the buffer like this:\n\n * First declare a variable b of type luaL_Buffer.\n\n * Then initialize it and preallocate a space of size sz with a call luaL_buffinitsize(L, &b, sz).\n\n * Then produce the string into that space.\n\n * Finish by calling luaL_pushresultsize(&b, sz), where sz is the total size of the resulting string copied into that space (which may be less than or equal to the preallocated size).\n\nDuring its normal operation, a string buffer uses a variable number of stack slots. So, while using a buffer, you cannot assume that you know where the top of the stack is. You can use the stack between successive calls to buffer operations as long as that use is balanced; that is, when you call a buffer operation, the stack is at the same level it was immediately after the previous buffer operation. (The only exception to this rule is luaL_addvalue.) After calling luaL_pushresult, the stack is back to its level when the buffer was initialized, plus the final string on its top.","name":"luaL_Buffer","type":"c-api","def":"luaL_Buffer"},{"doc":"luaL_buffinitsize\n\n[-?, +?, m]\n\n~~~\nchar *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);\n~~~\n\nEquivalent to the sequence luaL_buffinit, luaL_prepbuffsize.","name":"luaL_buffinitsize","type":"c-api","def":"luaL_buffinitsize"},{"doc":"lua_register\n\n[-0, +0, e]\n\n~~~\nvoid lua_register (lua_State *L, const char *name, lua_CFunction f);\n~~~\n\nSets the C function f as the new value of global name. It is defined as a macro:\n\n~~~\n\n #define lua_register(L,n,f) \\n (lua_pushcfunction(L, f), lua_setglobal(L, n))\n\n~~~","name":"lua_register","type":"c-api","def":"lua_register"},{"doc":"lua_pushglobaltable\n\n[-0, +1, –]\n\n~~~\nvoid lua_pushglobaltable (lua_State *L);\n~~~\n\nPushes the global environment onto the stack.","name":"lua_pushglobaltable","type":"c-api","def":"lua_pushglobaltable"},{"doc":"luaL_error\n\n[-0, +0, v]\n\n~~~\nint luaL_error (lua_State *L, const char *fmt, ...);\n~~~\n\nRaises an error. The error message format is given by fmt plus any extra arguments, following the same rules of lua_pushfstring. It also adds at the beginning of the message the file name and the line number where the error occurred, if this information is available.\n\nThis function never returns, but it is an idiom to use it in C functions as return luaL_error(args).","name":"luaL_error","type":"c-api","def":"luaL_error"},{"doc":"lua_getallocf\n\n[-0, +0, –]\n\n~~~\nlua_Alloc lua_getallocf (lua_State *L, void **ud);\n~~~\n\nReturns the memory-allocation function of a given state. If ud is not NULL, Lua stores in *ud the opaque pointer given when the memory-allocator function was set.","name":"lua_getallocf","type":"c-api","def":"lua_getallocf"},{"doc":"lua_Number\n\n~~~\ntypedef ... lua_Number;\n~~~\n\nThe type of floats in Lua.\n\nBy default this type is double, but that can be changed to a single float or a long double. (See LUA_FLOAT_TYPE in luaconf.h.)","name":"lua_Number","type":"c-api","def":"lua_Number"},{"doc":"luaL_buffaddr\n\n[-0, +0, –]\n\n~~~\nchar *luaL_buffaddr (luaL_Buffer *B);\n~~~\n\nReturns the address of the current content of buffer B (see luaL_Buffer). Note that any addition to the buffer may invalidate this address.","name":"luaL_buffaddr","type":"c-api","def":"luaL_buffaddr"},{"doc":"luaL_tolstring\n\n[-0, +1, e]\n\n~~~\nconst char *luaL_tolstring (lua_State *L, int idx, size_t *len);\n~~~\n\nConverts any Lua value at the given index to a C string in a reasonable format. The resulting string is pushed onto the stack and also returned by the function. If len is not NULL, the function also sets *len with the string length.\n\nIf the value has a metatable with a __tostring field, then luaL_tolstring calls the corresponding metamethod with the value as argument, and uses the result of the call as its result.","name":"luaL_tolstring","type":"c-api","def":"luaL_tolstring"},{"doc":"lua_pushstring\n\n[-0, +1, m]\n\n~~~\nconst char *lua_pushstring (lua_State *L, const char *s);\n~~~\n\nPushes the zero-terminated string pointed to by s onto the stack. Lua will make or reuse an internal copy of the given string, so the memory at s can be freed or reused immediately after the function returns.\n\nReturns a pointer to the internal copy of the string.\n\nIf s is NULL, pushes nil and returns NULL.","name":"lua_pushstring","type":"c-api","def":"lua_pushstring"},{"doc":"lua_gethookmask\n\n[-0, +0, –]\n\n~~~\nint lua_gethookmask (lua_State *L);\n~~~\n\nReturns the current hook mask.","name":"lua_gethookmask","type":"c-api","def":"lua_gethookmask"},{"doc":"lua_pushlightuserdata\n\n[-0, +1, –]\n\n~~~\nvoid lua_pushlightuserdata (lua_State *L, void *p);\n~~~\n\nPushes a light userdata onto the stack.\n\nUserdata represent C values in Lua. A light userdata represents a pointer, a void*. It is a value (like a number): you do not create it, it has no individual metatable, and it is not collected (as it was never created). A light userdata is equal to "any" light userdata with the same C address.","name":"lua_pushlightuserdata","type":"c-api","def":"lua_pushlightuserdata"},{"doc":"lua_tolstring\n\n[-0, +0, m]\n\n~~~\nconst char *lua_tolstring (lua_State *L, int index, size_t *len);\n~~~\n\nConverts the Lua value at the given index to a C string. If len is not NULL, it sets *len with the string length. The Lua value must be a string or a number; otherwise, the function returns NULL. If the value is a number, then lua_tolstring also changes the actual value in the stack to a string. (This change confuses lua_next when lua_tolstring is applied to keys during a table traversal.)\n\nlua_tolstring returns a pointer to a string inside the Lua state. This string always has a zero ('\\0') after its last character (as in C), but can contain other zeros in its body.\n\nBecause Lua has garbage collection, there is no guarantee that the pointer returned by lua_tolstring will be valid after the corresponding Lua value is removed from the stack.","name":"lua_tolstring","type":"c-api","def":"lua_tolstring"},{"doc":"lua_Hook\n\n~~~\ntypedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);\n~~~\n\nType for debugging hook functions.\n\nWhenever a hook is called, its ar argument has its field event set to the specific event that triggered the hook. Lua identifies these events with the following constants: LUA_HOOKCALL, LUA_HOOKRET, LUA_HOOKTAILCALL, LUA_HOOKLINE, and LUA_HOOKCOUNT. Moreover, for line events, the field currentline is also set. To get the value of any other field in ar, the hook must call lua_getinfo.\n\nFor call events, event can be LUA_HOOKCALL, the normal value, or LUA_HOOKTAILCALL, for a tail call; in this case, there will be no corresponding return event.\n\nWhile Lua is running a hook, it disables other calls to hooks. Therefore, if a hook calls back Lua to execute a function or a chunk, this execution occurs without any calls to hooks.\n\nHook functions cannot have continuations, that is, they cannot call lua_yieldk, lua_pcallk, or lua_callk with a non-null k.\n\nHook functions can yield under the following conditions: Only count and line events can yield; to yield, a hook function must finish its execution calling lua_yield with nresults equal to zero (that is, with no values).","name":"lua_Hook","type":"c-api","def":"lua_Hook"},{"doc":"lua_setglobal\n\n[-1, +0, e]\n\n~~~\nvoid lua_setglobal (lua_State *L, const char *name);\n~~~\n\nPops a value from the stack and sets it as the new value of global name.","name":"lua_setglobal","type":"c-api","def":"lua_setglobal"},{"doc":"lua_settop\n\n[-?, +?, –]\n\n~~~\nvoid lua_settop (lua_State *L, int index);\n~~~\n\nAccepts any index, or 0, and sets the stack top to this index. If the new top is greater than the old one, then the new elements are filled with nil. If index is 0, then all stack elements are removed.","name":"lua_settop","type":"c-api","def":"lua_settop"},{"doc":"luaL_prepbuffsize\n\n[-?, +?, m]\n\n~~~\nchar *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);\n~~~\n\nReturns an address to a space of size sz where you can copy a string to be added to buffer B (see luaL_Buffer). After copying the string into this space you must call luaL_addsize with the size of the string to actually add it to the buffer.","name":"luaL_prepbuffsize","type":"c-api","def":"luaL_prepbuffsize"},{"doc":"lua_setiuservalue\n\n[-1, +0, –]\n\n~~~\nint lua_setiuservalue (lua_State *L, int index, int n);\n~~~\n\nPops a value from the stack and sets it as the new n-th user value associated to the full userdata at the given index. Returns 0 if the userdata does not have that value.","name":"lua_setiuservalue","type":"c-api","def":"lua_setiuservalue"},{"doc":"luaL_newmetatable\n\n[-0, +1, m]\n\n~~~\nint luaL_newmetatable (lua_State *L, const char *tname);\n~~~\n\nIf the registry already has the key tname, returns 0. Otherwise, creates a new table to be used as a metatable for userdata, adds to this new table the pair __name = tname, adds to the registry the pair [tname] = new table, and returns 1.\n\nIn both cases, the function pushes onto the stack the final value associated with tname in the registry.","name":"luaL_newmetatable","type":"c-api","def":"luaL_newmetatable"},{"doc":"luaL_where\n\n[-0, +1, m]\n\n~~~\nvoid luaL_where (lua_State *L, int lvl);\n~~~\n\nPushes onto the stack a string identifying the current position of the control at level lvl in the call stack. Typically this string has the following format:\n\n~~~\n\n chunkname:currentline:\n\n~~~\n\nLevel 0 is the running function, level 1 is the function that called the running function, etc.\n\nThis function is used to build a prefix for error messages.","name":"luaL_where","type":"c-api","def":"luaL_where"},{"doc":"lua_Writer\n\n~~~\ntypedef int (lua_Writer) (lua_State L,\n const void p,\n size_t sz,\n void ud);\n~~~\n\nThe type of the writer function used by lua_dump. Every time lua_dump produces another piece of chunk, it calls the writer, passing along the buffer to be written (p), its size (sz), and the ud parameter supplied to lua_dump.\n\nThe writer returns an error code: 0 means no errors; any other value means an error and stops lua_dump from calling the writer again.","name":"lua_Writer","type":"c-api","def":"lua_Writer"},{"doc":"lua_tostring\n\n[-0, +0, m]\n\n~~~\nconst char *lua_tostring (lua_State *L, int index);\n~~~\n\nEquivalent to lua_tolstring with len equal to NULL.","name":"lua_tostring","type":"c-api","def":"lua_tostring"},{"doc":"lua_rawset\n\n[-2, +0, m]\n\n~~~\nvoid lua_rawset (lua_State *L, int index);\n~~~\n\nSimilar to lua_settable, but does a raw assignment (i.e., without metamethods).","name":"lua_rawset","type":"c-api","def":"lua_rawset"},{"doc":"lua_gc\n\n[-0, +0, –]\n\n~~~\nint lua_gc (lua_State *L, int what, ...);\n~~~\n\nControls the garbage collector.\n\nThis function performs several tasks, according to the value of the parameter what. For options that need extra arguments, they are listed after the option.\n\n * LUA_GCCOLLECT: Performs a full garbage-collection cycle.\n\n * LUA_GCSTOP: Stops the garbage collector.\n\n * LUA_GCRESTART: Restarts the garbage collector.\n\n * LUA_GCCOUNT: Returns the current amount of memory (in Kbytes) in use by Lua.\n\n * LUA_GCCOUNTB: Returns the remainder of dividing the current amount of bytes of memory in use by Lua by 1024.\n\n * LUA_GCSTEP (int stepsize): Performs an incremental step of garbage collection, corresponding to the allocation of stepsize Kbytes.\n\n * LUA_GCISRUNNING: Returns a boolean that tells whether the collector is running (i.e., not stopped).\n\n * LUA_GCINC (int pause, int stepmul, stepsize): Changes the collector to incremental mode with the given parameters (see §2.5.1). Returns the previous mode (LUA_GCGEN or LUA_GCINC).\n\n * LUA_GCGEN (int minormul, int majormul): Changes the collector to generational mode with the given parameters (see §2.5.2). Returns the previous mode (LUA_GCGEN or LUA_GCINC).\n\nFor more details about these options, see collectgarbage.","name":"lua_gc","type":"c-api","def":"lua_gc"},{"doc":"lua_error\n\n[-1, +0, v]\n\n~~~\nint lua_error (lua_State *L);\n~~~\n\nRaises a Lua error, using the value on the top of the stack as the error object. This function does a long jump, and therefore never returns (see luaL_error).","name":"lua_error","type":"c-api","def":"lua_error"},{"doc":"luaL_checktype\n\n[-0, +0, v]\n\n~~~\nvoid luaL_checktype (lua_State *L, int arg, int t);\n~~~\n\nChecks whether the function argument arg has type t. See lua_type for the encoding of types for t.","name":"luaL_checktype","type":"c-api","def":"luaL_checktype"},{"doc":"lua_tocfunction\n\n[-0, +0, –]\n\n~~~\nlua_CFunction lua_tocfunction (lua_State *L, int index);\n~~~\n\nConverts a value at the given index to a C function. That value must be a C function; otherwise, returns NULL.","name":"lua_tocfunction","type":"c-api","def":"lua_tocfunction"},{"doc":"luaL_unref\n\n[-0, +0, –]\n\n~~~\nvoid luaL_unref (lua_State *L, int t, int ref);\n~~~\n\nReleases the reference ref from the table at index t (see luaL_ref). The entry is removed from the table, so that the referred object can be collected. The reference ref is also freed to be used again.\n\nIf ref is LUA_NOREF or LUA_REFNIL, luaL_unref does nothing.","name":"luaL_unref","type":"c-api","def":"luaL_unref"},{"doc":"luaL_typename\n\n[-0, +0, –]\n\n~~~\nconst char *luaL_typename (lua_State *L, int index);\n~~~\n\nReturns the name of the type of the value at the given index.","name":"luaL_typename","type":"c-api","def":"luaL_typename"},{"doc":"luaL_typeerror\n\n[-0, +0, v]\n\n~~~\nconst char *luaL_typeerror (lua_State *L,\n int arg,\n const char *tname);\n~~~\n\nRaises a type error for the argument arg of the C function that called it, using a standard message; tname is a "name" for the expected type. This function never returns.","name":"luaL_typeerror","type":"c-api","def":"luaL_typeerror"},{"doc":"lua_islightuserdata\n\n[-0, +0, –]\n\n~~~\nint lua_islightuserdata (lua_State *L, int index);\n~~~\n\nReturns 1 if the value at the given index is a light userdata, and 0 otherwise.","name":"lua_islightuserdata","type":"c-api","def":"lua_islightuserdata"},{"doc":"luaL_testudata\n\n[-0, +0, m]\n\n~~~\nvoid *luaL_testudata (lua_State *L, int arg, const char *tname);\n~~~\n\nThis function works like luaL_checkudata, except that, when the test fails, it returns NULL instead of raising an error.","name":"luaL_testudata","type":"c-api","def":"luaL_testudata"},{"doc":"lua_remove\n\n[-1, +0, –]\n\n~~~\nvoid lua_remove (lua_State *L, int index);\n~~~\n\nRemoves the element at the given valid index, shifting down the elements above this index to fill the gap. This function cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.","name":"lua_remove","type":"c-api","def":"lua_remove"},{"doc":"luaL_checkstring\n\n[-0, +0, v]\n\n~~~\nconst char *luaL_checkstring (lua_State *L, int arg);\n~~~\n\nChecks whether the function argument arg is a string and returns this string.\n\nThis function uses lua_tolstring to get its result, so all conversions and caveats of that function apply here.","name":"luaL_checkstring","type":"c-api","def":"luaL_checkstring"},{"doc":"lua_insert\n\n[-1, +1, –]\n\n~~~\nvoid lua_insert (lua_State *L, int index);\n~~~\n\nMoves the top element into the given valid index, shifting up the elements above this index to open space. This function cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.","name":"lua_insert","type":"c-api","def":"lua_insert"},{"doc":"lua_typename\n\n[-0, +0, –]\n\n~~~\nconst char *lua_typename (lua_State *L, int tp);\n~~~\n\nReturns the name of the type encoded by the value tp, which must be one the values returned by lua_type.","name":"lua_typename","type":"c-api","def":"lua_typename"},{"doc":"luaL_loadstring\n\n[-0, +1, –]\n\n~~~\nint luaL_loadstring (lua_State *L, const char *s);\n~~~\n\nLoads a string as a Lua chunk. This function uses lua_load to load the chunk in the zero-terminated string s.\n\nThis function returns the same results as lua_load.\n\nAlso as lua_load, this function only loads the chunk; it does not run it.","name":"luaL_loadstring","type":"c-api","def":"luaL_loadstring"},{"doc":"lua_tothread\n\n[-0, +0, –]\n\n~~~\nlua_State *lua_tothread (lua_State *L, int index);\n~~~\n\nConverts the value at the given index to a Lua thread (represented as lua_State*). This value must be a thread; otherwise, the function returns NULL.","name":"lua_tothread","type":"c-api","def":"lua_tothread"},{"doc":"lua_resume\n\n[-?, +?, –]\n\n~~~\nint lua_resume (lua_State *L, lua_State *from, int nargs,\n int *nresults);\n~~~\n\nStarts and resumes a coroutine in the given thread L.\n\nTo start a coroutine, you push the main function plus any arguments onto the empty stack of the thread. then you call lua_resume, with nargs being the number of arguments. This call returns when the coroutine suspends or finishes its execution. When it returns, *nresults is updated and the top of the stack contains the *nresults values passed to lua_yield or returned by the body function. lua_resume returns LUA_YIELD if the coroutine yields, LUA_OK if the coroutine finishes its execution without errors, or an error code in case of errors (see §4.4.1). In case of errors, the error object is on the top of the stack.\n\nTo resume a coroutine, you remove the *nresults yielded values from its stack, push the values to be passed as results from yield, and then call lua_resume.\n\nThe parameter from represents the coroutine that is resuming L. If there is no such coroutine, this parameter can be NULL.","name":"lua_resume","type":"c-api","def":"lua_resume"},{"doc":"lua_absindex\n\n[-0, +0, –]\n\n~~~\nint lua_absindex (lua_State *L, int idx);\n~~~\n\nConverts the acceptable index idx into an equivalent absolute index (that is, one that does not depend on the stack top).","name":"lua_absindex","type":"c-api","def":"lua_absindex"},{"doc":"luaL_requiref\n\n[-0, +1, e]\n\n~~~\nvoid luaL_requiref (lua_State *L, const char *modname,\n lua_CFunction openf, int glb);\n~~~\n\nIf package.loaded[modname] is not true, calls the function openf with the string modname as an argument and sets the call result to package.loaded[modname], as if that function has been called through require.\n\nIf glb is true, also stores the module into the global modname.\n\nLeaves a copy of the module on the stack.","name":"luaL_requiref","type":"c-api","def":"luaL_requiref"},{"doc":"luaL_ref\n\n[-1, +0, m]\n\n~~~\nint luaL_ref (lua_State *L, int t);\n~~~\n\nCreates and returns a reference, in the table at index t, for the object on the top of the stack (and pops the object).\n\nA reference is a unique integer key. As long as you do not manually add integer keys into the table t, luaL_ref ensures the uniqueness of the key it returns. You can retrieve an object referred by the reference r by calling lua_rawgeti(L, t, r). The function luaL_unref frees a reference.\n\nIf the object on the top of the stack is nil, luaL_ref returns the constant LUA_REFNIL. The constant LUA_NOREF is guaranteed to be different from any reference returned by luaL_ref.","name":"luaL_ref","type":"c-api","def":"luaL_ref"},{"doc":"lua_rawlen\n\n[-0, +0, –]\n\n~~~\nlua_Unsigned lua_rawlen (lua_State *L, int index);\n~~~\n\nReturns the raw "length" of the value at the given index: for strings, this is the string length; for tables, this is the result of the length operator ('#') with no metamethods; for userdata, this is the size of the block of memory allocated for the userdata. For other values, this call returns 0.","name":"lua_rawlen","type":"c-api","def":"lua_rawlen"},{"doc":"luaL_argcheck\n\n[-0, +0, v]\n\n~~~\nvoid luaL_argcheck (lua_State *L,\n int cond,\n int arg,\n const char *extramsg);\n~~~\n\nChecks whether cond is true. If it is not, raises an error with a standard message (see luaL_argerror).","name":"luaL_argcheck","type":"c-api","def":"luaL_argcheck"},{"doc":"luaL_pushresultsize\n\n[-?, +1, m]\n\n~~~\nvoid luaL_pushresultsize (luaL_Buffer *B, size_t sz);\n~~~\n\nEquivalent to the sequence luaL_addsize, luaL_pushresult.","name":"luaL_pushresultsize","type":"c-api","def":"luaL_pushresultsize"},{"doc":"lua_load\n\n[-0, +1, –]\n\n~~~\nint lua_load (lua_State *L,\n lua_Reader reader,\n void *data,\n const char *chunkname,\n const char *mode);\n~~~\n\nLoads a Lua chunk without running it. If there are no errors, lua_load pushes the compiled chunk as a Lua function on top of the stack. Otherwise, it pushes an error message.\n\nThe lua_load function uses a user-supplied reader function to read the chunk (see lua_Reader). The data argument is an opaque value passed to the reader function.\n\nThe chunkname argument gives a name to the chunk, which is used for error messages and in debug information (see §4.7).\n\nlua_load automatically detects whether the chunk is text or binary and loads it accordingly (see program luac). The string mode works as in function load, with the addition that a NULL value is equivalent to the string "bt".\n\nlua_load uses the stack internally, so the reader function must always leave the stack unmodified when returning.\n\nlua_load can return LUA_OK, LUA_ERRSYNTAX, or LUA_ERRMEM. The function may also return other values corresponding to errors raised by the read function (see §4.4.1).\n\nIf the resulting function has upvalues, its first upvalue is set to the value of the global environment stored at index LUA_RIDX_GLOBALS in the registry (see §4.3). When loading main chunks, this upvalue will be the _ENV variable (see §2.2). Other upvalues are initialized with nil.","name":"lua_load","type":"c-api","def":"lua_load"},{"doc":"lua_pushcfunction\n\n[-0, +1, –]\n\n~~~\nvoid lua_pushcfunction (lua_State *L, lua_CFunction f);\n~~~\n\nPushes a C function onto the stack. This function is equivalent to lua_pushcclosure with no upvalues.","name":"lua_pushcfunction","type":"c-api","def":"lua_pushcfunction"},{"doc":"luaL_loadfilex\n\n[-0, +1, m]\n\n~~~\nint luaL_loadfilex (lua_State *L, const char *filename,\n const char *mode);\n~~~\n\nLoads a file as a Lua chunk. This function uses lua_load to load the chunk in the file named filename. If filename is NULL, then it loads from the standard input. The first line in the file is ignored if it starts with a #.\n\nThe string mode works as in the function lua_load.\n\nThis function returns the same results as lua_load or LUA_ERRFILE for file-related errors.\n\nAs lua_load, this function only loads the chunk; it does not run it.","name":"luaL_loadfilex","type":"c-api","def":"luaL_loadfilex"},{"doc":"luaL_pushfail\n\n[-0, +1, –]\n\n~~~\nvoid luaL_pushfail (lua_State *L);\n~~~\n\nPushes the fail value onto the stack (see §6).","name":"luaL_pushfail","type":"c-api","def":"luaL_pushfail"},{"doc":"luaL_optstring\n\n[-0, +0, v]\n\n~~~\nconst char *luaL_optstring (lua_State *L,\n int arg,\n const char *d);\n~~~\n\nIf the function argument arg is a string, returns this string. If this argument is absent or is nil, returns d. Otherwise, raises an error.","name":"luaL_optstring","type":"c-api","def":"luaL_optstring"},{"doc":"luaL_Stream\n\n~~~\ntypedef struct luaL_Stream {\n FILE *f;\n lua_CFunction closef; } luaL_Stream;\n~~~\n\nThe standard representation for file handles used by the standard I/O library.\n\nA file handle is implemented as a full userdata, with a metatable called LUA_FILEHANDLE (where LUA_FILEHANDLE is a macro with the actual metatable's name). The metatable is created by the I/O library (see luaL_newmetatable).\n\nThis userdata must start with the structure luaL_Stream; it can contain other data after this initial structure. The field f points to the corresponding C stream (or it can be NULL to indicate an incompletely created handle). The field closef points to a Lua function that will be called to close the stream when the handle is closed or collected; this function receives the file handle as its sole argument and must return either a true value, in case of success, or a false value plus an error message, in case of error. Once Lua calls this field, it changes the field value to NULL to signal that the handle is closed.","name":"luaL_Stream","type":"c-api","def":"luaL_Stream"},{"doc":"luaL_optnumber\n\n[-0, +0, v]\n\n~~~\nlua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);\n~~~\n\nIf the function argument arg is a number, returns this number as a lua_Number. If this argument is absent or is nil, returns d. Otherwise, raises an error.","name":"luaL_optnumber","type":"c-api","def":"luaL_optnumber"},{"doc":"luaL_optlstring\n\n[-0, +0, v]\n\n~~~\nconst char *luaL_optlstring (lua_State *L,\n int arg,\n const char *d,\n size_t *l);\n~~~\n\nIf the function argument arg is a string, returns this string. If this argument is absent or is nil, returns d. Otherwise, raises an error.\n\nIf l is not NULL, fills its referent with the result's length. If the result is NULL (only possible when returning d and d == NULL), its length is considered zero.\n\nThis function uses lua_tolstring to get its result, so all conversions and caveats of that function apply here.","name":"luaL_optlstring","type":"c-api","def":"luaL_optlstring"},{"doc":"luaL_optinteger\n\n[-0, +0, v]\n\n~~~\nlua_Integer luaL_optinteger (lua_State *L,\n int arg,\n lua_Integer d);\n~~~\n\nIf the function argument arg is an integer (or it is convertible to an integer), returns this integer. If this argument is absent or is nil, returns d. Otherwise, raises an error.","name":"luaL_optinteger","type":"c-api","def":"luaL_optinteger"},{"doc":"luaL_opt\n\n[-0, +0, –]\n\n~~~\nT luaL_opt (L, func, arg, dflt);\n~~~\n\nThis macro is defined as follows:\n\n~~~\n\n (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))\n\n~~~\n\nIn words, if the argument arg is nil or absent, the macro results in the default dflt. Otherwise, it results in the result of calling func with the state L and the argument index arg as arguments. Note that it evaluates the expression dflt only if needed.","name":"luaL_opt","type":"c-api","def":"luaL_opt"},{"doc":"luaL_openlibs\n\n[-0, +0, e]\n\n~~~\nvoid luaL_openlibs (lua_State *L);\n~~~\n\nOpens all standard Lua libraries into the given state.","name":"luaL_openlibs","type":"c-api","def":"luaL_openlibs"},{"doc":"luaL_newstate\n\n[-0, +0, –]\n\n~~~\nlua_State *luaL_newstate (void);\n~~~\n\nCreates a new Lua state. It calls lua_newstate with an allocator based on the standard C allocation functions and then sets a warning function and a panic function (see §4.4) that print messages to the standard error output.\n\nReturns the new state, or NULL if there is a memory allocation error.","name":"luaL_newstate","type":"c-api","def":"luaL_newstate"},{"doc":"luaL_addstring\n\n[-?, +?, m]\n\n~~~\nvoid luaL_addstring (luaL_Buffer *B, const char *s);\n~~~\n\nAdds the zero-terminated string pointed to by s to the buffer B (see luaL_Buffer).","name":"luaL_addstring","type":"c-api","def":"luaL_addstring"},{"doc":"lua_setwarnf\n\n[-0, +0, –]\n\n~~~\nvoid lua_setwarnf (lua_State *L, lua_WarnFunction f, void *ud);\n~~~\n\nSets the warning function to be used by Lua to emit warnings (see lua_WarnFunction). The ud parameter sets the value ud passed to the warning function.","name":"lua_setwarnf","type":"c-api","def":"lua_setwarnf"},{"doc":"luaL_setfuncs\n\n[-nup, +0, m]\n\n~~~\nvoid luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);\n~~~\n\nRegisters all functions in the array l (see luaL_Reg) into the table on the top of the stack (below optional upvalues, see next).\n\nWhen nup is not zero, all functions are created with nup upvalues, initialized with copies of the nup values previously pushed on the stack on top of the library table. These values are popped from the stack after the registration.","name":"luaL_setfuncs","type":"c-api","def":"luaL_setfuncs"},{"doc":"luaL_pushresult\n\n[-?, +1, m]\n\n~~~\nvoid luaL_pushresult (luaL_Buffer *B);\n~~~\n\nFinishes the use of buffer B leaving the final string on the top of the stack.","name":"luaL_pushresult","type":"c-api","def":"luaL_pushresult"},{"doc":"lua_Unsigned\n\n~~~\ntypedef ... lua_Unsigned;\n~~~\n\nThe unsigned version of lua_Integer.","name":"lua_Unsigned","type":"c-api","def":"lua_Unsigned"},{"doc":"luaL_loadfile\n\n[-0, +1, m]\n\n~~~\nint luaL_loadfile (lua_State *L, const char *filename);\n~~~\n\nEquivalent to luaL_loadfilex with mode equal to NULL.","name":"luaL_loadfile","type":"c-api","def":"luaL_loadfile"},{"doc":"luaL_loadbufferx\n\n[-0, +1, –]\n\n~~~\nint luaL_loadbufferx (lua_State *L,\n const char *buff,\n size_t sz,\n const char *name,\n const char *mode);\n~~~\n\nLoads a buffer as a Lua chunk. This function uses lua_load to load the chunk in the buffer pointed to by buff with size sz.\n\nThis function returns the same results as lua_load. name is the chunk name, used for debug information and error messages. The string mode works as in the function lua_load.","name":"luaL_loadbufferx","type":"c-api","def":"luaL_loadbufferx"},{"doc":"lua_pushvalue\n\n[-0, +1, –]\n\n~~~\nvoid lua_pushvalue (lua_State *L, int index);\n~~~\n\nPushes a copy of the element at the given index onto the stack.","name":"lua_pushvalue","type":"c-api","def":"lua_pushvalue"},{"doc":"lua_isstring\n\n[-0, +0, –]\n\n~~~\nint lua_isstring (lua_State *L, int index);\n~~~\n\nReturns 1 if the value at the given index is a string or a number (which is always convertible to a string), and 0 otherwise.","name":"lua_isstring","type":"c-api","def":"lua_isstring"},{"doc":"luaL_checkudata\n\n[-0, +0, v]\n\n~~~\nvoid *luaL_checkudata (lua_State *L, int arg, const char *tname);\n~~~\n\nChecks whether the function argument arg is a userdata of the type tname (see luaL_newmetatable) and returns the userdata's memory-block address (see lua_touserdata).","name":"luaL_checkudata","type":"c-api","def":"luaL_checkudata"},{"doc":"lua_newthread\n\n[-0, +1, m]\n\n~~~\nlua_State *lua_newthread (lua_State *L);\n~~~\n\nCreates a new thread, pushes it on the stack, and returns a pointer to a lua_State that represents this new thread. The new thread returned by this function shares with the original thread its global environment, but has an independent execution stack.\n\nThreads are subject to garbage collection, like any Lua object.","name":"lua_newthread","type":"c-api","def":"lua_newthread"},{"doc":"luaL_gsub\n\n[-0, +1, m]\n\n~~~\nconst char *luaL_gsub (lua_State *L,\n const char *s,\n const char *p,\n const char *r);\n~~~\n\nCreates a copy of string s, replacing any occurrence of the string p with the string r. Pushes the resulting string on the stack and returns it.","name":"luaL_gsub","type":"c-api","def":"luaL_gsub"},{"doc":"luaL_getsubtable\n\n[-0, +1, e]\n\n~~~\nint luaL_getsubtable (lua_State *L, int idx, const char *fname);\n~~~\n\nEnsures that the value t[fname], where t is the value at index idx, is a table, and pushes that table onto the stack. Returns true if it finds a previous table there and false if it creates a new table.","name":"luaL_getsubtable","type":"c-api","def":"luaL_getsubtable"},{"doc":"luaL_getmetatable\n\n[-0, +1, m]\n\n~~~\nint luaL_getmetatable (lua_State *L, const char *tname);\n~~~\n\nPushes onto the stack the metatable associated with the name tname in the registry (see luaL_newmetatable), or nil if there is no metatable associated with that name. Returns the type of the pushed value.","name":"luaL_getmetatable","type":"c-api","def":"luaL_getmetatable"},{"doc":"luaL_getmetafield\n\n[-0, +(0|1), m]\n\n~~~\nint luaL_getmetafield (lua_State *L, int obj, const char *e);\n~~~\n\nPushes onto the stack the field e from the metatable of the object at index obj and returns the type of the pushed value. If the object does not have a metatable, or if the metatable does not have this field, pushes nothing and returns LUA_TNIL.","name":"luaL_getmetafield","type":"c-api","def":"luaL_getmetafield"},{"doc":"luaL_fileresult\n\n[-0, +(1|3), m]\n\n~~~\nint luaL_fileresult (lua_State *L, int stat, const char *fname);\n~~~\n\nThis function produces the return values for file-related functions in the standard library (io.open, os.rename, file:seek, etc.).","name":"luaL_fileresult","type":"c-api","def":"luaL_fileresult"},{"doc":"lua_CFunction\n\n~~~\ntypedef int (*lua_CFunction) (lua_State *L);\n~~~\n\nType for C functions.\n\nIn order to communicate properly with Lua, a C function must use the following protocol, which defines the way parameters and results are passed: a C function receives its arguments from Lua in its stack in direct order (the first argument is pushed first). So, when the function starts, lua_gettop(L) returns the number of arguments received by the function. The first argument (if any) is at index 1 and its last argument is at index lua_gettop(L). To return values to Lua, a C function just pushes them onto the stack, in direct order (the first result is pushed first), and returns in C the number of results. Any other value in the stack below the results will be properly discarded by Lua. Like a Lua function, a C function called by Lua can also return many results.\n\nAs an example, the following function receives a variable number of numeric arguments and returns their average and their sum:\n\n~~~\n\n static int foo (lua_State L) {\n int n = lua_gettop(L); / number of arguments /\n lua_Number sum = 0.0;\n int i;\n for (i = 1; i <= n; i++) {\n if (!lua_isnumber(L, i)) {\n lua_pushliteral(L, "incorrect argument");\n lua_error(L);\n }\n sum += lua_tonumber(L, i);\n }\n lua_pushnumber(L, sum/n); / first result /\n lua_pushnumber(L, sum); / second result /\n return 2; / number of results */\n }\n\n~~~","name":"lua_CFunction","type":"c-api","def":"lua_CFunction"},{"doc":"luaL_loadbuffer\n\n[-0, +1, –]\n\n~~~\nint luaL_loadbuffer (lua_State *L,\n const char *buff,\n size_t sz,\n const char *name);\n~~~\n\nEquivalent to luaL_loadbufferx with mode equal to NULL.","name":"luaL_loadbuffer","type":"c-api","def":"luaL_loadbuffer"},{"doc":"luaL_checkversion\n\n[-0, +0, v]\n\n~~~\nvoid luaL_checkversion (lua_State *L);\n~~~\n\nChecks whether the code making the call and the Lua library being called are using the same version of Lua and the same numeric types.","name":"luaL_checkversion","type":"c-api","def":"luaL_checkversion"},{"doc":"luaL_checkstack\n\n[-0, +0, v]\n\n~~~\nvoid luaL_checkstack (lua_State *L, int sz, const char *msg);\n~~~\n\nGrows the stack size to top + sz elements, raising an error if the stack cannot grow to that size. msg is an additional text to go into the error message (or NULL for no additional text).","name":"luaL_checkstack","type":"c-api","def":"luaL_checkstack"},{"doc":"luaL_checkoption\n\n[-0, +0, v]\n\n~~~\nint luaL_checkoption (lua_State *L,\n int arg,\n const char *def,\n const char *const lst[]);\n~~~\n\nChecks whether the function argument arg is a string and searches for this string in the array lst (which must be NULL-terminated). Returns the index in the array where the string was found. Raises an error if the argument is not a string or if the string cannot be found.\n\nIf def is not NULL, the function uses def as a default value when there is no argument arg or when this argument is nil.\n\nThis is a useful function for mapping strings to C enums. (The usual convention in Lua libraries is to use strings instead of numbers to select options.)","name":"luaL_checkoption","type":"c-api","def":"luaL_checkoption"},{"doc":"luaL_checknumber\n\n[-0, +0, v]\n\n~~~\nlua_Number luaL_checknumber (lua_State *L, int arg);\n~~~\n\nChecks whether the function argument arg is a number and returns this number converted to a lua_Number.","name":"luaL_checknumber","type":"c-api","def":"luaL_checknumber"},{"doc":"lua_isnone\n\n[-0, +0, –]\n\n~~~\nint lua_isnone (lua_State *L, int index);\n~~~\n\nReturns 1 if the given index is not valid, and 0 otherwise.","name":"lua_isnone","type":"c-api","def":"lua_isnone"},{"doc":"lua_setlocal\n\n[-(0|1), +0, –]\n\n~~~\nconst char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);\n~~~\n\nSets the value of a local variable of a given activation record. It assigns the value on the top of the stack to the variable and returns its name. It also pops the value from the stack.\n\nReturns NULL (and pops nothing) when the index is greater than the number of active local variables.\n\nParameters ar and n are as in the function lua_getlocal.","name":"lua_setlocal","type":"c-api","def":"lua_setlocal"},{"doc":"luaL_checkany\n\n[-0, +0, v]\n\n~~~\nvoid luaL_checkany (lua_State *L, int arg);\n~~~\n\nChecks whether the function has an argument of any type (including nil) at position arg.","name":"luaL_checkany","type":"c-api","def":"luaL_checkany"},{"doc":"lua_newstate\n\n[-0, +0, –]\n\n~~~\nlua_State *lua_newstate (lua_Alloc f, void *ud);\n~~~\n\nCreates a new independent state and returns its main thread. Returns NULL if it cannot create the state (due to lack of memory). The argument f is the allocator function; Lua will do all memory allocation for this state through this function (see lua_Alloc). The second argument, ud, is an opaque pointer that Lua passes to the allocator in every call.","name":"lua_newstate","type":"c-api","def":"lua_newstate"},{"doc":"luaL_buffsub\n\n[-0, +0, –]\n\n~~~\nvoid luaL_buffsub (luaL_Buffer *B, int n);\n~~~\n\nRemoves n bytes from the the buffer B (see luaL_Buffer). The buffer must have at least that many bytes.","name":"luaL_buffsub","type":"c-api","def":"luaL_buffsub"},{"doc":"luaL_bufflen\n\n[-0, +0, –]\n\n~~~\nsize_t luaL_bufflen (luaL_Buffer *B);\n~~~\n\nReturns the length of the current content of buffer B (see luaL_Buffer).","name":"luaL_bufflen","type":"c-api","def":"luaL_bufflen"},{"doc":"luaL_buffinit\n\n[-0, +0, –]\n\n~~~\nvoid luaL_buffinit (lua_State *L, luaL_Buffer *B);\n~~~\n\nInitializes a buffer B (see luaL_Buffer). This function does not allocate any space; the buffer must be declared as a variable.","name":"luaL_buffinit","type":"c-api","def":"luaL_buffinit"},{"doc":"luaL_prepbuffer\n\n[-?, +?, m]\n\n~~~\nchar *luaL_prepbuffer (luaL_Buffer *B);\n~~~\n\nEquivalent to luaL_prepbuffsize with the predefined size LUAL_BUFFERSIZE.","name":"luaL_prepbuffer","type":"c-api","def":"luaL_prepbuffer"},{"doc":"luaL_addvalue\n\n[-1, +?, m]\n\n~~~\nvoid luaL_addvalue (luaL_Buffer *B);\n~~~\n\nAdds the value on the top of the stack to the buffer B (see luaL_Buffer). Pops the value.\n\nThis is the only function on string buffers that can (and must) be called with an extra element on the stack, which is the value to be added to the buffer.","name":"luaL_addvalue","type":"c-api","def":"luaL_addvalue"},{"doc":"luaL_newlibtable\n\n[-0, +1, m]\n\n~~~\nvoid luaL_newlibtable (lua_State *L, const luaL_Reg l[]);\n~~~\n\nCreates a new table with a size optimized to store all entries in the array l (but does not actually store them). It is intended to be used in conjunction with luaL_setfuncs (see luaL_newlib).\n\nIt is implemented as a macro. The array l must be the actual array, not a pointer to it.","name":"luaL_newlibtable","type":"c-api","def":"luaL_newlibtable"},{"doc":"lua_atpanic\n\n[-0, +0, –]\n\n~~~\nlua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);\n~~~\n\nSets a new panic function and returns the old one (see §4.4).","name":"lua_atpanic","type":"c-api","def":"lua_atpanic"},{"doc":"luaL_addlstring\n\n[-?, +?, m]\n\n~~~\nvoid luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);\n~~~\n\nAdds the string pointed to by s with length l to the buffer B (see luaL_Buffer). The string can contain embedded zeros.","name":"luaL_addlstring","type":"c-api","def":"luaL_addlstring"},{"doc":"luaL_addgsub\n\n[-0, +0, m]\n\n~~~\nconst void luaL_addgsub (luaL_Buffer *B, const char *s,\n const char *p, const char *r);\n~~~\n\nAdds a copy of the string s to the buffer B (see luaL_Buffer), replacing any occurrence of the string p with the string r.","name":"luaL_addgsub","type":"c-api","def":"luaL_addgsub"},{"doc":"luaL_addchar\n\n[-?, +?, m]\n\n~~~\nvoid luaL_addchar (luaL_Buffer *B, char c);\n~~~\n\nAdds the byte c to the buffer B (see luaL_Buffer).","name":"luaL_addchar","type":"c-api","def":"luaL_addchar"},{"doc":"luaL_argexpected\n\n[-0, +0, v]\n\n~~~\nvoid luaL_argexpected (lua_State *L,\n int cond,\n int arg,\n const char *tname);\n~~~\n\nChecks whether cond is true. If it is not, raises an error about the type of the argument arg with a standard message (see luaL_typeerror).","name":"luaL_argexpected","type":"c-api","def":"luaL_argexpected"},{"doc":"lua_pushvfstring\n\n[-0, +1, v]\n\n~~~\nconst char *lua_pushvfstring (lua_State *L,\n const char *fmt,\n va_list argp);\n~~~\n\nEquivalent to lua_pushfstring, except that it receives a va_list instead of a variable number of arguments.","name":"lua_pushvfstring","type":"c-api","def":"lua_pushvfstring"},{"doc":"the value of the environment variable LUA_PATH_5_4 or the environment variable LUA_PATH or with a default path defined in luaconf.h, if those environment variables are not defined. A ";;" in the value of the environment variable is replaced by the default path.","name":"LUA_PATH_5_4","type":"c-api","def":"LUA_PATH_5_4"},{"doc":"lua_resetthread\n\n[-0, +?, –]\n\n~~~\nint lua_resetthread (lua_State *L);\n~~~\n\nResets a thread, cleaning its call stack and closing all pending to-be-closed variables. Returns a status code: LUA_OK for no errors in closing methods, or an error status otherwise. In case of error, leaves the error object on the top of the stack,","name":"lua_resetthread","type":"c-api","def":"lua_resetthread"},{"doc":"lua_pushthread\n\n[-0, +1, –]\n\n~~~\nint lua_pushthread (lua_State *L);\n~~~\n\nPushes the thread represented by L onto the stack. Returns 1 if this thread is the main thread of its state.","name":"lua_pushthread","type":"c-api","def":"lua_pushthread"},{"doc":"lua_yield\n\n[-?, +?, v]\n\n~~~\nint lua_yield (lua_State *L, int nresults);\n~~~\n\nThis function is equivalent to lua_yieldk, but it has no continuation (see §4.5). Therefore, when the thread resumes, it continues the function that called the function calling lua_yield. To avoid surprises, this function should be called only in a tail call.","name":"lua_yield","type":"c-api","def":"lua_yield"},{"doc":"lua_xmove\n\n[-?, +?, –]\n\n~~~\nvoid lua_xmove (lua_State *from, lua_State *to, int n);\n~~~\n\nExchange values between different threads of the same state.\n\nThis function pops n values from the stack from, and pushes them onto the stack to.","name":"lua_xmove","type":"c-api","def":"lua_xmove"},{"doc":"lua_newuserdatauv\n\n[-0, +1, m]\n\n~~~\nvoid *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);\n~~~\n\nThis function creates and pushes on the stack a new full userdata, with nuvalue associated Lua values, called user values, plus an associated block of raw memory with size bytes. (The user values can be set and read with the functions lua_setiuservalue and lua_getiuservalue.)\n\nThe function returns the address of the block of memory.","name":"lua_newuserdatauv","type":"c-api","def":"lua_newuserdatauv"},{"doc":"lua_warning\n\n[-0, +0, –]\n\n~~~\nvoid lua_warning (lua_State *L, const char *msg, int tocont);\n~~~\n\nEmits a warning with the given message. A message in a call with tocont true should be continued in another call to this function.\n\nSee warn for more details about warnings.","name":"lua_warning","type":"c-api","def":"lua_warning"},{"doc":"lua_version\n\n[-0, +0, –]\n\n~~~\nlua_Number lua_version (lua_State *L);\n~~~\n\nReturns the version number of this core.","name":"lua_version","type":"c-api","def":"lua_version"},{"doc":"lua_next\n\n[-1, +(2|0), v]\n\n~~~\nint lua_next (lua_State L, int index);\n~~~\n\nPops a key from the stack, and pushes a key–value pair from the table at the given index, the "next" pair after the given key. If there are no more elements in the table, then lua_next returns 0 and pushes nothing.\n\nA typical table traversal looks like this:\n\n~~~\n\n / table is in the stack at index 't' /\n lua_pushnil(L); / first key /\n while (lua_next(L, t) != 0) {\n / uses 'key' (at index -2) and 'value' (at index -1) /\n printf("%s - %s\n",\n lua_typename(L, lua_type(L, -2)),\n lua_typename(L, lua_type(L, -1)));\n / removes 'value'; keeps 'key' for next iteration */\n lua_pop(L, 1);\n }\n\n~~~\n\nWhile traversing a table, avoid calling lua_tolstring directly on a key, unless you know that the key is actually a string. Recall that lua_tolstring may change the value at the given index; this confuses the next call to lua_next.\n\nThis function may raise an error if the given key is neither nil nor present in the table. See function next for the caveats of modifying the table during its traversal.","name":"lua_next","type":"c-api","def":"lua_next"},{"doc":"lua_settable\n\n[-2, +0, e]\n\n~~~\nvoid lua_settable (lua_State *L, int index);\n~~~\n\nDoes the equivalent to t[k] = v, where t is the value at the given index, v is the value on the top of the stack, and k is the value just below the top.\n\nThis function pops both the key and the value from the stack. As in Lua, this function may trigger a metamethod for the "newindex" event (see §2.4).","name":"lua_settable","type":"c-api","def":"lua_settable"},{"doc":"lua_upvalueindex\n\n[-0, +0, –]\n\n~~~\nint lua_upvalueindex (int i);\n~~~\n\nReturns the pseudo-index that represents the i-th upvalue of the running function (see §4.2). i must be in the range [1,256].","name":"lua_upvalueindex","type":"c-api","def":"lua_upvalueindex"},{"doc":"lua_touserdata\n\n[-0, +0, –]\n\n~~~\nvoid *lua_touserdata (lua_State *L, int index);\n~~~\n\nIf the value at the given index is a full userdata, returns its memory-block address. If the value is a light userdata, returns its value (a pointer). Otherwise, returns NULL.","name":"lua_touserdata","type":"c-api","def":"lua_touserdata"},{"doc":"lua_topointer\n\n[-0, +0, –]\n\n~~~\nconst void *lua_topointer (lua_State *L, int index);\n~~~\n\nConverts the value at the given index to a generic C pointer (void*). The value can be a userdata, a table, a thread, a string, or a function; otherwise, lua_topointer returns NULL. Different objects will give different pointers. There is no way to convert the pointer back to its original value.\n\nTypically this function is used only for hashing and debug information.","name":"lua_topointer","type":"c-api","def":"lua_topointer"},{"doc":"lua_tonumberx\n\n[-0, +0, –]\n\n~~~\nlua_Number lua_tonumberx (lua_State *L, int index, int *isnum);\n~~~\n\nConverts the Lua value at the given index to the C type lua_Number (see lua_Number). The Lua value must be a number or a string convertible to a number (see §3.4.3); otherwise, lua_tonumberx returns 0.\n\nIf isnum is not NULL, its referent is assigned a boolean value that indicates whether the operation succeeded.","name":"lua_tonumberx","type":"c-api","def":"lua_tonumberx"},{"doc":"lua_tointegerx\n\n[-0, +0, –]\n\n~~~\nlua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);\n~~~\n\nConverts the Lua value at the given index to the signed integral type lua_Integer. The Lua value must be an integer, or a number or string convertible to an integer (see §3.4.3); otherwise, lua_tointegerx returns 0.\n\nIf isnum is not NULL, its referent is assigned a boolean value that indicates whether the operation succeeded.","name":"lua_tointegerx","type":"c-api","def":"lua_tointegerx"},{"doc":"lua_Debug\n\n~~~\ntypedef struct lua_Debug {\n int event;\n const char name; / (n) */\n const char namewhat; / (n) */\n const char what; / (S) */\n const char source; / (S) /\n size_t srclen; / (S) /\n int currentline; / (l) /\n int linedefined; / (S) /\n int lastlinedefined; / (S) /\n unsigned char nups; / (u) number of upvalues /\n unsigned char nparams; / (u) number of parameters /\n char isvararg; / (u) /\n char istailcall; / (t) /\n unsigned short ftransfer; / (r) index of first value transferred /\n unsigned short ntransfer; / (r) number of transferred values /\n char short_src[LUA_IDSIZE]; / (S) /\n / private part */\n other fields } lua_Debug;\n~~~\n\nA structure used to carry different pieces of information about a function or an activation record. lua_getstack fills only the private part of this structure, for later use. To fill the other fields of lua_Debug with useful information, you must call lua_getinfo.\n\nThe fields of lua_Debug have the following meaning:\n\n * source: the source of the chunk that created the function. If source starts with a '@', it means that the function was defined in a file where the file name follows the '@'. If source starts with a '=', the remainder of its contents describes the source in a user-dependent manner. Otherwise, the function was defined in a string where source is that string.\n\n * srclen: The length of the string source.\n\n * short_src: a "printable" version of source, to be used in error messages.\n\n * linedefined: the line number where the definition of the function starts.\n\n * lastlinedefined: the line number where the definition of the function ends.\n\n * what: the string \"Lua\" if the function is a Lua function, \"C\" if it is a C function, \"main\" if it is the main part of a chunk.\n\n * currentline: the current line where the given function is executing. When no line information is available, currentline is set to -1.\n\n * name: a reasonable name for the given function. Because functions in Lua are first-class values, they do not have a fixed name: some functions can be the value of multiple global variables, while others can be stored only in a table field. The lua_getinfo function checks how the function was called to find a suitable name. If it cannot find a name, then name is set to NULL.\n\n * namewhat: explains the name field. The value of namewhat can be \"global\", \"local\", \"method\", \"field\", \"upvalue\", or \"\" (the empty string), according to how the function was called. (Lua uses the empty string when no other option seems to apply.)\n\n * istailcall: true if this function invocation was called by a tail call. In this case, the caller of this level is not in the stack.\n\n * nups: the number of upvalues of the function.\n\n * nparams: the number of parameters of the function (always 0 for C functions).\n\n * isvararg: true if the function is a vararg function (always true for C functions).\n\n * ftransfer: the index on the stack of the first value being "transferred", that is, parameters in a call or return values in a return. (The other values are in consecutive indices.) Using this index, you can access and modify these values through lua_getlocal and lua_setlocal. This field is only meaningful during a call hook, denoting the first parameter, or a return hook, denoting the first value being returned. (For call hooks, this value is always 1.)\n\n * ntransfer: The number of values being transferred (see previous item). (For calls of Lua functions, this value is always equal to nparams.)","name":"lua_Debug","type":"c-api","def":"lua_Debug"},{"doc":"lua_tointeger\n\n[-0, +0, –]\n\n~~~\nlua_Integer lua_tointeger (lua_State *L, int index);\n~~~\n\nEquivalent to lua_tointegerx with isnum equal to NULL.","name":"lua_tointeger","type":"c-api","def":"lua_tointeger"},{"doc":"lua_dump\n\n[-0, +0, –]\n\n~~~\nint lua_dump (lua_State *L,\n lua_Writer writer,\n void *data,\n int strip);\n~~~\n\nDumps a function as a binary chunk. Receives a Lua function on the top of the stack and produces a binary chunk that, if loaded again, results in a function equivalent to the one dumped. As it produces parts of the chunk, lua_dump calls function writer (see lua_Writer) with the given data to write them.\n\nIf strip is true, the binary representation may not include all debug information about the function, to save space.\n\nThe value returned is the error code returned by the last call to the writer; 0 means no errors.\n\nThis function does not pop the Lua function from the stack.","name":"lua_dump","type":"c-api","def":"lua_dump"},{"doc":"lua_toboolean\n\n[-0, +0, –]\n\n~~~\nint lua_toboolean (lua_State *L, int index);\n~~~\n\nConverts the Lua value at the given index to a C boolean value (0 or 1). Like all tests in Lua, lua_toboolean returns true for any Lua value different from false and nil; otherwise it returns false. (If you want to accept only actual boolean values, use lua_isboolean to test the value's type.)","name":"lua_toboolean","type":"c-api","def":"lua_toboolean"},{"doc":"lua_stringtonumber\n\n[-0, +1, –]\n\n~~~\nsize_t lua_stringtonumber (lua_State *L, const char *s);\n~~~\n\nConverts the zero-terminated string s to a number, pushes that number into the stack, and returns the total size of the string, that is, its length plus one. The conversion can result in an integer or a float, according to the lexical conventions of Lua (see §3.1). The string may have leading and trailing whitespaces and a sign. If the string is not a valid numeral, returns 0 and pushes nothing. (Note that the result can be used as a boolean, true if the conversion succeeds.)","name":"lua_stringtonumber","type":"c-api","def":"lua_stringtonumber"},{"doc":"lua_concat\n\n[-n, +1, e]\n\n~~~\nvoid lua_concat (lua_State *L, int n);\n~~~\n\nConcatenates the n values at the top of the stack, pops them, and leaves the result on the top. If n is 1, the result is the single value on the stack (that is, the function does nothing); if n is 0, the result is the empty string. Concatenation is performed following the usual semantics of Lua (see §3.4.6).","name":"lua_concat","type":"c-api","def":"lua_concat"},{"doc":"lua_status\n\n[-0, +0, –]\n\n~~~\nint lua_status (lua_State *L);\n~~~\n\nReturns the status of the thread L.\n\nThe status can be LUA_OK for a normal thread, an error code if the thread finished the execution of a lua_resume with an error, or LUA_YIELD if the thread is suspended.\n\nYou can call functions only in threads with status LUA_OK. You can resume threads with status LUA_OK (to start a new coroutine) or LUA_YIELD (to resume a coroutine).","name":"lua_status","type":"c-api","def":"lua_status"},{"doc":"luaL_newlib\n\n[-0, +1, m]\n\n~~~\nvoid luaL_newlib (lua_State *L, const luaL_Reg l[]);\n~~~\n\nCreates a new table and registers there the functions in the list l.\n\nIt is implemented as the following macro:\n\n~~~\n\n (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))\n\n~~~\n\nThe array l must be the actual array, not a pointer to it.","name":"luaL_newlib","type":"c-api","def":"luaL_newlib"},{"doc":"lua_geti\n\n[-0, +1, e]\n\n~~~\nint lua_geti (lua_State *L, int index, lua_Integer i);\n~~~\n\nPushes onto the stack the value t[i], where t is the value at the given index. As in Lua, this function may trigger a metamethod for the "index" event (see §2.4).\n\nReturns the type of the pushed value.","name":"lua_geti","type":"c-api","def":"lua_geti"},{"doc":"lua_isnoneornil\n\n[-0, +0, –]\n\n~~~\nint lua_isnoneornil (lua_State *L, int index);\n~~~\n\nReturns 1 if the given index is not valid or if the value at this index is nil, and 0 otherwise.","name":"lua_isnoneornil","type":"c-api","def":"lua_isnoneornil"},{"doc":"lua_setmetatable\n\n[-1, +0, –]\n\n~~~\nint lua_setmetatable (lua_State *L, int index);\n~~~\n\nPops a table or nil from the stack and sets that value as the new metatable for the value at the given index. (nil means no metatable.)\n\n(For historical reasons, this function returns an int, which now is always 1.)","name":"lua_setmetatable","type":"c-api","def":"lua_setmetatable"},{"doc":"lua_seti\n\n[-1, +0, e]\n\n~~~\nvoid lua_seti (lua_State *L, int index, lua_Integer n);\n~~~\n\nDoes the equivalent to t[n] = v, where t is the value at the given index and v is the value on the top of the stack.\n\nThis function pops the value from the stack. As in Lua, this function may trigger a metamethod for the "newindex" event (see §2.4).","name":"lua_seti","type":"c-api","def":"lua_seti"},{"doc":"lua_sethook\n\n[-0, +0, –]\n\n~~~\nvoid lua_sethook (lua_State *L, lua_Hook f, int mask, int count);\n~~~\n\nSets the debugging hook function.\n\nArgument f is the hook function. mask specifies on which events the hook will be called: it is formed by a bitwise OR of the constants LUA_MASKCALL, LUA_MASKRET, LUA_MASKLINE, and LUA_MASKCOUNT. The count argument is only meaningful when the mask includes LUA_MASKCOUNT. For each event, the hook is called as explained below:\n\n * The call hook: is called when the interpreter calls a function. The hook is called just after Lua enters the new function, before the function gets its arguments.\n\n * The return hook: is called when the interpreter returns from a function. The hook is called just before Lua leaves the function.\n\n * The line hook: is called when the interpreter is about to start the execution of a new line of code, or when it jumps back in the code (even to the same line). This event only happens while Lua is executing a Lua function.\n\n * The count hook: is called after the interpreter executes every count instructions. This event only happens while Lua is executing a Lua function.\n\nHooks are disabled by setting mask to zero.","name":"lua_sethook","type":"c-api","def":"lua_sethook"},{"doc":"lua_upvalueid\n\n[-0, +0, –]\n\n~~~\nvoid *lua_upvalueid (lua_State *L, int funcindex, int n);\n~~~\n\nReturns a unique identifier for the upvalue numbered n from the closure at index funcindex.\n\nThese unique identifiers allow a program to check whether different closures share upvalues. Lua closures that share an upvalue (that is, that access a same external local variable) will return identical ids for those upvalue indices.\n\nParameters funcindex and n are as in the function lua_getupvalue, but n cannot be greater than the number of upvalues.","name":"lua_upvalueid","type":"c-api","def":"lua_upvalueid"},{"doc":"lua_setcstacklimit\n\n[-0, +0, –]\n\n~~~\nint (lua_setcstacklimit) (lua_State *L, unsigned int limit);\n~~~\n\nSets a new limit for the C stack. This limit controls how deeply nested calls can go in Lua, with the intent of avoiding a stack overflow. Returns the old limit in case of success, or zero in case of error. For more details about this function, see debug.setcstacklimit, its equivalent in the standard library.","name":"lua_setcstacklimit","type":"c-api","def":"lua_setcstacklimit"},{"doc":"lua_setallocf\n\n[-0, +0, –]\n\n~~~\nvoid lua_setallocf (lua_State *L, lua_Alloc f, void *ud);\n~~~\n\nChanges the allocator function of a given state to f with user data ud.","name":"lua_setallocf","type":"c-api","def":"lua_setallocf"},{"doc":"lua_getiuservalue\n\n[-0, +1, –]\n\n~~~\nint lua_getiuservalue (lua_State *L, int index, int n);\n~~~\n\nPushes onto the stack the n-th user value associated with the full userdata at the given index and returns the type of the pushed value.\n\nIf the userdata does not have that value, pushes nil and returns LUA_TNONE.","name":"lua_getiuservalue","type":"c-api","def":"lua_getiuservalue"},{"doc":"lua_pushliteral\n\n[-0, +1, m]\n\n~~~\nconst char *lua_pushliteral (lua_State *L, const char *s);\n~~~\n\nThis macro is equivalent to lua_pushstring, but should be used only when s is a literal string. (Lua may optimize this case.)","name":"lua_pushliteral","type":"c-api","def":"lua_pushliteral"},{"doc":"lua_isfunction\n\n[-0, +0, –]\n\n~~~\nint lua_isfunction (lua_State *L, int index);\n~~~\n\nReturns 1 if the value at the given index is a function (either C or Lua), and 0 otherwise.","name":"lua_isfunction","type":"c-api","def":"lua_isfunction"},{"doc":"lua_rotate\n\n[-0, +0, –]\n\n~~~\nvoid lua_rotate (lua_State *L, int idx, int n);\n~~~\n\nRotates the stack elements between the valid index idx and the top of the stack. The elements are rotated n positions in the direction of the top, for a positive n, or -n positions in the direction of the bottom, for a negative n. The absolute value of n must not be greater than the size of the slice being rotated. This function cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.","name":"lua_rotate","type":"c-api","def":"lua_rotate"},{"doc":"luaL_setmetatable\n\n[-0, +0, –]\n\n~~~\nvoid luaL_setmetatable (lua_State *L, const char *tname);\n~~~\n\nSets the metatable of the object on the top of the stack as the metatable associated with name tname in the registry (see luaL_newmetatable).","name":"luaL_setmetatable","type":"c-api","def":"luaL_setmetatable"},{"doc":"luaL_execresult\n\n[-0, +3, m]\n\n~~~\nint luaL_execresult (lua_State *L, int stat);\n~~~\n\nThis function produces the return values for process-related functions in the standard library (os.execute and io.close).","name":"luaL_execresult","type":"c-api","def":"luaL_execresult"},{"doc":"lua_getfield\n\n[-0, +1, e]\n\n~~~\nint lua_getfield (lua_State *L, int index, const char *k);\n~~~\n\nPushes onto the stack the value t[k], where t is the value at the given index. As in Lua, this function may trigger a metamethod for the "index" event (see §2.4).\n\nReturns the type of the pushed value.","name":"lua_getfield","type":"c-api","def":"lua_getfield"},{"doc":"lua_rawseti\n\n[-1, +0, m]\n\n~~~\nvoid lua_rawseti (lua_State *L, int index, lua_Integer i);\n~~~\n\nDoes the equivalent of t[i] = v, where t is the table at the given index and v is the value on the top of the stack.\n\nThis function pops the value from the stack. The assignment is raw, that is, it does not use the __newindex metavalue.","name":"lua_rawseti","type":"c-api","def":"lua_rawseti"},{"doc":"lua_rawgetp\n\n[-0, +1, –]\n\n~~~\nint lua_rawgetp (lua_State *L, int index, const void *p);\n~~~\n\nPushes onto the stack the value t[k], where t is the table at the given index and k is the pointer p represented as a light userdata. The access is raw; that is, it does not use the __index metavalue.\n\nReturns the type of the pushed value.","name":"lua_rawgetp","type":"c-api","def":"lua_rawgetp"},{"doc":"lua_rawgeti\n\n[-0, +1, –]\n\n~~~\nint lua_rawgeti (lua_State *L, int index, lua_Integer n);\n~~~\n\nPushes onto the stack the value t[n], where t is the table at the given index. The access is raw, that is, it does not use the __index metavalue.\n\nReturns the type of the pushed value.","name":"lua_rawgeti","type":"c-api","def":"lua_rawgeti"},{"doc":"lua_Reader\n\n~~~\ntypedef const char * (*lua_Reader) (lua_State *L,\n void *data,\n size_t *size);\n~~~\n\nThe reader function used by lua_load. Every time lua_load needs another piece of the chunk, it calls the reader, passing along its data parameter. The reader must return a pointer to a block of memory with a new piece of the chunk and set size to the block size. The block must exist until the reader function is called again. To signal the end of the chunk, the reader must return NULL or set size to zero. The reader function may return pieces of any size greater than zero.","name":"lua_Reader","type":"c-api","def":"lua_Reader"},{"doc":"lua_Integer\n\n~~~\ntypedef ... lua_Integer;\n~~~\n\nThe type of integers in Lua.\n\nBy default this type is long long, (usually a 64-bit two-complement integer), but that can be changed to long or int (usually a 32-bit two-complement integer). (See LUA_INT_TYPE in luaconf.h.)\n\nLua also defines the constants LUA_MININTEGER and LUA_MAXINTEGER, with the minimum and the maximum values that fit in this type.","name":"lua_Integer","type":"c-api","def":"lua_Integer"},{"doc":"luaL_Reg\n\n~~~\ntypedef struct luaL_Reg {\n const char *name;\n lua_CFunction func; } luaL_Reg;\n~~~\n\nType for arrays of functions to be registered by luaL_setfuncs. name is the function name and func is a pointer to the function. Any array of luaL_Reg must end with a sentinel entry in which both name and func are NULL.","name":"luaL_Reg","type":"c-api","def":"luaL_Reg"},{"doc":"lua_yieldk\n\n[-?, +?, v]\n\n~~~\nint lua_yieldk (lua_State *L,\n int nresults,\n lua_KContext ctx,\n lua_KFunction k);\n~~~\n\nYields a coroutine (thread).\n\nWhen a C function calls lua_yieldk, the running coroutine suspends its execution, and the call to lua_resume that started this coroutine returns. The parameter nresults is the number of values from the stack that will be passed as results to lua_resume.\n\nWhen the coroutine is resumed again, Lua calls the given continuation function k to continue the execution of the C function that yielded (see §4.5). This continuation function receives the same stack from the previous function, with the n results removed and replaced by the arguments passed to lua_resume. Moreover, the continuation function receives the value ctx that was passed to lua_yieldk.\n\nUsually, this function does not return; when the coroutine eventually resumes, it continues executing the continuation function. However, there is one special case, which is when this function is called from inside a line or a count hook (see §4.7). In that case, lua_yieldk should be called with no continuation (probably in the form of lua_yield) and no results, and the hook should return immediately after the call. Lua will yield and, when the coroutine resumes again, it will continue the normal execution of the (Lua) function that triggered the hook.\n\nThis function can raise an error if it is called from a thread with a pending C call with no continuation function (what is called a C-call boundary), or it is called from a thread that is not running inside a resume (typically the main thread).","name":"lua_yieldk","type":"c-api","def":"lua_yieldk"},{"doc":"lua_WarnFunction\n\n~~~\ntypedef void (*lua_WarnFunction) (void *ud, const char *msg, int tocont);\n~~~\n\nThe type of warning functions, called by Lua to emit warnings. The first parameter is an opaque pointer set by lua_setwarnf. The second parameter is the warning message. The third parameter is a boolean that indicates whether the message is to be continued by the message in the next call.\n\nSee warn for more details about warnings.","name":"lua_WarnFunction","type":"c-api","def":"lua_WarnFunction"},{"doc":"lua_isyieldable\n\n[-0, +0, –]\n\n~~~\nint lua_isyieldable (lua_State *L);\n~~~\n\nReturns 1 if the given coroutine can yield, and 0 otherwise.","name":"lua_isyieldable","type":"c-api","def":"lua_isyieldable"},{"doc":"lua_pushnil\n\n[-0, +1, –]\n\n~~~\nvoid lua_pushnil (lua_State *L);\n~~~\n\nPushes a nil value onto the stack.","name":"lua_pushnil","type":"c-api","def":"lua_pushnil"},{"doc":"lua_pushinteger\n\n[-0, +1, –]\n\n~~~\nvoid lua_pushinteger (lua_State *L, lua_Integer n);\n~~~\n\nPushes an integer with value n onto the stack.","name":"lua_pushinteger","type":"c-api","def":"lua_pushinteger"},{"doc":"lua_pushcclosure\n\n[-n, +1, m]\n\n~~~\nvoid lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);\n~~~\n\nPushes a new C closure onto the stack. This function receives a pointer to a C function and pushes onto the stack a Lua value of type function that, when called, invokes the corresponding C function. The parameter n tells how many upvalues this function will have (see §4.2).\n\nAny function to be callable by Lua must follow the correct protocol to receive its parameters and return its results (see lua_CFunction).\n\nWhen a C function is created, it is possible to associate some values with it, the so called upvalues; these upvalues are then accessible to the function whenever it is called. This association is called a C closure (see §4.2). To create a C closure, first the initial values for its upvalues must be pushed onto the stack. (When there are multiple upvalues, the first value is pushed first.) Then lua_pushcclosure is called to create and push the C function onto the stack, with the argument n telling how many values will be associated with the function. lua_pushcclosure also pops these values from the stack.\n\nThe maximum value for n is 255.\n\nWhen n is zero, this function creates a light C function, which is just a pointer to the C function. In that case, it never raises a memory error.","name":"lua_pushcclosure","type":"c-api","def":"lua_pushcclosure"},{"doc":"lua_gethookcount\n\n[-0, +0, –]\n\n~~~\nint lua_gethookcount (lua_State *L);\n~~~\n\nReturns the current hook count.","name":"lua_gethookcount","type":"c-api","def":"lua_gethookcount"},{"doc":"lua_pushboolean\n\n[-0, +1, –]\n\n~~~\nvoid lua_pushboolean (lua_State *L, int b);\n~~~\n\nPushes a boolean value with value b onto the stack.","name":"lua_pushboolean","type":"c-api","def":"lua_pushboolean"},{"doc":"lua_pop\n\n[-n, +0, –]\n\n~~~\nvoid lua_pop (lua_State *L, int n);\n~~~\n\nPops n elements from the stack.","name":"lua_pop","type":"c-api","def":"lua_pop"},{"doc":"lua_pcallk\n\n[-(nargs + 1), +(nresults|1), –]\n\n~~~\nint lua_pcallk (lua_State *L,\n int nargs,\n int nresults,\n int msgh,\n lua_KContext ctx,\n lua_KFunction k);\n~~~\n\nThis function behaves exactly like lua_pcall, except that it allows the called function to yield (see §4.5).","name":"lua_pcallk","type":"c-api","def":"lua_pcallk"},{"doc":"lua_pcall\n\n[-(nargs + 1), +(nresults|1), –]\n\n~~~\nint lua_pcall (lua_State *L, int nargs, int nresults, int msgh);\n~~~\n\nCalls a function (or a callable object) in protected mode.\n\nBoth nargs and nresults have the same meaning as in lua_call. If there are no errors during the call, lua_pcall behaves exactly like lua_call. However, if there is any error, lua_pcall catches it, pushes a single value on the stack (the error object), and returns an error code. Like lua_call, lua_pcall always removes the function and its arguments from the stack.\n\nIf msgh is 0, then the error object returned on the stack is exactly the original error object. Otherwise, msgh is the stack index of a message handler. (This index cannot be a pseudo-index.) In case of runtime errors, this handler will be called with the error object and its return value will be the object returned on the stack by lua_pcall.\n\nTypically, the message handler is used to add more debug information to the error object, such as a stack traceback. Such information cannot be gathered after the return of lua_pcall, since by then the stack has unwound.\n\nThe lua_pcall function returns one of the following status codes: LUA_OK, LUA_ERRRUN, LUA_ERRMEM, or LUA_ERRERR.","name":"lua_pcall","type":"c-api","def":"lua_pcall"},{"doc":"lua_gettable\n\n[-1, +1, e]\n\n~~~\nint lua_gettable (lua_State *L, int index);\n~~~\n\nPushes onto the stack the value t[k], where t is the value at the given index and k is the value on the top of the stack.\n\nThis function pops the key from the stack, pushing the resulting value in its place. As in Lua, this function may trigger a metamethod for the "index" event (see §2.4).\n\nReturns the type of the pushed value.","name":"lua_gettable","type":"c-api","def":"lua_gettable"},{"doc":"lua_getextraspace\n\n[-0, +0, –]\n\n~~~\nvoid *lua_getextraspace (lua_State *L);\n~~~\n\nReturns a pointer to a raw memory area associated with the given Lua state. The application can use this area for any purpose; Lua does not use it for anything.\n\nEach new thread has this area initialized with a copy of the area of the main thread.\n\nBy default, this area has the size of a pointer to void, but you can recompile Lua with a different size for this area. (See LUA_EXTRASPACE in luaconf.h.)","name":"lua_getextraspace","type":"c-api","def":"lua_getextraspace"},{"doc":"lua_upvaluejoin\n\n[-0, +0, –]\n\n~~~\nvoid lua_upvaluejoin (lua_State *L, int funcindex1, int n1,\n int funcindex2, int n2);\n~~~\n\nMake the n1-th upvalue of the Lua closure at index funcindex1 refer to the n2-th upvalue of the Lua closure at index funcindex2.","name":"lua_upvaluejoin","type":"c-api","def":"lua_upvaluejoin"},{"doc":"lua_newtable\n\n[-0, +1, m]\n\n~~~\nvoid lua_newtable (lua_State *L);\n~~~\n\nCreates a new empty table and pushes it onto the stack. It is equivalent to lua_createtable(L, 0, 0).","name":"lua_newtable","type":"c-api","def":"lua_newtable"},{"doc":"luaL_callmeta\n\n[-0, +(0|1), e]\n\n~~~\nint luaL_callmeta (lua_State *L, int obj, const char *e);\n~~~\n\nCalls a metamethod.\n\nIf the object at index obj has a metatable and this metatable has a field e, this function calls this field passing the object as its only argument. In this case this function returns true and pushes onto the stack the value returned by the call. If there is no metatable or no metamethod, this function returns false without pushing any value on the stack.","name":"luaL_callmeta","type":"c-api","def":"luaL_callmeta"},{"doc":"lua_arith\n\n[-(2|1), +1, e]\n\n~~~\nvoid lua_arith (lua_State *L, int op);\n~~~\n\nPerforms an arithmetic or bitwise operation over the two values (or one, in the case of negations) at the top of the stack, with the value on the top being the second operand, pops these values, and pushes the result of the operation. The function follows the semantics of the corresponding Lua operator (that is, it may call metamethods).\n\nThe value of op must be one of the following constants:\n\n * LUA_OPADD: performs addition (+)\n * LUA_OPSUB: performs subtraction (-)\n * LUA_OPMUL: performs multiplication (*)\n * LUA_OPDIV: performs float division (\/)\n * LUA_OPIDIV: performs floor division (\/\/)\n * LUA_OPMOD: performs modulo (%)\n * LUA_OPPOW: performs exponentiation (^)\n * LUA_OPUNM: performs mathematical negation (unary -)\n * LUA_OPBNOT: performs bitwise NOT (~)\n * LUA_OPBAND: performs bitwise AND (&)\n * LUA_OPBOR: performs bitwise OR (|)\n * LUA_OPBXOR: performs bitwise exclusive OR (~)\n * LUA_OPSHL: performs left shift (<<)\n * LUA_OPSHR: performs right shift (>>)","name":"lua_arith","type":"c-api","def":"lua_arith"},{"doc":"lua_isthread\n\n[-0, +0, –]\n\n~~~\nint lua_isthread (lua_State *L, int index);\n~~~\n\nReturns 1 if the value at the given index is a thread, and 0 otherwise.","name":"lua_isthread","type":"c-api","def":"lua_isthread"},{"doc":"luaL_len\n\n[-0, +0, e]\n\n~~~\nlua_Integer luaL_len (lua_State *L, int index);\n~~~\n\nReturns the "length" of the value at the given index as a number; it is equivalent to the '#' operator in Lua (see §3.4.7). Raises an error if the result of the operation is not an integer. (This case can only happen through metamethods.)","name":"luaL_len","type":"c-api","def":"luaL_len"},{"doc":"lua_getlocal\n\n[-0, +(0|1), –]\n\n~~~\nconst char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);\n~~~\n\nGets information about a local variable or a temporary value of a given activation record or a given function.\n\nIn the first case, the parameter ar must be a valid activation record that was filled by a previous call to lua_getstack or given as argument to a hook (see lua_Hook). The index n selects which local variable to inspect; see debug.getlocal for details about variable indices and names.\n\nlua_getlocal pushes the variable's value onto the stack and returns its name.\n\nIn the second case, ar must be NULL and the function to be inspected must be on the top of the stack. In this case, only parameters of Lua functions are visible (as there is no information about what variables are active) and no values are pushed onto the stack.\n\nReturns NULL (and pushes nothing) when the index is greater than the number of active local variables.","name":"lua_getlocal","type":"c-api","def":"lua_getlocal"},{"doc":"lua_iscfunction\n\n[-0, +0, –]\n\n~~~\nint lua_iscfunction (lua_State *L, int index);\n~~~\n\nReturns 1 if the value at the given index is a C function, and 0 otherwise.","name":"lua_iscfunction","type":"c-api","def":"lua_iscfunction"},{"doc":"lua_isnumber\n\n[-0, +0, –]\n\n~~~\nint lua_isnumber (lua_State *L, int index);\n~~~\n\nReturns 1 if the value at the given index is a number or a string convertible to a number, and 0 otherwise.","name":"lua_isnumber","type":"c-api","def":"lua_isnumber"},{"doc":"luaL_checklstring\n\n[-0, +0, v]\n\n~~~\nconst char *luaL_checklstring (lua_State *L, int arg, size_t *l);\n~~~\n\nChecks whether the function argument arg is a string and returns this string; if l is not NULL fills its referent with the string's length.\n\nThis function uses lua_tolstring to get its result, so all conversions and caveats of that function apply here.","name":"luaL_checklstring","type":"c-api","def":"luaL_checklstring"},{"doc":"lua_getmetatable\n\n[-0, +(0|1), –]\n\n~~~\nint lua_getmetatable (lua_State *L, int index);\n~~~\n\nIf the value at the given index has a metatable, the function pushes that metatable onto the stack and returns 1. Otherwise, the function returns 0 and pushes nothing on the stack.","name":"lua_getmetatable","type":"c-api","def":"lua_getmetatable"},{"doc":"lua_KFunction\n\n~~~\ntypedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);\n~~~\n\nType for continuation functions (see §4.5).","name":"lua_KFunction","type":"c-api","def":"lua_KFunction"},{"doc":"luaL_traceback\n\n[-0, +1, m]\n\n~~~\nvoid luaL_traceback (lua_State *L, lua_State *L1, const char *msg,\n int level);\n~~~\n\nCreates and pushes a traceback of the stack L1. If msg is not NULL, it is appended at the beginning of the traceback. The level parameter tells at which level to start the traceback.","name":"luaL_traceback","type":"c-api","def":"luaL_traceback"},{"doc":"lua_isinteger\n\n[-0, +0, –]\n\n~~~\nint lua_isinteger (lua_State *L, int index);\n~~~\n\nReturns 1 if the value at the given index is an integer (that is, the value is a number and is represented as an integer), and 0 otherwise.","name":"lua_isinteger","type":"c-api","def":"lua_isinteger"},{"doc":"lua_isboolean\n\n[-0, +0, –]\n\n~~~\nint lua_isboolean (lua_State *L, int index);\n~~~\n\nReturns 1 if the value at the given index is a boolean, and 0 otherwise.","name":"lua_isboolean","type":"c-api","def":"lua_isboolean"},{"doc":"lua_gettop\n\n[-0, +0, –]\n\n~~~\nint lua_gettop (lua_State *L);\n~~~\n\nReturns the index of the top element in the stack. Because indices start at 1, this result is equal to the number of elements in the stack; in particular, 0 means an empty stack.","name":"lua_gettop","type":"c-api","def":"lua_gettop"},{"doc":"lua_getupvalue\n\n[-0, +(0|1), –]\n\n~~~\nconst char *lua_getupvalue (lua_State *L, int funcindex, int n);\n~~~\n\nGets information about the n-th upvalue of the closure at index funcindex. It pushes the upvalue's value onto the stack and returns its name. Returns NULL (and pushes nothing) when the index n is greater than the number of upvalues.\n\nSee debug.getupvalue for more information about upvalues.","name":"lua_getupvalue","type":"c-api","def":"lua_getupvalue"},{"doc":"lua_getstack\n\n[-0, +0, –]\n\n~~~\nint lua_getstack (lua_State *L, int level, lua_Debug *ar);\n~~~\n\nGets information about the interpreter runtime stack.\n\nThis function fills parts of a lua_Debug structure with an identification of the activation record of the function executing at a given level. Level 0 is the current running function, whereas level n+1 is the function that has called level n (except for tail calls, which do not count on the stack). When called with a level greater than the stack depth, lua_getstack returns 0; otherwise it returns 1.","name":"lua_getstack","type":"c-api","def":"lua_getstack"},{"doc":"lua_toclose\n\n[-0, +0, v]\n\n~~~\nvoid lua_toclose (lua_State *L, int index);\n~~~\n\nMarks the given index in the stack as a to-be-closed "variable" (see §3.3.8). Like a to-be-closed variable in Lua, the value at that index in the stack will be closed when it goes out of scope. Here, in the context of a C function, to go out of scope means that the running function returns to Lua, there is an error, or the index is removed from the stack through lua_settop or lua_pop. An index marked as to-be-closed should not be removed from the stack by any other function in the API except lua_settop or lua_pop.\n\nThis function should not be called for an index that is equal to or below an active to-be-closed index.\n\nThis function can raise an out-of-memory error. In that case, the value in the given index is immediately closed, as if it was already marked.","name":"lua_toclose","type":"c-api","def":"lua_toclose"},{"doc":"lua_isnil\n\n[-0, +0, –]\n\n~~~\nint lua_isnil (lua_State *L, int index);\n~~~\n\nReturns 1 if the value at the given index is nil, and 0 otherwise.","name":"lua_isnil","type":"c-api","def":"lua_isnil"},{"doc":"luaL_dostring\n\n[-0, +?, –]\n\n~~~\nint luaL_dostring (lua_State *L, const char *str);\n~~~\n\nLoads and runs the given string. It is defined as the following macro:\n\n~~~\n\n (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))\n\n~~~\n\nIt returns LUA_OK if there are no errors, or an error code in case of errors (see §4.4.1).","name":"luaL_dostring","type":"c-api","def":"luaL_dostring"},{"doc":"lua_Alloc\n\n~~~\ntypedef void * (*lua_Alloc) (void *ud,\n void *ptr,\n size_t osize,\n size_t nsize);\n~~~\n\nThe type of the memory-allocation function used by Lua states. The allocator function must provide a functionality similar to realloc, but not exactly the same. Its arguments are ud, an opaque pointer passed to lua_newstate; ptr, a pointer to the block being allocated/reallocated/freed; osize, the original size of the block or some code about what is being allocated; and nsize, the new size of the block.\n\nWhen ptr is not NULL, osize is the size of the block pointed by ptr, that is, the size given when it was allocated or reallocated.\n\nWhen ptr is NULL, osize encodes the kind of object that Lua is allocating. osize is any of LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION, LUA_TUSERDATA, or LUA_TTHREAD when (and only when) Lua is creating a new object of that type. When osize is some other value, Lua is allocating memory for something else.\n\nLua assumes the following behavior from the allocator function:\n\nWhen nsize is zero, the allocator must behave like free and then return NULL.\n\nWhen nsize is not zero, the allocator must behave like realloc. In particular, the allocator returns NULL if and only if it cannot fulfill the request.\n\nHere is a simple implementation for the allocator function. It is used in the auxiliary library by luaL_newstate.\n\n~~~\n\n static void *l_alloc (void *ud, void ptr, size_t osize,\n size_t nsize) {\n (void)ud; (void)osize; / not used */\n if (nsize == 0) {\n free(ptr);\n return NULL;\n }\n else\n return realloc(ptr, nsize);\n }\n\n~~~\n\nNote that Standard C ensures that free(NULL) has no effect and that realloc(NULL,size) is equivalent to malloc(size).","name":"lua_Alloc","type":"c-api","def":"lua_Alloc"},{"doc":"lua_State\n\n~~~\ntypedef struct lua_State lua_State;\n~~~\n\nAn opaque structure that points to a thread and indirectly (through the thread) to the whole state of a Lua interpreter. The Lua library is fully reentrant: it has no global variables. All information about a state is accessible through this structure.\n\nA pointer to this structure must be passed as the first argument to every function in the library, except to lua_newstate, which creates a Lua state from scratch.","name":"lua_State","type":"c-api","def":"lua_State"},{"doc":"lua_rawsetp\n\n[-1, +0, m]\n\n~~~\nvoid lua_rawsetp (lua_State *L, int index, const void *p);\n~~~\n\nDoes the equivalent of t[p] = v, where t is the table at the given index, p is encoded as a light userdata, and v is the value on the top of the stack.\n\nThis function pops the value from the stack. The assignment is raw, that is, it does not use the __newindex metavalue.","name":"lua_rawsetp","type":"c-api","def":"lua_rawsetp"},{"doc":"using the environment variable LUA_CPATH_5_4, or the environment variable LUA_CPATH, or a default path defined in luaconf.h.","name":"LUA_CPATH_5_4","type":"c-api","def":"LUA_CPATH_5_4"},{"doc":"lua_setfield\n\n[-1, +0, e]\n\n~~~\nvoid lua_setfield (lua_State *L, int index, const char *k);\n~~~\n\nDoes the equivalent to t[k] = v, where t is the value at the given index and v is the value on the top of the stack.\n\nThis function pops the value from the stack. As in Lua, this function may trigger a metamethod for the "newindex" event (see §2.4).","name":"lua_setfield","type":"c-api","def":"lua_setfield"},{"doc":"lua_pushlstring\n\n[-0, +1, m]\n\n~~~\nconst char *lua_pushlstring (lua_State *L, const char *s, size_t len);\n~~~\n\nPushes the string pointed to by s with size len onto the stack. Lua will make or reuse an internal copy of the given string, so the memory at s can be freed or reused immediately after the function returns. The string can contain any binary data, including embedded zeros.\n\nReturns a pointer to the internal copy of the string.","name":"lua_pushlstring","type":"c-api","def":"lua_pushlstring"},{"doc":"lua_createtable\n\n[-0, +1, m]\n\n~~~\nvoid lua_createtable (lua_State *L, int narr, int nrec);\n~~~\n\nCreates a new empty table and pushes it onto the stack. Parameter narr is a hint for how many elements the table will have as a sequence; parameter nrec is a hint for how many other elements the table will have. Lua may use these hints to preallocate memory for the new table. This preallocation may help performance when you know in advance how many elements the table will have. Otherwise you can use the function lua_newtable.","name":"lua_createtable","type":"c-api","def":"lua_createtable"},{"doc":"lua_gethook\n\n[-0, +0, –]\n\n~~~\nlua_Hook lua_gethook (lua_State *L);\n~~~\n\nReturns the current hook function.","name":"lua_gethook","type":"c-api","def":"lua_gethook"},{"doc":"lua_setupvalue\n\n[-(0|1), +0, –]\n\n~~~\nconst char *lua_setupvalue (lua_State *L, int funcindex, int n);\n~~~\n\nSets the value of a closure's upvalue. It assigns the value on the top of the stack to the upvalue and returns its name. It also pops the value from the stack.\n\nReturns NULL (and pops nothing) when the index n is greater than the number of upvalues.\n\nParameters funcindex and n are as in the function lua_getupvalue.","name":"lua_setupvalue","type":"c-api","def":"lua_setupvalue"},{"doc":"lua_KContext\n\n~~~\ntypedef ... lua_KContext;\n~~~\n\nThe type for continuation-function contexts. It must be a numeric type. This type is defined as intptr_t when intptr_t is available, so that it can store pointers too. Otherwise, it is defined as ptrdiff_t.","name":"lua_KContext","type":"c-api","def":"lua_KContext"},{"doc":"lua_len\n\n[-0, +1, e]\n\n~~~\nvoid lua_len (lua_State *L, int index);\n~~~\n\nReturns the length of the value at the given index. It is equivalent to the '#' operator in Lua (see §3.4.7) and may trigger a metamethod for the "length" event (see §2.4). The result is pushed on the stack.","name":"lua_len","type":"c-api","def":"lua_len"},{"doc":"lua_pushfstring\n\n[-0, +1, v]\n\n~~~\nconst char *lua_pushfstring (lua_State *L, const char *fmt, ...);\n~~~\n\nPushes onto the stack a formatted string and returns a pointer to this string. It is similar to the ISO C function sprintf, but has two important differences. First, you do not have to allocate space for the result; the result is a Lua string and Lua takes care of memory allocation (and deallocation, through garbage collection). Second, the conversion specifiers are quite restricted. There are no flags, widths, or precisions. The conversion specifiers can only be '%%' (inserts the character '%'), '%s' (inserts a zero-terminated string, with no size restrictions), '%f' (inserts a lua_Number), '%I' (inserts a lua_Integer), '%p' (inserts a pointer), '%d' (inserts an int), '%c' (inserts an int as a one-byte character), and '%U' (inserts a long int as a UTF-8 byte sequence).\n\nThis function may raise errors due to memory overflow or an invalid conversion specifier.","name":"lua_pushfstring","type":"c-api","def":"lua_pushfstring"},{"doc":"lua_numbertointeger\n\n~~~\nint lua_numbertointeger (lua_Number n, lua_Integer *p);\n~~~\n\nTries to convert a Lua float to a Lua integer; the float n must have an integral value. If that value is within the range of Lua integers, it is converted to an integer and assigned to *p. The macro results in a boolean indicating whether the conversion was successful. (Note that this range test can be tricky to do correctly without this macro, due to rounding.)\n\nThis macro may evaluate its arguments more than once.","name":"lua_numbertointeger","type":"c-api","def":"lua_numbertointeger"},{"doc":"lua_checkstack\n\n[-0, +0, –]\n\n~~~\nint lua_checkstack (lua_State *L, int n);\n~~~\n\nEnsures that the stack has space for at least n extra slots, that is, that you can safely push up to n values into it. It returns false if it cannot fulfill the request, either because it would cause the stack to be greater than a fixed maximum size (typically at least several thousand elements) or because it cannot allocate memory for the extra space. This function never shrinks the stack; if the stack already has space for the extra slots, it is left unchanged.","name":"lua_checkstack","type":"c-api","def":"lua_checkstack"},{"doc":"lua_tonumber\n\n[-0, +0, –]\n\n~~~\nlua_Number lua_tonumber (lua_State *L, int index);\n~~~\n\nEquivalent to lua_tonumberx with isnum equal to NULL.","name":"lua_tonumber","type":"c-api","def":"lua_tonumber"},{"doc":"lua_pushnumber\n\n[-0, +1, –]\n\n~~~\nvoid lua_pushnumber (lua_State *L, lua_Number n);\n~~~\n\nPushes a float with value n onto the stack.","name":"lua_pushnumber","type":"c-api","def":"lua_pushnumber"},{"doc":"lua_getinfo\n\n[-(0|1), +(0|1|2), m]\n\n~~~\nint lua_getinfo (lua_State *L, const char *what, lua_Debug ar);\n~~~\n\nGets information about a specific function or function invocation.\n\nTo get information about a function invocation, the parameter ar must be a valid activation record that was filled by a previous call to lua_getstack or given as argument to a hook (see lua_Hook).\n\nTo get information about a function, you push it onto the stack and start the what string with the character '>'. (In that case, lua_getinfo pops the function from the top of the stack.) For instance, to know in which line a function f was defined, you can write the following code:\n\n~~~\n\n lua_Debug ar;\n lua_getglobal(L, "f"); / get global 'f' */\n lua_getinfo(L, ">S", &ar);\n printf("%d\n", ar.linedefined);\n\n~~~\n\nEach character in the string what selects some fields of the structure ar to be filled or a value to be pushed on the stack:\n\n * 'n': fills in the field name and namewhat;\n\n * 'S': fills in the fields source, short_src, linedefined, lastlinedefined, and what;\n\n * 'l': fills in the field currentline;\n\n * 't': fills in the field istailcall;\n\n * 'u': fills in the fields nups, nparams, and isvararg;\n\n * 'f': pushes onto the stack the function that is running at the given level;\n\n * 'L': pushes onto the stack a table whose indices are the numbers of the lines that are valid on the function. (A valid line is a line with some associated code, that is, a line where you can put a break point. Non-valid lines include empty lines and comments.)\n\nIf this option is given together with option 'f', its table is pushed after the function.\n\nThis is the only option that can raise a memory error.\n\nThis function returns 0 to signal an invalid option in what; even then the valid options are handled correctly.","name":"lua_getinfo","type":"c-api","def":"lua_getinfo"},{"doc":"luaL_dofile\n\n[-0, +?, m]\n\n~~~\nint luaL_dofile (lua_State *L, const char *filename);\n~~~\n\nLoads and runs the given file. It is defined as the following macro:\n\n~~~\n\n (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))\n\n~~~\n\nIt returns LUA_OK if there are no errors, or an error code in case of errors (see §4.4.1).","name":"luaL_dofile","type":"c-api","def":"luaL_dofile"},{"doc":"luaL_addsize\n\n[-?, +?, –]\n\n~~~\nvoid luaL_addsize (luaL_Buffer *B, size_t n);\n~~~\n\nAdds to the buffer B a string of length n previously copied to the buffer area (see luaL_prepbuffer).","name":"luaL_addsize","type":"c-api","def":"luaL_addsize"},{"doc":"lua_copy\n\n[-0, +0, –]\n\n~~~\nvoid lua_copy (lua_State *L, int fromidx, int toidx);\n~~~\n\nCopies the element at index fromidx into the valid index toidx, replacing the value at that position. Values at other positions are not affected.","name":"lua_copy","type":"c-api","def":"lua_copy"},{"doc":"lua_getglobal\n\n[-0, +1, e]\n\n~~~\nint lua_getglobal (lua_State *L, const char name);\n~~~\n\nPushes onto the stack the value of the global name. Returns the type of that value.","name":"lua_getglobal","type":"c-api","def":"lua_getglobal"}],"name":"lua.C","desc":"Lua 5.4 C API"},{"doc":"Select a section from the Lua 5.4 manual by prefacing it's number with and replacing all periods with an ''; e.g. Section 6.4 would be _6_4.","items":[{"doc":"3.3.3 – Assignment\n\nLua allows multiple assignments. Therefore, the syntax for assignment defines a list of variables on the left side and a list of expressions on the right side. The elements in both lists are separated by commas:\n\n~~~\n\n\tstat ::= varlist ‘=’ explist\n\tvarlist ::= var {‘,’ var}\n\texplist ::= exp {‘,’ exp}\n\n~~~\n\nExpressions are discussed in §3.4.\n\nBefore the assignment, the list of values is adjusted to the length of the list of variables. If there are more values than needed, the excess values are thrown away. If there are fewer values than needed, the list is extended with nil's. If the list of expressions ends with a function call, then all values returned by that call enter the list of values, before the adjustment (except when the call is enclosed in parentheses; see §3.4).\n\nThe assignment statement first evaluates all its expressions and only then the assignments are performed. Thus the code\n\n~~~\n\n i = 3\n i, a[i] = i+1, 20\n\n~~~\n\nsets a[3] to 20, without affecting a[4] because the i in a[i] is evaluated (to 3) before it is assigned 4. Similarly, the line\n\n~~~\n\n x, y = y, x\n\n~~~\n\nexchanges the values of x and y, and\n\n~~~\n\n x, y, z = y, z, x\n\n~~~\n\ncyclically permutes the values of x, y, and z.\n\nAn assignment to a global name x = val is equivalent to the assignment _ENV.x = val (see §2.2).\n\nThe meaning of assignments to table fields and global variables (which are actually table fields, too) can be changed via metatables (see §2.4).","name":"_3_3_3","type":"manual","def":"3.3.3 – Assignment"},{"doc":"2.4 – Metatables and Metamethods\n\nEvery value in Lua can have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original value under certain events. You can change several aspects of the behavior of a value by setting specific fields in its metatable. For instance, when a non-numeric value is the operand of an addition, Lua checks for a function in the field "__add" of the value's metatable. If it finds one, Lua calls this function to perform the addition.\n\nThe key for each event in a metatable is a string with the event name prefixed by two underscores; the corresponding value is called a metavalue. For most events, the metavalue must be a function, which is then called a metamethod. In the previous example, the key is the string "__add" and the metamethod is the function that performs the addition. Unless stated otherwise, a metamethod may in fact be any callable value, which is either a function or a value with a __call metamethod.\n\nYou can query the metatable of any value using the getmetatable function. Lua queries metamethods in metatables using a raw access (see rawget).\n\nYou can replace the metatable of tables using the setmetatable function. You cannot change the metatable of other types from Lua code, except by using the debug library (§6.10).\n\nTables and full userdata have individual metatables, although multiple tables and userdata can share their metatables. Values of all other types share one single metatable per type; that is, there is one single metatable for all numbers, one for all strings, etc. By default, a value has no metatable, but the string library sets a metatable for the string type (see §6.4).\n\nA detailed list of operations controlled by metatables is given next. Each event is identified by its corresponding key. By convention, all metatable keys used by Lua are composed by two underscores followed by lowercase Latin letters.\n\n * __add: the addition (+) operation. If any operand for an addition is not a number, Lua will try to call a metamethod. It starts by checking the first operand (even if it is a number); if that operand does not define a metamethod for __add, then Lua will check the second operand. If Lua can find a metamethod, it calls the metamethod with the two operands as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, if no metamethod is found, Lua raises an error.\n\n * __sub: the subtraction (-) operation. Behavior similar to the addition operation.\n\n * __mul: the multiplication (*) operation. Behavior similar to the addition operation.\n\n * __div: the division (\/) operation. Behavior similar to the addition operation.\n\n * __mod: the modulo (%) operation. Behavior similar to the addition operation.\n\n * __pow: the exponentiation (^) operation. Behavior similar to the addition operation.\n\n * __unm: the negation (unary -) operation. Behavior similar to the addition operation.\n\n * __idiv: the floor division (\/\/) operation. Behavior similar to the addition operation.\n\n * __band: the bitwise AND (&) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither an integer nor a float coercible to an integer (see §3.4.3).\n\n * __bor: the bitwise OR (|) operation. Behavior similar to the bitwise AND operation.\n\n * __bxor: the bitwise exclusive OR (binary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __bnot: the bitwise NOT (unary ~) operation. Behavior similar to the bitwise AND operation.\n\n * __shl: the bitwise left shift (<<) operation. Behavior similar to the bitwise AND operation.\n\n * __shr: the bitwise right shift (>>) operation. Behavior similar to the bitwise AND operation.\n\n * __concat: the concatenation (..) operation. Behavior similar to the addition operation, except that Lua will try a metamethod if any operand is neither a string nor a number (which is always coercible to a string).\n\n * __len: the length (#) operation. If the object is not a string, Lua will try its metamethod. If there is a metamethod, Lua calls it with the object as argument, and the result of the call (always adjusted to one value) is the result of the operation. If there is no metamethod but the object is a table, then Lua uses the table length operation (see §3.4.7). Otherwise, Lua raises an error.\n\n * __eq: the equal (==) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are either both tables or both full userdata and they are not primitively equal. The result of the call is always converted to a boolean.\n\n * __lt: the less than (<) operation. Behavior similar to the addition operation, except that Lua will try a metamethod only when the values being compared are neither both numbers nor both strings. Moreover, the result of the call is always converted to a boolean.\n\n * __le: the less equal (<=) operation. Behavior similar to the less than operation.\n\n * __index: The indexing access operation table[key]. This event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nThe metavalue for this event can be either a function, a table, or any value with an __index metavalue. If it is a function, it is called with table and key as arguments, and the result of the call (adjusted to one value) is the result of the operation. Otherwise, the final result is the result of indexing this metavalue with key. This indexing is regular, not raw, and therefore can trigger another __index metavalue.\n\n * __newindex: The indexing assignment table[key] = value. Like the index event, this event happens when table is not a table or when key is not present in table. The metavalue is looked up in the metatable of table.\n\nLike with indexing, the metavalue for this event can be either a function, a table, or any value with an __newindex metavalue. If it is a function, it is called with table, key, and value as arguments. Otherwise, Lua repeats the indexing assignment over this metavalue with the same key and value. This assignment is regular, not raw, and therefore can trigger another __newindex metavalue.\n\nWhenever a __newindex metavalue is invoked, Lua does not perform the primitive assignment. If needed, the metamethod itself can call rawset to do the assignment.\n\n * __call: The call operation func(args). This event happens when Lua tries to call a non-function value (that is, func is not a function). The metamethod is looked up in func. If present, the metamethod is called with func as its first argument, followed by the arguments of the original call (args). All results of the call are the results of the operation. This is the only metamethod that allows multiple results.\n\nIn addition to the previous list, the interpreter also respects the following keys in metatables: __gc (see §2.5.3), __close (see §3.3.8), __mode (see §2.5.4), and __name. (The entry __name, when it contains a string, may be used by tostring and in error messages.)\n\nFor the unary operators (negation, length, and bitwise NOT), the metamethod is computed and called with a dummy second operand, equal to the first one. This extra operand is only to simplify Lua's internals (by making these operators behave like a binary operation) and may be removed in future versions. For most uses this extra operand is irrelevant.\n\nBecause metatables are regular tables, they can contain arbitrary fields, not only the event names defined above. Some functions in the standard library (e.g., tostring) use other fields in metatables for their own purposes.\n\nIt is a good practice to add all needed metamethods to a table before setting it as a metatable of some object. In particular, the __gc metamethod works only when this order is followed (see §2.5.3). It is also a good practice to set the metatable of an object right after its creation.","name":"_2_4","type":"manual","def":"2.4 – Metatables and Metamethods"},{"doc":"3.4 – Expressions\n\nThe basic expressions in Lua are the following:\n\n~~~\n\n\texp ::= prefixexp\n\texp ::= nil | false | true\n\texp ::= Numeral\n\texp ::= LiteralString\n\texp ::= functiondef\n\texp ::= tableconstructor\n\texp ::= ‘...’\n\texp ::= exp binop exp\n\texp ::= unop exp\n\tprefixexp ::= var | functioncall | ‘(’ exp ‘)’\n\n~~~\n\nNumerals and literal strings are explained in §3.1; variables are explained in §3.2; function definitions are explained in §3.4.11; function calls are explained in §3.4.10; table constructors are explained in §3.4.9. Vararg expressions, denoted by three dots ('...'), can only be used when directly inside a vararg function; they are explained in §3.4.11.\n\nBinary operators comprise arithmetic operators (see §3.4.1), bitwise operators (see §3.4.2), relational operators (see §3.4.4), logical operators (see §3.4.5), and the concatenation operator (see §3.4.6). Unary operators comprise the unary minus (see §3.4.1), the unary bitwise NOT (see §3.4.2), the unary logical not (see §3.4.5), and the unary length operator (see §3.4.7).\n\nBoth function calls and vararg expressions can result in multiple values. If a function call is used as a statement (see §3.3.6), then its return list is adjusted to zero elements, thus discarding all returned values. If an expression is used as the last (or the only) element of a list of expressions, then no adjustment is made (unless the expression is enclosed in parentheses). In all other contexts, Lua adjusts the result list to one element, either discarding all values except the first one or adding a single nil if there are no values.\n\nHere are some examples:\n\n~~~\n\n f() -- adjusted to 0 results\n g(f(), x) -- f() is adjusted to 1 result\n g(x, f()) -- g gets x plus all results from f()\n a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)\n a,b = ... -- a gets the first vararg argument, b gets\n -- the second (both a and b can get nil if there\n -- is no corresponding vararg argument)\n \n a,b,c = x, f() -- f() is adjusted to 2 results\n a,b,c = f() -- f() is adjusted to 3 results\n return f() -- returns all results from f()\n return ... -- returns all received vararg arguments\n return x,y,f() -- returns x, y, and all results from f()\n {f()} -- creates a list with all results from f()\n {...} -- creates a list with all vararg arguments\n {f(), nil} -- f() is adjusted to 1 result\n\n~~~\n\nAny expression enclosed in parentheses always results in only one value. Thus, (f(x,y,z)) is always a single value, even if f returns several values. (The value of (f(x,y,z)) is the first value returned by f or nil if f does not return any values.)","name":"_3_4","type":"manual","def":"3.4 – Expressions"},{"doc":"4.4 – Error Handling in C\n\nInternally, Lua uses the C longjmp facility to handle errors. (Lua will use exceptions if you compile it as C++; search for LUAI_THROW in the source code for details.) When Lua faces any error, such as a memory allocation error or a type error, it raises an error; that is, it does a long jump. A protected environment uses setjmp to set a recovery point; any error jumps to the most recent active recovery point.\n\nInside a C function you can raise an error explicitly by calling lua_error.\n\nMost functions in the API can raise an error, for instance due to a memory allocation error. The documentation for each function indicates whether it can raise errors.\n\nIf an error happens outside any protected environment, Lua calls a panic function (see lua_atpanic) and then calls abort, thus exiting the host application. Your panic function can avoid this exit by never returning (e.g., doing a long jump to your own recovery point outside Lua).\n\nThe panic function, as its name implies, is a mechanism of last resort. Programs should avoid it. As a general rule, when a C function is called by Lua with a Lua state, it can do whatever it wants on that Lua state, as it should be already protected. However, when C code operates on other Lua states (e.g., a Lua-state argument to the function, a Lua state stored in the registry, or the result of lua_newthread), it should use them only in API calls that cannot raise errors.\n\nThe panic function runs as if it were a message handler (see §2.3); in particular, the error object is on the top of the stack. However, there is no guarantee about stack space. To push anything on the stack, the panic function must first check the available space (see §4.1.1).","name":"_4_4","type":"manual","def":"4.4 – Error Handling in C"},{"doc":"3.3.8 – To-be-closed Variables\n\nA to-be-closed variable behaves like a constant local variable, except that its value is closed whenever the variable goes out of scope, including normal block termination, exiting its block by break/goto/return, or exiting by an error.\n\nHere, to close a value means to call its __close metamethod. When calling the metamethod, the value itself is passed as the first argument and the error object that caused the exit (if any) is passed as a second argument; if there was no error, the second argument is nil.\n\nThe value assigned to a to-be-closed variable must have a __close metamethod or be a false value. (nil and false are ignored as to-be-closed values.)\n\nIf several to-be-closed variables go out of scope at the same event, they are closed in the reverse order that they were declared.\n\nIf there is any error while running a closing method, that error is handled like an error in the regular code where the variable was defined. However, Lua may call the method one more time.\n\nAfter an error, the other pending closing methods will still be called. Errors in these methods interrupt the respective method and generate a warning, but are otherwise ignored; the error reported is only the original one.\n\nIf a coroutine yields and is never resumed again, some variables may never go out of scope, and therefore they will never be closed. (These variables are the ones created inside the coroutine and in scope at the point where the coroutine yielded.) Similarly, if a coroutine ends with an error, it does not unwind its stack, so it does not close any variable. In both cases, you can either use finalizers or call coroutine.close to close the variables. However, if the coroutine was created through coroutine.wrap, then its corresponding function will close the coroutine in case of errors.","name":"_3_3_8","type":"manual","def":"3.3.8 – To-be-closed Variables"},{"doc":"3.4.9 – Table Constructors\n\nTable constructors are expressions that create tables. Every time a constructor is evaluated, a new table is created. A constructor can be used to create an empty table or to create a table and initialize some of its fields. The general syntax for constructors is\n\n~~~\n\n\ttableconstructor ::= ‘{’ [fieldlist] ‘}’\n\tfieldlist ::= field {fieldsep field} [fieldsep]\n\tfield ::= ‘[’ exp ‘]’ ‘=’ exp | Name ‘=’ exp | exp\n\tfieldsep ::= ‘,’ | ‘;’\n\n~~~\n\nEach field of the form [exp1] = exp2 adds to the new table an entry with key exp1 and value exp2. A field of the form name = exp is equivalent to [\"name\"] = exp. Fields of the form exp are equivalent to [i] = exp, where i are consecutive integers starting with 1; fields in the other formats do not affect this counting. For example,\n\n~~~\n\n a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }\n\n~~~\n\nis equivalent to\n\n~~~\n\n do\n local t = {}\n t[f(1)] = g\n t[1] = "x" -- 1st exp\n t[2] = "y" -- 2nd exp\n t.x = 1 -- t["x"] = 1\n t[3] = f(x) -- 3rd exp\n t[30] = 23\n t[4] = 45 -- 4th exp\n a = t\n end\n\n~~~\n\nThe order of the assignments in a constructor is undefined. (This order would be relevant only when there are repeated keys.)\n\nIf the last field in the list has the form exp and the expression is a function call or a vararg expression, then all values returned by this expression enter the list consecutively (see §3.4.10).\n\nThe field list can have an optional trailing separator, as a convenience for machine-generated code.","name":"_3_4_9","type":"manual","def":"3.4.9 – Table Constructors"},{"doc":"2.3 – Error Handling\n\nSeveral operations in Lua can raise an error. An error interrupts the normal flow of the program, which can continue by catching the error.\n\nLua code can explicitly raise an error by calling the error function. (This function never returns.)\n\nTo catch errors in Lua, you can do a protected call, using pcall (or xpcall). The function pcall calls a given function in protected mode. Any error while running the function stops its execution, and control returns immediately to pcall, which returns a status code.\n\nBecause Lua is an embedded extension language, Lua code starts running by a call from C code in the host program. (When you use Lua standalone, the lua application is the host program.) Usually, this call is protected; so, when an otherwise unprotected error occurs during the compilation or execution of a Lua chunk, control returns to the host, which can take appropriate measures, such as printing an error message.\n\nWhenever there is an error, an error object is propagated with information about the error. Lua itself only generates errors whose error object is a string, but programs may generate errors with any value as the error object. It is up to the Lua program or its host to handle such error objects. For historical reasons, an error object is often called an error message, even though it does not have to be a string.\n\nWhen you use xpcall (or lua_pcall, in C) you may give a message handler to be called in case of errors. This function is called with the original error object and returns a new error object. It is called before the error unwinds the stack, so that it can gather more information about the error, for instance by inspecting the stack and creating a stack traceback. This message handler is still protected by the protected call; so, an error inside the message handler will call the message handler again. If this loop goes on for too long, Lua breaks it and returns an appropriate message. The message handler is called only for regular runtime errors. It is not called for memory-allocation errors nor for errors while running finalizers or other message handlers.\n\nLua also offers a system of warnings (see warn). Unlike errors, warnings do not interfere in any way with program execution. They typically only generate a message to the user, although this behavior can be adapted from C (see lua_setwarnf).","name":"_2_3","type":"manual","def":"2.3 – Error Handling"},{"doc":"4.3 – Registry\n\nLua provides a registry, a predefined table that can be used by any C code to store whatever Lua values it needs to store. The registry table is always accessible at pseudo-index LUA_REGISTRYINDEX. Any C library can store data into this table, but it must take care to choose keys that are different from those used by other libraries, to avoid collisions. Typically, you should use as key a string containing your library name, or a light userdata with the address of a C object in your code, or any Lua object created by your code. As with variable names, string keys starting with an underscore followed by uppercase letters are reserved for Lua.\n\nThe integer keys in the registry are used by the reference mechanism (see luaL_ref) and by some predefined values. Therefore, integer keys in the registry must not be used for other purposes.\n\nWhen you create a new Lua state, its registry comes with some predefined values. These predefined values are indexed with integer keys defined as constants in lua.h. The following constants are defined:\n\n * LUA_RIDX_MAINTHREAD: At this index the registry has the main thread of the state. (The main thread is the one created together with the state.)\n\n * LUA_RIDX_GLOBALS: At this index the registry has the global environment.","name":"_4_3","type":"manual","def":"4.3 – Registry"},{"doc":"3.3 – Statements\n\nLua supports an almost conventional set of statements, similar to those in other conventional languages. This set includes blocks, assignments, control structures, function calls, and variable declarations.","name":"_3_3","type":"manual","def":"3.3 – Statements"},{"doc":"2.5.4 – Weak Tables\n\nA weak table is a table whose elements are weak references. A weak reference is ignored by the garbage collector. In other words, if the only references to an object are weak references, then the garbage collector will collect that object.\n\nA weak table can have weak keys, weak values, or both. A table with weak values allows the collection of its values, but prevents the collection of its keys. A table with both weak keys and weak values allows the collection of both keys and values. In any case, if either the key or the value is collected, the whole pair is removed from the table. The weakness of a table is controlled by the __mode field of its metatable. This metavalue, if present, must be one of the following strings: "k", for a table with weak keys; "v", for a table with weak values; or "kv", for a table with both weak keys and values.\n\nA table with weak keys and strong values is also called an ephemeron table. In an ephemeron table, a value is considered reachable only if its key is reachable. In particular, if the only reference to a key comes through its value, the pair is removed.\n\nAny change in the weakness of a table may take effect only at the next collect cycle. In particular, if you change the weakness to a stronger mode, Lua may still collect some items from that table before the change takes effect.\n\nOnly objects that have an explicit construction are removed from weak tables. Values, such as numbers and light C functions, are not subject to garbage collection, and therefore are not removed from weak tables (unless their associated values are collected). Although strings are subject to garbage collection, they do not have an explicit construction and their equality is by value; they behave more like values than like objects. Therefore, they are not removed from weak tables.\n\nResurrected objects (that is, objects being finalized and objects accessible only through objects being finalized) have a special behavior in weak tables. They are removed from weak values before running their finalizers, but are removed from weak keys only in the next collection after running their finalizers, when such objects are actually freed. This behavior allows the finalizer to access properties associated with the object through weak tables.\n\nIf a weak table is among the resurrected objects in a collection cycle, it may not be properly cleared until the next cycle.","name":"_2_5_4","type":"manual","def":"2.5.4 – Weak Tables"},{"doc":"3.4.7 – The Length Operator\n\nThe length operator is denoted by the unary prefix operator #.\n\nThe length of a string is its number of bytes. (That is the usual meaning of string length when each character is one byte.)\n\nThe length operator applied on a table returns a border in that table. A border in a table t is any natural number that satisfies the following condition:\n\n~~~\n\n (border == 0 or t[border] ~= nil) and t[border + 1] == nil\n\n~~~\n\nIn words, a border is any (natural) index present in the table that is followed by an absent index (or zero, when index 1 is absent).\n\nA table with exactly one border is called a sequence. For instance, the table {10, 20, 30, 40, 50} is a sequence, as it has only one border (5). The table {10, 20, 30, nil, 50} has two borders (3 and 5), and therefore it is not a sequence. (The nil at index 4 is called a hole.) The table {nil, 20, 30, nil, nil, 60, nil} has three borders (0, 3, and 6) and three holes (at indices 1, 4, and 5), so it is not a sequence, too. The table {} is a sequence with border 0. Note that non-natural keys do not interfere with whether a table is a sequence.\n\nWhen t is a sequence, #t returns its only border, which corresponds to the intuitive notion of the length of the sequence. When t is not a sequence, #t can return any of its borders. (The exact one depends on details of the internal representation of the table, which in turn can depend on how the table was populated and the memory addresses of its non-numeric keys.)\n\nThe computation of the length of a table has a guaranteed worst time of O(log n), where n is the largest natural key in the table.\n\nA program can modify the behavior of the length operator for any value but strings through the __len metamethod (see §2.4).","name":"_3_4_7","type":"manual","def":"3.4.7 – The Length Operator"},{"doc":"3.4.4 – Relational Operators\n\nLua supports the following relational operators:\n\n * ==: equality\n * ~=: inequality\n * <: less than\n * >: greater than\n * <=: less or equal\n * >=: greater or equal\n\nThese operators always result in false or true.\n\nEquality (==) first compares the type of its operands. If the types are different, then the result is false. Otherwise, the values of the operands are compared. Strings are equal if they have the same byte content. Numbers are equal if they denote the same mathematical value.\n\nTables, userdata, and threads are compared by reference: two objects are considered equal only if they are the same object. Every time you create a new object (a table, a userdata, or a thread), this new object is different from any previously existing object. A function is always equal to itself. Functions with any detectable difference (different behavior, different definition) are always different. Functions created at different times but with no detectable differences may be classified as equal or not (depending on internal caching details).\n\nYou can change the way that Lua compares tables and userdata by using the __eq metamethod (see §2.4).\n\nEquality comparisons do not convert strings to numbers or vice versa. Thus, \"0\"==0 evaluates to false, and t[0] and t[\"0\"] denote different entries in a table.\n\nThe operator ~= is exactly the negation of equality (==).\n\nThe order operators work as follows. If both arguments are numbers, then they are compared according to their mathematical values, regardless of their subtypes. Otherwise, if both arguments are strings, then their values are compared according to the current locale. Otherwise, Lua tries to call the __lt or the __le metamethod (see §2.4). A comparison a > b is translated to b < a and a >= b is translated to b <= a.\n\nFollowing the IEEE 754 standard, the special value NaN is considered neither less than, nor equal to, nor greater than any value, including itself.","name":"_3_4_4","type":"manual","def":"3.4.4 – Relational Operators"},{"doc":"6.4 – String Manipulation\n\nThis library provides generic functions for string manipulation, such as finding and extracting substrings, and pattern matching. When indexing a string in Lua, the first character is at position 1 (not at 0, as in C). Indices are allowed to be negative and are interpreted as indexing backwards, from the end of the string. Thus, the last character is at position -1, and so on.\n\nThe string library provides all its functions inside the table string. It also sets a metatable for strings where the __index field points to the string table. Therefore, you can use the string functions in object-oriented style. For instance, string.byte(s,i) can be written as s:byte(i).\n\nThe string library assumes one-byte character encodings.\n\n--------------------------------------------------------------------------------\n\nstring.byte (s [, i [, j]])\n\nReturns the internal numeric codes of the characters s[i], s[i+1], ..., s[j]. The default value for i is 1; the default value for j is i. These indices are corrected following the same rules of function string.sub.\n\nNumeric codes are not necessarily portable across platforms.\n\n--------------------------------------------------------------------------------\n\nstring.char (···)\n\nReceives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numeric code equal to its corresponding argument.\n\nNumeric codes are not necessarily portable across platforms.\n\n--------------------------------------------------------------------------------\n\nstring.dump (function [, strip])\n\nReturns a string containing a binary representation (a binary chunk) of the given function, so that a later load on this string returns a copy of the function (but with new upvalues). If strip is a true value, the binary representation may not include all debug information about the function, to save space.\n\nFunctions with upvalues have only their number of upvalues saved. When (re)loaded, those upvalues receive fresh instances. (See the load function for details about how these upvalues are initialized. You can use the debug library to serialize and reload the upvalues of a function in a way adequate to your needs.)\n\n--------------------------------------------------------------------------------\n\nstring.find (s, pattern [, init [, plain]])\n\nLooks for the first match of pattern (see §6.4.1) in the string s. If it finds a match, then find returns the indices of s where this occurrence starts and ends; otherwise, it returns fail. A third, optional numeric argument init specifies where to start the search; its default value is 1 and can be negative. A value of true as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered magic.\n\nIf the pattern has captures, then in a successful match the captured values are also returned, after the two indices.\n\n--------------------------------------------------------------------------------\n\nstring.format (formatstring, ···)\n\nReturns a formatted version of its variable number of arguments following the description given in its first argument, which must be a string. The format string follows the same rules as the ISO C function sprintf. The only differences are that the conversion specifiers and modifiers *, h, L, l, and n are not supported and that there is an extra specifier, q.\n\nThe specifier q formats booleans, nil, numbers, and strings in a way that the result is a valid constant in Lua source code. Booleans and nil are written in the obvious way (true, false, nil). Floats are written in hexadecimal, to preserve full precision. A string is written between double quotes, using escape sequences when necessary to ensure that it can safely be read back by the Lua interpreter. For instance, the call\n\n~~~\n\n string.format('%q', 'a string with "quotes" and \n new line')\n\n~~~\n\nmay produce the string:\n\n~~~\n\n "a string with \"quotes\" and \\n new line"\n\n~~~\n\nThis specifier does not support modifiers (flags, width, length).\n\nThe conversion specifiers A, a, E, e, f, G, and g all expect a number as argument. The specifiers c, d, i, o, u, X, and x expect an integer. When Lua is compiled with a C89 compiler, the specifiers A and a (hexadecimal floats) do not support modifiers.\n\nThe specifier s expects a string; if its argument is not a string, it is converted to one following the same rules of tostring. If the specifier has any modifier, the corresponding string argument should not contain embedded zeros.\n\nThe specifier p formats the pointer returned by lua_topointer. That gives a unique string identifier for tables, userdata, threads, strings, and functions. For other values (numbers, nil, booleans), this specifier results in a string representing the pointer NULL.\n\n--------------------------------------------------------------------------------\n\nstring.gmatch (s, pattern [, init])\n\nReturns an iterator function that, each time it is called, returns the next captures from pattern (see §6.4.1) over the string s. If pattern specifies no captures, then the whole match is produced in each call. A third, optional numeric argument init specifies where to start the search; its default value is 1 and can be negative.\n\nAs an example, the following loop will iterate over all the words from string s, printing one per line:\n\n~~~\n\n s = "hello world from Lua"\n for w in string.gmatch(s, "%a+") do\n print(w)\n end\n\n~~~\n\nThe next example collects all pairs key=value from the given string into a table:\n\n~~~\n\n t = {}\n s = "from=world, to=Lua"\n for k, v in string.gmatch(s, "(%w+)=(%w+)") do\n t[k] = v\n end\n\n~~~\n\nFor this function, a caret '^' at the start of a pattern does not work as an anchor, as this would prevent the iteration.\n\n--------------------------------------------------------------------------------\n\nstring.gsub (s, pattern, repl [, n])\n\nReturns a copy of s in which all (or the first n, if given) occurrences of the pattern (see §6.4.1) have been replaced by a replacement string specified by repl, which can be a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred. The name gsub comes from Global SUBstitution.\n\nIf repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %d, with d between 1 and 9, stands for the value of the d-th captured substring; the sequence %0 stands for the whole match; the sequence %% stands for a single %.\n\nIf repl is a table, then the table is queried for every match, using the first capture as the key.\n\nIf repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order.\n\nIn any case, if the pattern specifies no captures, then it behaves as if the whole pattern was inside a capture.\n\nIf the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).\n\nHere are some examples:\n\n~~~\n\n x = string.gsub("hello world", "(%w+)", "%1 %1")\n --> x="hello hello world world"\n \n x = string.gsub("hello world", "%w+", "%0 %0", 1)\n --> x="hello hello world"\n \n x = string.gsub("hello world from Lua", "(%w+)%s(%w+)", "%2 %1")\n --> x="world hello Lua from"\n \n x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)\n --> x="home = /home/roberto, user = roberto"\n \n x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)\n return load(s)()\n end)\n --> x="4+5 = 9"\n \n local t = {name="lua", version="5.4"}\n x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)\n --> x="lua-5.4.tar.gz"\n\n~~~\n\n--------------------------------------------------------------------------------\n\nstring.len (s)\n\nReceives a string and returns its length. The empty string \"\" has length 0. Embedded zeros are counted, so \"a\\000bc\\000\" has length 5.\n\n--------------------------------------------------------------------------------\n\nstring.lower (s)\n\nReceives a string and returns a copy of this string with all uppercase letters changed to lowercase. All other characters are left unchanged. The definition of what an uppercase letter is depends on the current locale.\n\n--------------------------------------------------------------------------------\n\nstring.match (s, pattern [, init])\n\nLooks for the first match of the pattern (see §6.4.1) in the string s. If it finds one, then match returns the captures from the pattern; otherwise it returns fail. If pattern specifies no captures, then the whole match is returned. A third, optional numeric argument init specifies where to start the search; its default value is 1 and can be negative.\n\n--------------------------------------------------------------------------------\n\nstring.pack (fmt, v1, v2, ···)\n\nReturns a binary string containing the values v1, v2, etc. serialized in binary form (packed) according to the format string fmt (see §6.4.2).\n\n--------------------------------------------------------------------------------\n\nstring.packsize (fmt)\n\nReturns the size of a string resulting from string.pack with the given format. The format string cannot have the variable-length options 's' or 'z' (see §6.4.2).\n\n--------------------------------------------------------------------------------\n\nstring.rep (s, n [, sep])\n\nReturns a string that is the concatenation of n copies of the string s separated by the string sep. The default value for sep is the empty string (that is, no separator). Returns the empty string if n is not positive.\n\n(Note that it is very easy to exhaust the memory of your machine with a single call to this function.)\n\n--------------------------------------------------------------------------------\n\nstring.reverse (s)\n\nReturns a string that is the string s reversed.\n\n--------------------------------------------------------------------------------\n\nstring.sub (s, i [, j])\n\nReturns the substring of s that starts at i and continues until j; i and j can be negative. If j is absent, then it is assumed to be equal to -1 (which is the same as the string length). In particular, the call string.sub(s,1,j) returns a prefix of s with length j, and string.sub(s, -i) (for a positive i) returns a suffix of s with length i.\n\nIf, after the translation of negative indices, i is less than 1, it is corrected to 1. If j is greater than the string length, it is corrected to that length. If, after these corrections, i is greater than j, the function returns the empty string.\n\n--------------------------------------------------------------------------------\n\nstring.unpack (fmt, s [, pos])\n\nReturns the values packed in string s (see string.pack) according to the format string fmt (see §6.4.2). An optional pos marks where to start reading in s (default is 1). After the read values, this function also returns the index of the first unread byte in s.\n\n--------------------------------------------------------------------------------\n\nstring.upper (s)\n\nReceives a string and returns a copy of this string with all lowercase letters changed to uppercase. All other characters are left unchanged. The definition of what a lowercase letter is depends on the current locale.","name":"_6_4","type":"manual","def":"6.4 – String Manipulation"},{"doc":"3.4.5 – Logical Operators\n\nThe logical operators in Lua are and, or, and not. Like the control structures (see §3.3.4), all logical operators consider both false and nil as false and anything else as true.\n\nThe negation operator not always returns false or true. The conjunction operator and returns its first argument if this value is false or nil; otherwise, and returns its second argument. The disjunction operator or returns its first argument if this value is different from nil and false; otherwise, or returns its second argument. Both and and or use short-circuit evaluation; that is, the second operand is evaluated only if necessary. Here are some examples:\n\n~~~\n\n 10 or 20 --> 10\n 10 or error() --> 10\n nil or "a" --> "a"\n nil and 10 --> nil\n false and error() --> false\n false and nil --> false\n false or nil --> nil\n 10 and 20 --> 20\n\n~~~","name":"_3_4_5","type":"manual","def":"3.4.5 – Logical Operators"},{"doc":"3.4.8 – Precedence\n\nOperator precedence in Lua follows the table below, from lower to higher priority:\n\n~~~\n\n or\n and\n < > <= >= ~= ==\n |\n ~\n &\n << >>\n ..\n + -\n * / // %\n unary operators (not # - ~)\n ^\n\n~~~\n\nAs usual, you can use parentheses to change the precedences of an expression. The concatenation ('..') and exponentiation ('^') operators are right associative. All other binary operators are left associative.","name":"_3_4_8","type":"manual","def":"3.4.8 – Precedence"},{"doc":"3.2 – Variables\n\nVariables are places that store values. There are three kinds of variables in Lua: global variables, local variables, and table fields.\n\nA single name can denote a global variable or a local variable (or a function's formal parameter, which is a particular kind of local variable):\n\n~~~\n\n\tvar ::= Name\n\n~~~\n\nName denotes identifiers (see §3.1).\n\nAny variable name is assumed to be global unless explicitly declared as a local (see §3.3.7). Local variables are lexically scoped: local variables can be freely accessed by functions defined inside their scope (see §3.5).\n\nBefore the first assignment to a variable, its value is nil.\n\nSquare brackets are used to index a table:\n\n~~~\n\n\tvar ::= prefixexp ‘[’ exp ‘]’\n\n~~~\n\nThe meaning of accesses to table fields can be changed via metatables (see §2.4).\n\nThe syntax var.Name is just syntactic sugar for var[\"Name\"]:\n\n~~~\n\n\tvar ::= prefixexp ‘.’ Name\n\n~~~\n\nAn access to a global variable x is equivalent to _ENV.x. Due to the way that chunks are compiled, the variable _ENV itself is never global (see §2.2).","name":"_3_2","type":"manual","def":"3.2 – Variables"},{"doc":"4.2 – C Closures\n\nWhen a C function is created, it is possible to associate some values with it, thus creating a C closure (see lua_pushcclosure); these values are called upvalues and are accessible to the function whenever it is called.\n\nWhenever a C function is called, its upvalues are located at specific pseudo-indices. These pseudo-indices are produced by the macro lua_upvalueindex. The first upvalue associated with a function is at index lua_upvalueindex(1), and so on. Any access to lua_upvalueindex(n), where n is greater than the number of upvalues of the current function (but not greater than 256, which is one plus the maximum number of upvalues in a closure), produces an acceptable but invalid index.\n\nA C closure can also change the values of its corresponding upvalues.","name":"_4_2","type":"manual","def":"4.2 – C Closures"},{"doc":"2.2 – Environments and the Global Environment\n\nAs we will discuss further in §3.2 and §3.3.3, any reference to a free name (that is, a name not bound to any declaration) var is syntactically translated to _ENV.var. Moreover, every chunk is compiled in the scope of an external local variable named _ENV (see §3.3.2), so _ENV itself is never a free name in a chunk.\n\nDespite the existence of this external _ENV variable and the translation of free names, _ENV is a completely regular name. In particular, you can define new variables and parameters with that name. Each reference to a free name uses the _ENV that is visible at that point in the program, following the usual visibility rules of Lua (see §3.5).\n\nAny table used as the value of _ENV is called an environment.\n\nLua keeps a distinguished environment called the global environment. This value is kept at a special index in the C registry (see §4.3). In Lua, the global variable _G is initialized with this same value. (_G is never used internally, so changing its value will affect only your own code.)\n\nWhen Lua loads a chunk, the default value for its _ENV variable is the global environment (see load). Therefore, by default, free names in Lua code refer to entries in the global environment and, therefore, they are also called global variables. Moreover, all standard libraries are loaded in the global environment and some functions there operate on that environment. You can use load (or loadfile) to load a chunk with a different environment. (In C, you have to load the chunk and then change the value of its first upvalue; see lua_setupvalue.)","name":"_2_2","type":"manual","def":"2.2 – Environments and the Global Environment"},{"doc":"6.10 – The Debug Library\n\nThis library provides the functionality of the debug interface (§4.7) to Lua programs. You should exert care when using this library. Several of its functions violate basic assumptions about Lua code (e.g., that variables local to a function cannot be accessed from outside; that userdata metatables cannot be changed by Lua code; that Lua programs do not crash) and therefore can compromise otherwise secure code. Moreover, some functions in this library may be slow.\n\nAll functions in this library are provided inside the debug table. All functions that operate over a thread have an optional first argument which is the thread to operate over. The default is always the current thread.\n\n--------------------------------------------------------------------------------\n\ndebug.debug ()\n\nEnters an interactive mode with the user, running each string that the user enters. Using simple commands and other debug facilities, the user can inspect global and local variables, change their values, evaluate expressions, and so on. A line containing only the word cont finishes this function, so that the caller continues its execution.\n\nNote that commands for debug.debug are not lexically nested within any function and so have no direct access to local variables.\n\n--------------------------------------------------------------------------------\n\ndebug.gethook ([thread])\n\nReturns the current hook settings of the thread, as three values: the current hook function, the current hook mask, and the current hook count, as set by the debug.sethook function.\n\nReturns fail if there is no active hook.\n\n--------------------------------------------------------------------------------\n\ndebug.getinfo ([thread,] f [, what])\n\nReturns a table with information about a function. You can give the function directly or you can give a number as the value of f, which means the function running at level f of the call stack of the given thread: level 0 is the current function (getinfo itself); level 1 is the function that called getinfo (except for tail calls, which do not count on the stack); and so on. If f is a number greater than the number of active functions, then getinfo returns fail.\n\nThe returned table can contain all the fields returned by lua_getinfo, with the string what describing which fields to fill in. The default for what is to get all information available, except the table of valid lines. If present, the option 'f' adds a field named func with the function itself. If present, the option 'L' adds a field named activelines with the table of valid lines.\n\nFor instance, the expression debug.getinfo(1,\"n\").name returns a name for the current function, if a reasonable name can be found, and the expression debug.getinfo(print) returns a table with all available information about the print function.\n\n--------------------------------------------------------------------------------\n\ndebug.getlocal ([thread,] f, local)\n\nThis function returns the name and the value of the local variable with index local of the function at level f of the stack. This function accesses not only explicit local variables, but also parameters and temporary values.\n\nThe first parameter or local variable has index 1, and so on, following the order that they are declared in the code, counting only the variables that are active in the current scope of the function. Compile-time constants may not appear in this listing, if they were optimized away by the compiler. Negative indices refer to vararg arguments; -1 is the first vararg argument. The function returns fail if there is no variable with the given index, and raises an error when called with a level out of range. (You can call debug.getinfo to check whether the level is valid.)\n\nVariable names starting with '(' (open parenthesis) represent variables with no known names (internal variables such as loop control variables, and variables from chunks saved without debug information).\n\nThe parameter f may also be a function. In that case, getlocal returns only the name of function parameters.\n\n--------------------------------------------------------------------------------\n\ndebug.getmetatable (value)\n\nReturns the metatable of the given value or nil if it does not have a metatable.\n\n--------------------------------------------------------------------------------\n\ndebug.getregistry ()\n\nReturns the registry table (see §4.3).\n\n--------------------------------------------------------------------------------\n\ndebug.getupvalue (f, up)\n\nThis function returns the name and the value of the upvalue with index up of the function f. The function returns fail if there is no upvalue with the given index.\n\n(For Lua functions, upvalues are the external local variables that the function uses, and that are consequently included in its closure.)\n\nFor C functions, this function uses the empty string \"\" as a name for all upvalues.\n\nVariable name '?' (interrogation mark) represents variables with no known names (variables from chunks saved without debug information).\n\n--------------------------------------------------------------------------------\n\ndebug.getuservalue (u, n)\n\nReturns the n-th user value associated to the userdata u plus a boolean, false if the userdata does not have that value.\n\n--------------------------------------------------------------------------------\n\ndebug.setcstacklimit (limit)\n\nSets a new limit for the C stack. This limit controls how deeply nested calls can go in Lua, with the intent of avoiding a stack overflow. A limit too small restricts recursive calls pointlessly; a limit too large exposes the interpreter to stack-overflow crashes. Unfortunately, there is no way to know a priori the maximum safe limit for a platform.\n\nEach call made from Lua code counts one unit. Other operations (e.g., calls made from C to Lua or resuming a coroutine) may have a higher cost.\n\nThis function has the following restrictions:\n\n * It can only be called from the main coroutine (thread);\n * It cannot be called while handling a stack-overflow error;\n * limit must be less than 40000;\n * limit cannot be less than the amount of C stack in use.\n\nIf a call does not respect some restriction, it returns a false value. Otherwise, the call returns the old limit.\n\n--------------------------------------------------------------------------------\n\ndebug.sethook ([thread,] hook, mask [, count])\n\nSets the given function as the debug hook. The string mask and the number count describe when the hook will be called. The string mask may have any combination of the following characters, with the given meaning:\n\n * 'c': the hook is called every time Lua calls a function;\n * 'r': the hook is called every time Lua returns from a function;\n * 'l': the hook is called every time Lua enters a new line of code.\n\nMoreover, with a count different from zero, the hook is called also after every count instructions.\n\nWhen called without arguments, debug.sethook turns off the hook.\n\nWhen the hook is called, its first parameter is a string describing the event that has triggered its call: \"call\", \"tail call\", \"return\", \"line\", and \"count\". For line events, the hook also gets the new line number as its second parameter. Inside a hook, you can call getinfo with level 2 to get more information about the running function. (Level 0 is the getinfo function, and level 1 is the hook function.)\n\n--------------------------------------------------------------------------------\n\ndebug.setlocal ([thread,] level, local, value)\n\nThis function assigns the value value to the local variable with index local of the function at level level of the stack. The function returns fail if there is no local variable with the given index, and raises an error when called with a level out of range. (You can call getinfo to check whether the level is valid.) Otherwise, it returns the name of the local variable.\n\nSee debug.getlocal for more information about variable indices and names.\n\n--------------------------------------------------------------------------------\n\ndebug.setmetatable (value, table)\n\nSets the metatable for the given value to the given table (which can be nil). Returns value.\n\n--------------------------------------------------------------------------------\n\ndebug.setupvalue (f, up, value)\n\nThis function assigns the value value to the upvalue with index up of the function f. The function returns fail if there is no upvalue with the given index. Otherwise, it returns the name of the upvalue.\n\nSee debug.getupvalue for more information about upvalues.\n\n--------------------------------------------------------------------------------\n\ndebug.setuservalue (udata, value, n)\n\nSets the given value as the n-th user value associated to the given udata. udata must be a full userdata.\n\nReturns udata, or fail if the userdata does not have that value.\n\n--------------------------------------------------------------------------------\n\ndebug.traceback ([thread,] [message [, level]])\n\nIf message is present but is neither a string nor nil, this function returns message without further processing. Otherwise, it returns a string with a traceback of the call stack. The optional message string is appended at the beginning of the traceback. An optional level number tells at which level to start the traceback (default is 1, the function calling traceback).\n\n--------------------------------------------------------------------------------\n\ndebug.upvalueid (f, n)\n\nReturns a unique identifier (as a light userdata) for the upvalue numbered n from the given function.\n\nThese unique identifiers allow a program to check whether different closures share upvalues. Lua closures that share an upvalue (that is, that access a same external local variable) will return identical ids for those upvalue indices.\n\n--------------------------------------------------------------------------------\n\ndebug.upvaluejoin (f1, n1, f2, n2)\n\nMake the n1-th upvalue of the Lua closure f1 refer to the n2-th upvalue of the Lua closure f2.","name":"_6_10","type":"manual","def":"6.10 – The Debug Library"},{"doc":"2.5.3 – Garbage-Collection Metamethods\n\nYou can set garbage-collector metamethods for tables and, using the C API, for full userdata (see §2.4). These metamethods, called finalizers, are called when the garbage collector detects that the corresponding table or userdata is dead. Finalizers allow you to coordinate Lua's garbage collection with external resource management such as closing files, network or database connections, or freeing your own memory.\n\nFor an object (table or userdata) to be finalized when collected, you must mark it for finalization.\n\nYou mark an object for finalization when you set its metatable and the metatable has a field indexed by the string "__gc". Note that if you set a metatable without a __gc field and later create that field in the metatable, the object will not be marked for finalization.\n\nWhen a marked object becomes dead, it is not collected immediately by the garbage collector. Instead, Lua puts it in a list. After the collection, Lua goes through that list. For each object in the list, it checks the object's __gc metamethod: If it is present, Lua calls it with the object as its single argument.\n\nAt the end of each garbage-collection cycle, the finalizers are called in the reverse order that the objects were marked for finalization, among those collected in that cycle; that is, the first finalizer to be called is the one associated with the object marked last in the program. The execution of each finalizer may occur at any point during the execution of the regular code.\n\nBecause the object being collected must still be used by the finalizer, that object (and other objects accessible only through it) must be resurrected by Lua. Usually, this resurrection is transient, and the object memory is freed in the next garbage-collection cycle. However, if the finalizer stores the object in some global place (e.g., a global variable), then the resurrection is permanent. Moreover, if the finalizer marks a finalizing object for finalization again, its finalizer will be called again in the next cycle where the object is dead. In any case, the object memory is freed only in a GC cycle where the object is dead and not marked for finalization.\n\nWhen you close a state (see lua_close), Lua calls the finalizers of all objects marked for finalization, following the reverse order that they were marked. If any finalizer marks objects for collection during that phase, these marks have no effect.\n\nFinalizers cannot yield. Except for that, they can do anything, such as raise errors, create new objects, or even run the garbage collector. However, because they can run in unpredictable times, it is good practice to restrict each finalizer to the minimum necessary to properly release its associated resource.\n\nAny error while running a finalizer generates a warning; the error is not propagated.","name":"_2_5_3","type":"manual","def":"2.5.3 – Garbage-Collection Metamethods"},{"doc":"3.4.3 – Coercions and Conversions\n\nLua provides some automatic conversions between some types and representations at run time. Bitwise operators always convert float operands to integers. Exponentiation and float division always convert integer operands to floats. All other arithmetic operations applied to mixed numbers (integers and floats) convert the integer operand to a float. The C API also converts both integers to floats and floats to integers, as needed. Moreover, string concatenation accepts numbers as arguments, besides strings.\n\nIn a conversion from integer to float, if the integer value has an exact representation as a float, that is the result. Otherwise, the conversion gets the nearest higher or the nearest lower representable value. This kind of conversion never fails.\n\nThe conversion from float to integer checks whether the float has an exact representation as an integer (that is, the float has an integral value and it is in the range of integer representation). If it does, that representation is the result. Otherwise, the conversion fails.\n\nSeveral places in Lua coerce strings to numbers when necessary. In particular, the string library sets metamethods that try to coerce strings to numbers in all arithmetic operations. If the conversion fails, the library calls the metamethod of the other operand (if present) or it raises an error. Note that bitwise operators do not do this coercion.\n\nNonetheless, it is always a good practice not to rely on these implicit coercions, as they are not always applied; in particular, \"1\"==1 is false and \"1\"<1 raises an error (see §3.4.4). These coercions exist mainly for compatibility and may be removed in future versions of the language.\n\nA string is converted to an integer or a float following its syntax and the rules of the Lua lexer. The string may have also leading and trailing whitespaces and a sign. All conversions from strings to numbers accept both a dot and the current locale mark as the radix character. (The Lua lexer, however, accepts only a dot.) If the string is not a valid numeral, the conversion fails. If necessary, the result of this first step is then converted to a specific number subtype following the previous rules for conversions between floats and integers.\n\nThe conversion from numbers to strings uses a non-specified human-readable format. To convert numbers to strings in any specific way, use the function string.format.","name":"_3_4_3","type":"manual","def":"3.4.3 – Coercions and Conversions"},{"doc":"3.3.7 – Local Declarations\n\nLocal variables can be declared anywhere inside a block. The declaration can include an initialization:\n\n~~~\n\n\tstat ::= local attnamelist [‘=’ explist]\n\tattnamelist ::= Name attrib {‘,’ Name attrib}\n\n~~~\n\nIf present, an initial assignment has the same semantics of a multiple assignment (see §3.3.3). Otherwise, all variables are initialized with nil.\n\nEach variable name may be postfixed by an attribute (a name between angle brackets):\n\n~~~\n\n\tattrib ::= [‘<’ Name ‘>’]\n\n~~~\n\nThere are two possible attributes: const, which declares a constant variable, that is, a variable that cannot be assigned to after its initialization; and close, which declares a to-be-closed variable (see §3.3.8). A list of variables can contain at most one to-be-closed variable.\n\nA chunk is also a block (see §3.3.2), and so local variables can be declared in a chunk outside any explicit block.\n\nThe visibility rules for local variables are explained in §3.5.","name":"_3_3_7","type":"manual","def":"3.3.7 – Local Declarations"},{"doc":"3.4.10 – Function Calls\n\nA function call in Lua has the following syntax:\n\n~~~\n\n\tfunctioncall ::= prefixexp args\n\n~~~\n\nIn a function call, first prefixexp and args are evaluated. If the value of prefixexp has type function, then this function is called with the given arguments. Otherwise, if present, the prefixexp __call metamethod is called: its first argument is the value of prefixexp, followed by the original call arguments (see §2.4).\n\nThe form\n\n~~~\n\n\tfunctioncall ::= prefixexp ‘:’ Name args\n\n~~~\n\ncan be used to emulate methods. A call v:name(args) is syntactic sugar for v.name(v,args), except that v is evaluated only once.\n\nArguments have the following syntax:\n\n~~~\n\n\targs ::= ‘(’ [explist] ‘)’\n\targs ::= tableconstructor\n\targs ::= LiteralString\n\n~~~\n\nAll argument expressions are evaluated before the call. A call of the form f{fields} is syntactic sugar for f({fields}); that is, the argument list is a single new table. A call of the form f'string' (or f\"string\" or f[[string]]) is syntactic sugar for f('string'); that is, the argument list is a single literal string.\n\nA call of the form return functioncall not in the scope of a to-be-closed variable is called a tail call. Lua implements proper tail calls (or proper tail recursion): in a tail call, the called function reuses the stack entry of the calling function. Therefore, there is no limit on the number of nested tail calls that a program can execute. However, a tail call erases any debug information about the calling function. Note that a tail call only happens with a particular syntax, where the return has one single function call as argument, and it is outside the scope of any to-be-closed variable. This syntax makes the calling function return exactly the returns of the called function, without any intervening action. So, none of the following examples are tail calls:\n\n~~~\n\n return (f(x)) -- results adjusted to 1\n return 2 * f(x) -- result multiplied by 2\n return x, f(x) -- additional results\n f(x); return -- results discarded\n return x or f(x) -- results adjusted to 1\n\n~~~","name":"_3_4_10","type":"manual","def":"3.4.10 – Function Calls"},{"doc":"8.1 – Incompatibilities in the Language\n\n * The coercion of strings to numbers in arithmetic and bitwise operations has been removed from the core language. The string library does a similar job for arithmetic (but not for bitwise) operations using the string metamethods. However, unlike in previous versions, the new implementation preserves the implicit type of the numeral in the string. For instance, the result of \"1\" + \"2\" now is an integer, not a float.\n\n * Literal decimal integer constants that overflow are read as floats, instead of wrapping around. You can use hexadecimal notation for such constants if you want the old behavior (reading them as integers with wrap around).\n\n * The use of the __lt metamethod to emulate __le has been removed. When needed, this metamethod must be explicitly defined.\n\n * The semantics of the numerical for loop over integers changed in some details. In particular, the control variable never wraps around.\n\n * A label for a goto cannot be declared where a label with the same name is visible, even if this other label is declared in an enclosing block.\n\n * When finalizing an object, Lua does not ignore __gc metamethods that are not functions. Any value will be called, if present. (Non-callable values will generate a warning, like any other error when calling a finalizer.)","name":"_8_1","type":"manual","def":"8.1 – Incompatibilities in the Language"},{"doc":"3.3.2 – Chunks\n\nThe unit of compilation of Lua is called a chunk. Syntactically, a chunk is simply a block:\n\n~~~\n\n\tchunk ::= block\n\n~~~\n\nLua handles a chunk as the body of an anonymous function with a variable number of arguments (see §3.4.11). As such, chunks can define local variables, receive arguments, and return values. Moreover, such anonymous function is compiled as in the scope of an external local variable called _ENV (see §2.2). The resulting function always has _ENV as its only external variable, even if it does not use that variable.\n\nA chunk can be stored in a file or in a string inside the host program. To execute a chunk, Lua first loads it, precompiling the chunk's code into instructions for a virtual machine, and then Lua executes the compiled code with an interpreter for the virtual machine.\n\nChunks can also be precompiled into binary form; see the program luac and the function string.dump for details. Programs in source and compiled forms are interchangeable; Lua automatically detects the file type and acts accordingly (see load).","name":"_3_3_2","type":"manual","def":"3.3.2 – Chunks"},{"doc":"6.1 – Basic Functions\n\nThe basic library provides core functions to Lua. If you do not include this library in your application, you should check carefully whether you need to provide implementations for some of its facilities.\n\n--------------------------------------------------------------------------------\n\nassert (v [, message])\n\nRaises an error if the value of its argument v is false (i.e., nil or false); otherwise, returns all its arguments. In case of error, message is the error object; when absent, it defaults to "assertion failed!"\n\n--------------------------------------------------------------------------------\n\ncollectgarbage ([opt [, arg]])\n\nThis function is a generic interface to the garbage collector. It performs different functions according to its first argument, opt:\n\n * "collect": Performs a full garbage-collection cycle. This is the default option.\n\n * "stop": Stops automatic execution of the garbage collector. The collector will run only when explicitly invoked, until a call to restart it.\n\n * "restart": Restarts automatic execution of the garbage collector.\n\n * "count": Returns the total memory in use by Lua in Kbytes. The value has a fractional part, so that it multiplied by 1024 gives the exact number of bytes in use by Lua.\n\n * "step": Performs a garbage-collection step. The step "size" is controlled by arg. With a zero value, the collector will perform one basic (indivisible) step. For non-zero values, the collector will perform as if that amount of memory (in Kbytes) had been allocated by Lua. Returns true if the step finished a collection cycle.\n\n * "isrunning": Returns a boolean that tells whether the collector is running (i.e., not stopped).\n\n * "incremental": Change the collector mode to incremental. This option can be followed by three numbers: the garbage-collector pause, the step multiplier, and the step size (see §2.5.1). A zero means to not change that value.\n\n * "generational": Change the collector mode to generational. This option can be followed by two numbers: the garbage-collector minor multiplier and the major multiplier (see §2.5.2). A zero means to not change that value.\n\nSee §2.5 for more details about garbage collection and some of these options.\n\n--------------------------------------------------------------------------------\n\ndofile ([filename])\n\nOpens the named file and executes its content as a Lua chunk. When called without arguments, dofile executes the content of the standard input (stdin). Returns all values returned by the chunk. In case of errors, dofile propagates the error to its caller. (That is, dofile does not run in protected mode.)\n\n--------------------------------------------------------------------------------\n\nerror (message [, level])\n\nRaises an error (see §2.3) with @{message} as the error object. This function never returns.\n\nUsually, error adds some information about the error position at the beginning of the message, if the message is a string. The level argument specifies how to get the error position. With level 1 (the default), the error position is where the error function was called. Level 2 points the error to where the function that called error was called; and so on. Passing a level 0 avoids the addition of error position information to the message.\n\n--------------------------------------------------------------------------------\n\n_G\n\nA global variable (not a function) that holds the global environment (see §2.2). Lua itself does not use this variable; changing its value does not affect any environment, nor vice versa.\n\n--------------------------------------------------------------------------------\n\ngetmetatable (object)\n\nIf object does not have a metatable, returns nil. Otherwise, if the object's metatable has a __metatable field, returns the associated value. Otherwise, returns the metatable of the given object.\n\n--------------------------------------------------------------------------------\n\nipairs (t)\n\nReturns three values (an iterator function, the table t, and 0) so that the construction\n\n~~~\n\n for i,v in ipairs(t) do body end\n\n~~~\n\nwill iterate over the key–value pairs (1,t[1]), (2,t[2]), ..., up to the first absent index.\n\n--------------------------------------------------------------------------------\n\nload (chunk [, chunkname [, mode [, env]]])\n\nLoads a chunk.\n\nIf chunk is a string, the chunk is this string. If chunk is a function, load calls it repeatedly to get the chunk pieces. Each call to chunk must return a string that concatenates with previous results. A return of an empty string, nil, or no value signals the end of the chunk.\n\nIf there are no syntactic errors, load returns the compiled chunk as a function; otherwise, it returns fail plus the error message.\n\nWhen you load a main chunk, the resulting function will always have exactly one upvalue, the _ENV variable (see §2.2). However, when you load a binary chunk created from a function (see string.dump), the resulting function can have an arbitrary number of upvalues, and there is no guarantee that its first upvalue will be the _ENV variable. (A non-main function may not even have an _ENV upvalue.)\n\nRegardless, if the resulting function has any upvalues, its first upvalue is set to the value of env, if that parameter is given, or to the value of the global environment. Other upvalues are initialized with nil. All upvalues are fresh, that is, they are not shared with any other function.\n\nchunkname is used as the name of the chunk for error messages and debug information (see §4.7). When absent, it defaults to chunk, if chunk is a string, or to "=(load)" otherwise.\n\nThe string mode controls whether the chunk can be text or binary (that is, a precompiled chunk). It may be the string "b" (only binary chunks), "t" (only text chunks), or "bt" (both binary and text). The default is "bt".\n\nLua does not check the consistency of binary chunks. Maliciously crafted binary chunks can crash the interpreter.\n\n--------------------------------------------------------------------------------\n\nloadfile ([filename [, mode [, env]]])\n\nSimilar to load, but gets the chunk from file filename or from the standard input, if no file name is given.\n\n--------------------------------------------------------------------------------\n\nnext (table [, index])\n\nAllows a program to traverse all fields of a table. Its first argument is a table and its second argument is an index in this table. A call to next returns the next index of the table and its associated value. When called with nil as its second argument, next returns an initial index and its associated value. When called with the last index, or with nil in an empty table, next returns nil. If the second argument is absent, then it is interpreted as nil. In particular, you can use next(t) to check whether a table is empty.\n\nThe order in which the indices are enumerated is not specified, even for numeric indices. (To traverse a table in numerical order, use a numerical for.)\n\nThe behavior of next is undefined if, during the traversal, you assign any value to a non-existent field in the table. You may however modify existing fields. In particular, you may set existing fields to nil.\n\n--------------------------------------------------------------------------------\n\npairs (t)\n\nIf t has a metamethod __pairs, calls it with t as argument and returns the first three results from the call.\n\nOtherwise, returns three values: the next function, the table t, and nil, so that the construction\n\n~~~\n\n for k,v in pairs(t) do body end\n\n~~~\n\nwill iterate over all key–value pairs of table t.\n\nSee function next for the caveats of modifying the table during its traversal.\n\n--------------------------------------------------------------------------------\n\npcall (f [, arg1, ···])\n\nCalls the function f with the given arguments in protected mode. This means that any error inside f is not propagated; instead, pcall catches the error and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. In such case, pcall also returns all results from the call, after this first result. In case of any error, pcall returns false plus the error object. Note that errors caught by pcall do not call a message handler.\n\n--------------------------------------------------------------------------------\n\nprint (···)\n\nReceives any number of arguments and prints their values to stdout, converting each argument to a string following the same rules of tostring.\n\nThe function print is not intended for formatted output, but only as a quick way to show a value, for instance for debugging. For complete control over the output, use string.format and io.write.\n\n--------------------------------------------------------------------------------\n\nrawequal (v1, v2)\n\nChecks whether v1 is equal to v2, without invoking the __eq metamethod. Returns a boolean.\n\n--------------------------------------------------------------------------------\n\nrawget (table, index)\n\nGets the real value of table[index], without using the __index metavalue. table must be a table; index may be any value.\n\n--------------------------------------------------------------------------------\n\nrawlen (v)\n\nReturns the length of the object v, which must be a table or a string, without invoking the __len metamethod. Returns an integer.\n\n--------------------------------------------------------------------------------\n\nrawset (table, index, value)\n\nSets the real value of table[index] to value, without using the __newindex metavalue. table must be a table, index any value different from nil and NaN, and value any Lua value.\n\nThis function returns table.\n\n--------------------------------------------------------------------------------\n\nselect (index, ···)\n\nIf index is a number, returns all arguments after argument number index; a negative number indexes from the end (-1 is the last argument). Otherwise, index must be the string \"#\", and select returns the total number of extra arguments it received.\n\n--------------------------------------------------------------------------------\n\nsetmetatable (table, metatable)\n\nSets the metatable for the given table. If metatable is nil, removes the metatable of the given table. If the original metatable has a __metatable field, raises an error.\n\nThis function returns table.\n\nTo change the metatable of other types from Lua code, you must use the debug library (§6.10).\n\n--------------------------------------------------------------------------------\n\ntonumber (e [, base])\n\nWhen called with no base, tonumber tries to convert its argument to a number. If the argument is already a number or a string convertible to a number, then tonumber returns this number; otherwise, it returns fail.\n\nThe conversion of strings can result in integers or floats, according to the lexical conventions of Lua (see §3.1). The string may have leading and trailing spaces and a sign.\n\nWhen called with base, then e must be a string to be interpreted as an integer numeral in that base. The base may be any integer between 2 and 36, inclusive. In bases above 10, the letter 'A' (in either upper or lower case) represents 10, 'B' represents 11, and so forth, with 'Z' representing 35. If the string e is not a valid numeral in the given base, the function returns fail.\n\n--------------------------------------------------------------------------------\n\ntostring (v)\n\nReceives a value of any type and converts it to a string in a human-readable format.\n\nIf the metatable of v has a __tostring field, then tostring calls the corresponding value with v as argument, and uses the result of the call as its result. Otherwise, if the metatable of v has a __name field with a string value, tostring may use that string in its final result.\n\nFor complete control of how numbers are converted, use string.format.\n\n--------------------------------------------------------------------------------\n\ntype (v)\n\nReturns the type of its only argument, coded as a string. The possible results of this function are "nil" (a string, not the value nil), "number", "string", "boolean", "table", "function", "thread", and "userdata".\n\n--------------------------------------------------------------------------------\n\n_VERSION\n\nA global variable (not a function) that holds a string containing the running Lua version. The current value of this variable is "Lua 5.4".\n\n--------------------------------------------------------------------------------\n\nwarn (msg1, ···)\n\nEmits a warning with a message composed by the concatenation of all its arguments (which should be strings).\n\nBy convention, a one-piece message starting with '@' is intended to be a control message, which is a message to the warning system itself. In particular, the standard warning function in Lua recognizes the control messages "@off", to stop the emission of warnings, and "@on", to (re)start the emission; it ignores unknown control messages.\n\n--------------------------------------------------------------------------------\n\nxpcall (f, msgh [, arg1, ···])\n\nThis function is similar to pcall, except that it sets a new message handler msgh.","name":"_6_1","type":"manual","def":"6.1 – Basic Functions"},{"doc":"5.1 – Functions and Types\n\nHere we list all functions and types from the auxiliary library in alphabetical order.\n\n--------------------------------------------------------------------------------\n\nluaL_addchar\n\n[-?, +?, m]\n\n~~~\nvoid luaL_addchar (luaL_Buffer *B, char c);\n~~~\n\nAdds the byte c to the buffer B (see luaL_Buffer).\n\n--------------------------------------------------------------------------------\n\nluaL_addgsub\n\n[-0, +0, m]\n\n~~~\nconst void luaL_addgsub (luaL_Buffer *B, const char *s,\n const char *p, const char *r);\n~~~\n\nAdds a copy of the string s to the buffer B (see luaL_Buffer), replacing any occurrence of the string p with the string r.\n\n--------------------------------------------------------------------------------\n\nluaL_addlstring\n\n[-?, +?, m]\n\n~~~\nvoid luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);\n~~~\n\nAdds the string pointed to by s with length l to the buffer B (see luaL_Buffer). The string can contain embedded zeros.\n\n--------------------------------------------------------------------------------\n\nluaL_addsize\n\n[-?, +?, –]\n\n~~~\nvoid luaL_addsize (luaL_Buffer *B, size_t n);\n~~~\n\nAdds to the buffer B a string of length n previously copied to the buffer area (see luaL_prepbuffer).\n\n--------------------------------------------------------------------------------\n\nluaL_addstring\n\n[-?, +?, m]\n\n~~~\nvoid luaL_addstring (luaL_Buffer *B, const char *s);\n~~~\n\nAdds the zero-terminated string pointed to by s to the buffer B (see luaL_Buffer).\n\n--------------------------------------------------------------------------------\n\nluaL_addvalue\n\n[-1, +?, m]\n\n~~~\nvoid luaL_addvalue (luaL_Buffer *B);\n~~~\n\nAdds the value on the top of the stack to the buffer B (see luaL_Buffer). Pops the value.\n\nThis is the only function on string buffers that can (and must) be called with an extra element on the stack, which is the value to be added to the buffer.\n\n--------------------------------------------------------------------------------\n\nluaL_argcheck\n\n[-0, +0, v]\n\n~~~\nvoid luaL_argcheck (lua_State *L,\n int cond,\n int arg,\n const char *extramsg);\n~~~\n\nChecks whether cond is true. If it is not, raises an error with a standard message (see luaL_argerror).\n\n--------------------------------------------------------------------------------\n\nluaL_argerror\n\n[-0, +0, v]\n\n~~~\nint luaL_argerror (lua_State *L, int arg, const char *extramsg);\n~~~\n\nRaises an error reporting a problem with argument arg of the C function that called it, using a standard message that includes extramsg as a comment:\n\n~~~\n\n bad argument #arg to 'funcname' (extramsg)\n\n~~~\n\nThis function never returns.\n\n--------------------------------------------------------------------------------\n\nluaL_argexpected\n\n[-0, +0, v]\n\n~~~\nvoid luaL_argexpected (lua_State *L,\n int cond,\n int arg,\n const char *tname);\n~~~\n\nChecks whether cond is true. If it is not, raises an error about the type of the argument arg with a standard message (see luaL_typeerror).\n\n--------------------------------------------------------------------------------\n\nluaL_Buffer\n\n~~~\ntypedef struct luaL_Buffer luaL_Buffer;\n~~~\n\nType for a string buffer.\n\nA string buffer allows C code to build Lua strings piecemeal. Its pattern of use is as follows:\n\n * First declare a variable b of type luaL_Buffer.\n\n * Then initialize it with a call luaL_buffinit(L, &b).\n\n * Then add string pieces to the buffer calling any of the luaL_add* functions.\n\n * Finish by calling luaL_pushresult(&b). This call leaves the final string on the top of the stack.\n\nIf you know beforehand the maximum size of the resulting string, you can use the buffer like this:\n\n * First declare a variable b of type luaL_Buffer.\n\n * Then initialize it and preallocate a space of size sz with a call luaL_buffinitsize(L, &b, sz).\n\n * Then produce the string into that space.\n\n * Finish by calling luaL_pushresultsize(&b, sz), where sz is the total size of the resulting string copied into that space (which may be less than or equal to the preallocated size).\n\nDuring its normal operation, a string buffer uses a variable number of stack slots. So, while using a buffer, you cannot assume that you know where the top of the stack is. You can use the stack between successive calls to buffer operations as long as that use is balanced; that is, when you call a buffer operation, the stack is at the same level it was immediately after the previous buffer operation. (The only exception to this rule is luaL_addvalue.) After calling luaL_pushresult, the stack is back to its level when the buffer was initialized, plus the final string on its top.\n\n--------------------------------------------------------------------------------\n\nluaL_buffaddr\n\n[-0, +0, –]\n\n~~~\nchar *luaL_buffaddr (luaL_Buffer *B);\n~~~\n\nReturns the address of the current content of buffer B (see luaL_Buffer). Note that any addition to the buffer may invalidate this address.\n\n--------------------------------------------------------------------------------\n\nluaL_buffinit\n\n[-0, +0, –]\n\n~~~\nvoid luaL_buffinit (lua_State *L, luaL_Buffer *B);\n~~~\n\nInitializes a buffer B (see luaL_Buffer). This function does not allocate any space; the buffer must be declared as a variable.\n\n--------------------------------------------------------------------------------\n\nluaL_bufflen\n\n[-0, +0, –]\n\n~~~\nsize_t luaL_bufflen (luaL_Buffer *B);\n~~~\n\nReturns the length of the current content of buffer B (see luaL_Buffer).\n\n--------------------------------------------------------------------------------\n\nluaL_buffinitsize\n\n[-?, +?, m]\n\n~~~\nchar *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);\n~~~\n\nEquivalent to the sequence luaL_buffinit, luaL_prepbuffsize.\n\n--------------------------------------------------------------------------------\n\nluaL_buffsub\n\n[-0, +0, –]\n\n~~~\nvoid luaL_buffsub (luaL_Buffer *B, int n);\n~~~\n\nRemoves n bytes from the the buffer B (see luaL_Buffer). The buffer must have at least that many bytes.\n\n--------------------------------------------------------------------------------\n\nluaL_callmeta\n\n[-0, +(0|1), e]\n\n~~~\nint luaL_callmeta (lua_State *L, int obj, const char *e);\n~~~\n\nCalls a metamethod.\n\nIf the object at index obj has a metatable and this metatable has a field e, this function calls this field passing the object as its only argument. In this case this function returns true and pushes onto the stack the value returned by the call. If there is no metatable or no metamethod, this function returns false without pushing any value on the stack.\n\n--------------------------------------------------------------------------------\n\nluaL_checkany\n\n[-0, +0, v]\n\n~~~\nvoid luaL_checkany (lua_State *L, int arg);\n~~~\n\nChecks whether the function has an argument of any type (including nil) at position arg.\n\n--------------------------------------------------------------------------------\n\nluaL_checkinteger\n\n[-0, +0, v]\n\n~~~\nlua_Integer luaL_checkinteger (lua_State *L, int arg);\n~~~\n\nChecks whether the function argument arg is an integer (or can be converted to an integer) and returns this integer.\n\n--------------------------------------------------------------------------------\n\nluaL_checklstring\n\n[-0, +0, v]\n\n~~~\nconst char *luaL_checklstring (lua_State *L, int arg, size_t *l);\n~~~\n\nChecks whether the function argument arg is a string and returns this string; if l is not NULL fills its referent with the string's length.\n\nThis function uses lua_tolstring to get its result, so all conversions and caveats of that function apply here.\n\n--------------------------------------------------------------------------------\n\nluaL_checknumber\n\n[-0, +0, v]\n\n~~~\nlua_Number luaL_checknumber (lua_State *L, int arg);\n~~~\n\nChecks whether the function argument arg is a number and returns this number converted to a lua_Number.\n\n--------------------------------------------------------------------------------\n\nluaL_checkoption\n\n[-0, +0, v]\n\n~~~\nint luaL_checkoption (lua_State *L,\n int arg,\n const char *def,\n const char *const lst[]);\n~~~\n\nChecks whether the function argument arg is a string and searches for this string in the array lst (which must be NULL-terminated). Returns the index in the array where the string was found. Raises an error if the argument is not a string or if the string cannot be found.\n\nIf def is not NULL, the function uses def as a default value when there is no argument arg or when this argument is nil.\n\nThis is a useful function for mapping strings to C enums. (The usual convention in Lua libraries is to use strings instead of numbers to select options.)\n\n--------------------------------------------------------------------------------\n\nluaL_checkstack\n\n[-0, +0, v]\n\n~~~\nvoid luaL_checkstack (lua_State *L, int sz, const char *msg);\n~~~\n\nGrows the stack size to top + sz elements, raising an error if the stack cannot grow to that size. msg is an additional text to go into the error message (or NULL for no additional text).\n\n--------------------------------------------------------------------------------\n\nluaL_checkstring\n\n[-0, +0, v]\n\n~~~\nconst char *luaL_checkstring (lua_State *L, int arg);\n~~~\n\nChecks whether the function argument arg is a string and returns this string.\n\nThis function uses lua_tolstring to get its result, so all conversions and caveats of that function apply here.\n\n--------------------------------------------------------------------------------\n\nluaL_checktype\n\n[-0, +0, v]\n\n~~~\nvoid luaL_checktype (lua_State *L, int arg, int t);\n~~~\n\nChecks whether the function argument arg has type t. See lua_type for the encoding of types for t.\n\n--------------------------------------------------------------------------------\n\nluaL_checkudata\n\n[-0, +0, v]\n\n~~~\nvoid *luaL_checkudata (lua_State *L, int arg, const char *tname);\n~~~\n\nChecks whether the function argument arg is a userdata of the type tname (see luaL_newmetatable) and returns the userdata's memory-block address (see lua_touserdata).\n\n--------------------------------------------------------------------------------\n\nluaL_checkversion\n\n[-0, +0, v]\n\n~~~\nvoid luaL_checkversion (lua_State *L);\n~~~\n\nChecks whether the code making the call and the Lua library being called are using the same version of Lua and the same numeric types.\n\n--------------------------------------------------------------------------------\n\nluaL_dofile\n\n[-0, +?, m]\n\n~~~\nint luaL_dofile (lua_State *L, const char *filename);\n~~~\n\nLoads and runs the given file. It is defined as the following macro:\n\n~~~\n\n (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))\n\n~~~\n\nIt returns LUA_OK if there are no errors, or an error code in case of errors (see §4.4.1).\n\n--------------------------------------------------------------------------------\n\nluaL_dostring\n\n[-0, +?, –]\n\n~~~\nint luaL_dostring (lua_State *L, const char *str);\n~~~\n\nLoads and runs the given string. It is defined as the following macro:\n\n~~~\n\n (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))\n\n~~~\n\nIt returns LUA_OK if there are no errors, or an error code in case of errors (see §4.4.1).\n\n--------------------------------------------------------------------------------\n\nluaL_error\n\n[-0, +0, v]\n\n~~~\nint luaL_error (lua_State *L, const char *fmt, ...);\n~~~\n\nRaises an error. The error message format is given by fmt plus any extra arguments, following the same rules of lua_pushfstring. It also adds at the beginning of the message the file name and the line number where the error occurred, if this information is available.\n\nThis function never returns, but it is an idiom to use it in C functions as return luaL_error(args).\n\n--------------------------------------------------------------------------------\n\nluaL_execresult\n\n[-0, +3, m]\n\n~~~\nint luaL_execresult (lua_State *L, int stat);\n~~~\n\nThis function produces the return values for process-related functions in the standard library (os.execute and io.close).\n\n--------------------------------------------------------------------------------\n\nluaL_fileresult\n\n[-0, +(1|3), m]\n\n~~~\nint luaL_fileresult (lua_State *L, int stat, const char *fname);\n~~~\n\nThis function produces the return values for file-related functions in the standard library (io.open, os.rename, file:seek, etc.).\n\n--------------------------------------------------------------------------------\n\nluaL_getmetafield\n\n[-0, +(0|1), m]\n\n~~~\nint luaL_getmetafield (lua_State *L, int obj, const char *e);\n~~~\n\nPushes onto the stack the field e from the metatable of the object at index obj and returns the type of the pushed value. If the object does not have a metatable, or if the metatable does not have this field, pushes nothing and returns LUA_TNIL.\n\n--------------------------------------------------------------------------------\n\nluaL_getmetatable\n\n[-0, +1, m]\n\n~~~\nint luaL_getmetatable (lua_State *L, const char *tname);\n~~~\n\nPushes onto the stack the metatable associated with the name tname in the registry (see luaL_newmetatable), or nil if there is no metatable associated with that name. Returns the type of the pushed value.\n\n--------------------------------------------------------------------------------\n\nluaL_getsubtable\n\n[-0, +1, e]\n\n~~~\nint luaL_getsubtable (lua_State *L, int idx, const char *fname);\n~~~\n\nEnsures that the value t[fname], where t is the value at index idx, is a table, and pushes that table onto the stack. Returns true if it finds a previous table there and false if it creates a new table.\n\n--------------------------------------------------------------------------------\n\nluaL_gsub\n\n[-0, +1, m]\n\n~~~\nconst char *luaL_gsub (lua_State *L,\n const char *s,\n const char *p,\n const char *r);\n~~~\n\nCreates a copy of string s, replacing any occurrence of the string p with the string r. Pushes the resulting string on the stack and returns it.\n\n--------------------------------------------------------------------------------\n\nluaL_len\n\n[-0, +0, e]\n\n~~~\nlua_Integer luaL_len (lua_State *L, int index);\n~~~\n\nReturns the "length" of the value at the given index as a number; it is equivalent to the '#' operator in Lua (see §3.4.7). Raises an error if the result of the operation is not an integer. (This case can only happen through metamethods.)\n\n--------------------------------------------------------------------------------\n\nluaL_loadbuffer\n\n[-0, +1, –]\n\n~~~\nint luaL_loadbuffer (lua_State *L,\n const char *buff,\n size_t sz,\n const char *name);\n~~~\n\nEquivalent to luaL_loadbufferx with mode equal to NULL.\n\n--------------------------------------------------------------------------------\n\nluaL_loadbufferx\n\n[-0, +1, –]\n\n~~~\nint luaL_loadbufferx (lua_State *L,\n const char *buff,\n size_t sz,\n const char *name,\n const char *mode);\n~~~\n\nLoads a buffer as a Lua chunk. This function uses lua_load to load the chunk in the buffer pointed to by buff with size sz.\n\nThis function returns the same results as lua_load. name is the chunk name, used for debug information and error messages. The string mode works as in the function lua_load.\n\n--------------------------------------------------------------------------------\n\nluaL_loadfile\n\n[-0, +1, m]\n\n~~~\nint luaL_loadfile (lua_State *L, const char *filename);\n~~~\n\nEquivalent to luaL_loadfilex with mode equal to NULL.\n\n--------------------------------------------------------------------------------\n\nluaL_loadfilex\n\n[-0, +1, m]\n\n~~~\nint luaL_loadfilex (lua_State *L, const char *filename,\n const char *mode);\n~~~\n\nLoads a file as a Lua chunk. This function uses lua_load to load the chunk in the file named filename. If filename is NULL, then it loads from the standard input. The first line in the file is ignored if it starts with a #.\n\nThe string mode works as in the function lua_load.\n\nThis function returns the same results as lua_load or LUA_ERRFILE for file-related errors.\n\nAs lua_load, this function only loads the chunk; it does not run it.\n\n--------------------------------------------------------------------------------\n\nluaL_loadstring\n\n[-0, +1, –]\n\n~~~\nint luaL_loadstring (lua_State *L, const char *s);\n~~~\n\nLoads a string as a Lua chunk. This function uses lua_load to load the chunk in the zero-terminated string s.\n\nThis function returns the same results as lua_load.\n\nAlso as lua_load, this function only loads the chunk; it does not run it.\n\n--------------------------------------------------------------------------------\n\nluaL_newlib\n\n[-0, +1, m]\n\n~~~\nvoid luaL_newlib (lua_State *L, const luaL_Reg l[]);\n~~~\n\nCreates a new table and registers there the functions in the list l.\n\nIt is implemented as the following macro:\n\n~~~\n\n (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))\n\n~~~\n\nThe array l must be the actual array, not a pointer to it.\n\n--------------------------------------------------------------------------------\n\nluaL_newlibtable\n\n[-0, +1, m]\n\n~~~\nvoid luaL_newlibtable (lua_State *L, const luaL_Reg l[]);\n~~~\n\nCreates a new table with a size optimized to store all entries in the array l (but does not actually store them). It is intended to be used in conjunction with luaL_setfuncs (see luaL_newlib).\n\nIt is implemented as a macro. The array l must be the actual array, not a pointer to it.\n\n--------------------------------------------------------------------------------\n\nluaL_newmetatable\n\n[-0, +1, m]\n\n~~~\nint luaL_newmetatable (lua_State *L, const char *tname);\n~~~\n\nIf the registry already has the key tname, returns 0. Otherwise, creates a new table to be used as a metatable for userdata, adds to this new table the pair __name = tname, adds to the registry the pair [tname] = new table, and returns 1.\n\nIn both cases, the function pushes onto the stack the final value associated with tname in the registry.\n\n--------------------------------------------------------------------------------\n\nluaL_newstate\n\n[-0, +0, –]\n\n~~~\nlua_State *luaL_newstate (void);\n~~~\n\nCreates a new Lua state. It calls lua_newstate with an allocator based on the standard C allocation functions and then sets a warning function and a panic function (see §4.4) that print messages to the standard error output.\n\nReturns the new state, or NULL if there is a memory allocation error.\n\n--------------------------------------------------------------------------------\n\nluaL_openlibs\n\n[-0, +0, e]\n\n~~~\nvoid luaL_openlibs (lua_State *L);\n~~~\n\nOpens all standard Lua libraries into the given state.\n\n--------------------------------------------------------------------------------\n\nluaL_opt\n\n[-0, +0, –]\n\n~~~\nT luaL_opt (L, func, arg, dflt);\n~~~\n\nThis macro is defined as follows:\n\n~~~\n\n (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))\n\n~~~\n\nIn words, if the argument arg is nil or absent, the macro results in the default dflt. Otherwise, it results in the result of calling func with the state L and the argument index arg as arguments. Note that it evaluates the expression dflt only if needed.\n\n--------------------------------------------------------------------------------\n\nluaL_optinteger\n\n[-0, +0, v]\n\n~~~\nlua_Integer luaL_optinteger (lua_State *L,\n int arg,\n lua_Integer d);\n~~~\n\nIf the function argument arg is an integer (or it is convertible to an integer), returns this integer. If this argument is absent or is nil, returns d. Otherwise, raises an error.\n\n--------------------------------------------------------------------------------\n\nluaL_optlstring\n\n[-0, +0, v]\n\n~~~\nconst char *luaL_optlstring (lua_State *L,\n int arg,\n const char *d,\n size_t *l);\n~~~\n\nIf the function argument arg is a string, returns this string. If this argument is absent or is nil, returns d. Otherwise, raises an error.\n\nIf l is not NULL, fills its referent with the result's length. If the result is NULL (only possible when returning d and d == NULL), its length is considered zero.\n\nThis function uses lua_tolstring to get its result, so all conversions and caveats of that function apply here.\n\n--------------------------------------------------------------------------------\n\nluaL_optnumber\n\n[-0, +0, v]\n\n~~~\nlua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);\n~~~\n\nIf the function argument arg is a number, returns this number as a lua_Number. If this argument is absent or is nil, returns d. Otherwise, raises an error.\n\n--------------------------------------------------------------------------------\n\nluaL_optstring\n\n[-0, +0, v]\n\n~~~\nconst char *luaL_optstring (lua_State *L,\n int arg,\n const char *d);\n~~~\n\nIf the function argument arg is a string, returns this string. If this argument is absent or is nil, returns d. Otherwise, raises an error.\n\n--------------------------------------------------------------------------------\n\nluaL_prepbuffer\n\n[-?, +?, m]\n\n~~~\nchar *luaL_prepbuffer (luaL_Buffer *B);\n~~~\n\nEquivalent to luaL_prepbuffsize with the predefined size LUAL_BUFFERSIZE.\n\n--------------------------------------------------------------------------------\n\nluaL_prepbuffsize\n\n[-?, +?, m]\n\n~~~\nchar *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);\n~~~\n\nReturns an address to a space of size sz where you can copy a string to be added to buffer B (see luaL_Buffer). After copying the string into this space you must call luaL_addsize with the size of the string to actually add it to the buffer.\n\n--------------------------------------------------------------------------------\n\nluaL_pushfail\n\n[-0, +1, –]\n\n~~~\nvoid luaL_pushfail (lua_State *L);\n~~~\n\nPushes the fail value onto the stack (see §6).\n\n--------------------------------------------------------------------------------\n\nluaL_pushresult\n\n[-?, +1, m]\n\n~~~\nvoid luaL_pushresult (luaL_Buffer *B);\n~~~\n\nFinishes the use of buffer B leaving the final string on the top of the stack.\n\n--------------------------------------------------------------------------------\n\nluaL_pushresultsize\n\n[-?, +1, m]\n\n~~~\nvoid luaL_pushresultsize (luaL_Buffer *B, size_t sz);\n~~~\n\nEquivalent to the sequence luaL_addsize, luaL_pushresult.\n\n--------------------------------------------------------------------------------\n\nluaL_ref\n\n[-1, +0, m]\n\n~~~\nint luaL_ref (lua_State *L, int t);\n~~~\n\nCreates and returns a reference, in the table at index t, for the object on the top of the stack (and pops the object).\n\nA reference is a unique integer key. As long as you do not manually add integer keys into the table t, luaL_ref ensures the uniqueness of the key it returns. You can retrieve an object referred by the reference r by calling lua_rawgeti(L, t, r). The function luaL_unref frees a reference.\n\nIf the object on the top of the stack is nil, luaL_ref returns the constant LUA_REFNIL. The constant LUA_NOREF is guaranteed to be different from any reference returned by luaL_ref.\n\n--------------------------------------------------------------------------------\n\nluaL_Reg\n\n~~~\ntypedef struct luaL_Reg {\n const char *name;\n lua_CFunction func; } luaL_Reg;\n~~~\n\nType for arrays of functions to be registered by luaL_setfuncs. name is the function name and func is a pointer to the function. Any array of luaL_Reg must end with a sentinel entry in which both name and func are NULL.\n\n--------------------------------------------------------------------------------\n\nluaL_requiref\n\n[-0, +1, e]\n\n~~~\nvoid luaL_requiref (lua_State *L, const char *modname,\n lua_CFunction openf, int glb);\n~~~\n\nIf package.loaded[modname] is not true, calls the function openf with the string modname as an argument and sets the call result to package.loaded[modname], as if that function has been called through require.\n\nIf glb is true, also stores the module into the global modname.\n\nLeaves a copy of the module on the stack.\n\n--------------------------------------------------------------------------------\n\nluaL_setfuncs\n\n[-nup, +0, m]\n\n~~~\nvoid luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);\n~~~\n\nRegisters all functions in the array l (see luaL_Reg) into the table on the top of the stack (below optional upvalues, see next).\n\nWhen nup is not zero, all functions are created with nup upvalues, initialized with copies of the nup values previously pushed on the stack on top of the library table. These values are popped from the stack after the registration.\n\n--------------------------------------------------------------------------------\n\nluaL_setmetatable\n\n[-0, +0, –]\n\n~~~\nvoid luaL_setmetatable (lua_State *L, const char *tname);\n~~~\n\nSets the metatable of the object on the top of the stack as the metatable associated with name tname in the registry (see luaL_newmetatable).\n\n--------------------------------------------------------------------------------\n\nluaL_Stream\n\n~~~\ntypedef struct luaL_Stream {\n FILE *f;\n lua_CFunction closef; } luaL_Stream;\n~~~\n\nThe standard representation for file handles used by the standard I/O library.\n\nA file handle is implemented as a full userdata, with a metatable called LUA_FILEHANDLE (where LUA_FILEHANDLE is a macro with the actual metatable's name). The metatable is created by the I/O library (see luaL_newmetatable).\n\nThis userdata must start with the structure luaL_Stream; it can contain other data after this initial structure. The field f points to the corresponding C stream (or it can be NULL to indicate an incompletely created handle). The field closef points to a Lua function that will be called to close the stream when the handle is closed or collected; this function receives the file handle as its sole argument and must return either a true value, in case of success, or a false value plus an error message, in case of error. Once Lua calls this field, it changes the field value to NULL to signal that the handle is closed.\n\n--------------------------------------------------------------------------------\n\nluaL_testudata\n\n[-0, +0, m]\n\n~~~\nvoid *luaL_testudata (lua_State *L, int arg, const char *tname);\n~~~\n\nThis function works like luaL_checkudata, except that, when the test fails, it returns NULL instead of raising an error.\n\n--------------------------------------------------------------------------------\n\nluaL_tolstring\n\n[-0, +1, e]\n\n~~~\nconst char *luaL_tolstring (lua_State *L, int idx, size_t *len);\n~~~\n\nConverts any Lua value at the given index to a C string in a reasonable format. The resulting string is pushed onto the stack and also returned by the function. If len is not NULL, the function also sets *len with the string length.\n\nIf the value has a metatable with a __tostring field, then luaL_tolstring calls the corresponding metamethod with the value as argument, and uses the result of the call as its result.\n\n--------------------------------------------------------------------------------\n\nluaL_traceback\n\n[-0, +1, m]\n\n~~~\nvoid luaL_traceback (lua_State *L, lua_State *L1, const char *msg,\n int level);\n~~~\n\nCreates and pushes a traceback of the stack L1. If msg is not NULL, it is appended at the beginning of the traceback. The level parameter tells at which level to start the traceback.\n\n--------------------------------------------------------------------------------\n\nluaL_typeerror\n\n[-0, +0, v]\n\n~~~\nconst char *luaL_typeerror (lua_State *L,\n int arg,\n const char *tname);\n~~~\n\nRaises a type error for the argument arg of the C function that called it, using a standard message; tname is a "name" for the expected type. This function never returns.\n\n--------------------------------------------------------------------------------\n\nluaL_typename\n\n[-0, +0, –]\n\n~~~\nconst char *luaL_typename (lua_State *L, int index);\n~~~\n\nReturns the name of the type of the value at the given index.\n\n--------------------------------------------------------------------------------\n\nluaL_unref\n\n[-0, +0, –]\n\n~~~\nvoid luaL_unref (lua_State *L, int t, int ref);\n~~~\n\nReleases the reference ref from the table at index t (see luaL_ref). The entry is removed from the table, so that the referred object can be collected. The reference ref is also freed to be used again.\n\nIf ref is LUA_NOREF or LUA_REFNIL, luaL_unref does nothing.\n\n--------------------------------------------------------------------------------\n\nluaL_where\n\n[-0, +1, m]\n\n~~~\nvoid luaL_where (lua_State *L, int lvl);\n~~~\n\nPushes onto the stack a string identifying the current position of the control at level lvl in the call stack. Typically this string has the following format:\n\n~~~\n\n chunkname:currentline:\n\n~~~\n\nLevel 0 is the running function, level 1 is the function that called the running function, etc.\n\nThis function is used to build a prefix for error messages.","name":"_5_1","type":"manual","def":"5.1 – Functions and Types"},{"doc":"4.1 – The Stack\n\nLua uses a virtual stack to pass values to and from C. Each element in this stack represents a Lua value (nil, number, string, etc.). Functions in the API can access this stack through the Lua state parameter that they receive.\n\nWhenever Lua calls C, the called function gets a new stack, which is independent of previous stacks and of stacks of C functions that are still active. This stack initially contains any arguments to the C function and it is where the C function can store temporary Lua values and must push its results to be returned to the caller (see lua_CFunction).\n\nFor convenience, most query operations in the API do not follow a strict stack discipline. Instead, they can refer to any element in the stack by using an index: A positive index represents an absolute stack position, starting at 1 as the bottom of the stack; a negative index represents an offset relative to the top of the stack. More specifically, if the stack has n elements, then index 1 represents the first element (that is, the element that was pushed onto the stack first) and index n represents the last element; index -1 also represents the last element (that is, the element at the top) and index -n represents the first element.","name":"_4_1","type":"manual","def":"4.1 – The Stack"},{"doc":"3.1 – Lexical Conventions\n\nLua is a free-form language. It ignores spaces and comments between lexical elements (tokens), except as delimiters between two tokens. In source code, Lua recognizes as spaces the standard ASCII whitespace characters space, form feed, newline, carriage return, horizontal tab, and vertical tab.\n\nNames (also called identifiers) in Lua can be any string of Latin letters, Arabic-Indic digits, and underscores, not beginning with a digit and not being a reserved word. Identifiers are used to name variables, table fields, and labels.\n\nThe following keywords are reserved and cannot be used as na