Var dump

From Multi Theft Auto: Wiki
Jump to: navigation, search

This function outputs information about one or more variables using outputConsole().

Syntax

string/table var_dump( ... )

Arguments

The function can have a variable number of arguments. Those arguments can be of three types:

  • Modifiers: A string that begins with a "-" (minus) and that is followed by at least another parameter is a modifier. A modifier can change the behaviour of the function. Modifiers don't have to be the first argument, they always work on all arguments after it (see examples).
  • Names: A string that is followed by at least another parameter and isn't preceeded by another string (that is not a modifier), is a name. A name is output before the variable output, to make it recognizable (basicially a description of the variable that is being output, e.g. the name).
  • Values: Any value that is not one of the two above will generate an output with information about the variable:
    • For strings: string(lengthOfString) "value"
    • For userdata: userdata(MTA element type) "value"
    • For tables: table(numerOfElements) "value"
      • If the table contains any elements, they will also be output if the appropriate modifiers are set. This will always be in the form [key] => value, while key and value are formatted by var_dump.

Modifiers

  • v (verbose): Dumps more data than usual (for now it outputs whole tables including subtables)
  • n (normal): Switches back into 'normal' non-verbose mode.
  • s (silent): With this activated, it outputs nothing at all, however it still returns the output, so you can use it yourself (also used internally for recursion).
  • u (unnamed): Don't use names. Every string that is not a modifier will be output as a value, not a decription.
  • d[number] (depth): Output nested tables up to this depth (e.g. "d1" means output all values of the initial table, but not the values of the values, if they are also tables).


Returns

Returns a string with all the output in one line and a table with several lines of output.

Code

Click to collapse [-]
Server- and/or clientside Script
-- modifiers: v - verbose (all subtables), n - normal, s - silent (no output), dx - up to depth x, u - unnamed
function var_dump(...)
	-- default options
	local verbose = false
	local firstLevel = true
	local outputDirectly = true
	local noNames = false
	local indentation = "\t\t\t\t\t\t"
	local depth = nil

	local name = nil
	local output = {}
	for k,v in ipairs(arg) do
		-- check for modifiers
		if type(v) == "string" and k < #arg and v:sub(1,1) == "-" then
			local modifiers = v:sub(2)
			if modifiers:find("v") ~= nil then
				verbose = true
			end
			if modifiers:find("s") ~= nil then
				outputDirectly = false
			end
			if modifiers:find("n") ~= nil then
				verbose = false
			end
			if modifiers:find("u") ~= nil then
				noNames = true
			end
			local s,e = modifiers:find("d%d+")
			if s ~= nil then
				depth = tonumber(string.sub(modifiers,s+1,e))
			end
		-- set name if appropriate
		elseif type(v) == "string" and k < #arg and name == nil and not noNames then
			name = v
		else
			if name ~= nil then
				name = ""..name..": "
			else
				name = ""
			end

			local o = ""
			if type(v) == "string" then
				table.insert(output,name..type(v).."("..v:len()..") \""..v.."\"")
			elseif type(v) == "userdata" then
				local elementType = "no valid MTA element"
				if isElement(v) then
					elementType = getElementType(v)
				end
				table.insert(output,name..type(v).."("..elementType..") \""..tostring(v).."\"")
			elseif type(v) == "table" then
				local count = 0
				for key,value in pairs(v) do
					count = count + 1
				end
				table.insert(output,name..type(v).."("..count..") \""..tostring(v).."\"")
				if verbose and count > 0 and (depth == nil or depth > 0) then
					table.insert(output,"\t{")
					for key,value in pairs(v) do
						-- calls itself, so be careful when you change anything
						local newModifiers = "-s"
						if depth == nil then
							newModifiers = "-sv"
						elseif  depth > 1 then
							local newDepth = depth - 1
							newModifiers = "-svd"..newDepth
						end
						local keyString, keyTable = var_dump(newModifiers,key)
						local valueString, valueTable = var_dump(newModifiers,value)
						
						if #keyTable == 1 and #valueTable == 1 then
							table.insert(output,indentation.."["..keyString.."]\t=>\t"..valueString)
						elseif #keyTable == 1 then
							table.insert(output,indentation.."["..keyString.."]\t=>")
							for k,v in ipairs(valueTable) do
								table.insert(output,indentation..v)
							end
						elseif #valueTable == 1 then
							for k,v in ipairs(keyTable) do
								if k == 1 then
									table.insert(output,indentation.."["..v)
								elseif k == #keyTable then
									table.insert(output,indentation..v.."]")
								else
									table.insert(output,indentation..v)
								end
							end
							table.insert(output,indentation.."\t=>\t"..valueString)
						else
							for k,v in ipairs(keyTable) do
								if k == 1 then
									table.insert(output,indentation.."["..v)
								elseif k == #keyTable then
									table.insert(output,indentation..v.."]")
								else
									table.insert(output,indentation..v)
								end
							end
							for k,v in ipairs(valueTable) do
								if k == 1 then
									table.insert(output,indentation.." => "..v)
								else
									table.insert(output,indentation..v)
								end
							end
						end
					end
					table.insert(output,"\t}")
				end
			else
				table.insert(output,name..type(v).." \""..tostring(v).."\"")
			end
			name = nil
		end
	end
	local string = ""
	for k,v in ipairs(output) do
		if outputDirectly then
			outputConsole(v)
		end
		string = string..v
	end
	return string, output
end

Example

Click to collapse [-]
Serverside Example

Get a table of all players on the server (if there are 4 players).

var_dump(getElementsByType("player"))

Output:

table(4) "table: 02998058"

With 'verbose' modifier.

var_dump("-v",getElementsByType("player"))
table(1) "table: 043C6900"
 {
      [number "1"] => userdata(player) "userdata: 00000134"
 }

Now another table we created before (please note that the table 'test2' is both key and value in this example):

test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v",getElementsByType("player"),test)
table(1) "table: 020B7838"
 {
      [number "1"] => userdata(player) "userdata: 00000134"
 }
table(2) "table: 021770A0"
 {
      [string(5) "hello"] => string(4) "test"
      [table(2) "table: 02313070"
       {
            [number "1"] => string(4) "haha"
            [number "2"] => string(4) "naja"
       }]
       => table(2) "table: 02313070"
       {
            [number "1"] => string(4) "haha"
            [number "2"] => string(4) "naja"
       }
 }

The same as before, but now with a modifier to output the second table 'normal':

test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v",getElementsByType("player"),"-n",test)
table(1) "table: 01BB9030"
 {
      [number "1"] => userdata(player) "userdata: 00000134"
 }
table(2) "table: 0223B2D8"

The same as before, but now with a modifier to output the second table only to depth 1 (the verbose is still active from the first argument):

test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v",getElementsByType("player"),"-d1",test)
table(1) "table: 029BE6E8"
 {
      [number "1"] => userdata(player) "userdata: 00000134"
 }
table(2) "table: 01E2CDF8"
 {
      [string(5) "hello"] => string(4) "test"
      [table(2) "table: 021C6378"] => table(2) "table: 021C6378"
 }

The same as before, but now with names to make clear which output belongs to which variable (of course in this small example, it's not really needed):

test = {hello="test"}
test2 = {"haha","naja"}
test[test2] = test2
var_dump("-v","players",getElementsByType("player"),"-d1","test tables",test)
players: table(1) "table: 0219F4D0"
 {
      [number "1"] => userdata(player) "userdata: 00000134"
 }
test tables: table(2) "table: 0219DB20"
 {
      [string(5) "hello"] => string(4) "test"
      [table(2) "table: 01B68048"] => table(2) "table: 01B68048"
 }

The same as before, but now 'unnamed', meaning all values that are not modifiers will be output as values. However, the last two arguments were also removed, which leaves the last modifier as last argument, which will output the modifier as a normal value:

var_dump("-u","players",getElementsByType("player"),"-d1")
string(7) "players"
table(1) "table: 028B8A10"
string(3) "-d1"

See Also

ACL functions

  • aclGroupClone » This function clone a group to another group with/without ACLs and/or objects.
  • getPlayerAcls » This function returns a table of all ACL groups on a player.
  • isPlayerInACL » This function checks if a player element is in an ACL group.
  • renameAclGroup » This function gives an existing ACL group a new name.

Account functions

Camera functions

  • smoothMoveCamera » This function allows you to create a cinematic camera flight.

Cursor functions

  • getCursorMovedOn » This function checks in which way the cursor is currently moving.

Drawing functions

Effects functions

  • attachEffect » This function allows you attach an effect to an element.

Elements functions

  • getElementSpeed » This function returns the specified element's speed in m/s, km/h or mph.
  • getElementsInDimension » This function returns a table of elements that are in the specified dimension.
  • getElementsWithinMarker » This function returns a table of elements that are within a marker's collision shape.
  • isElementInPhotograph » This function checks if an element is in the player's camera picture area.
  • isElementInRange » This function allows you to check if an element's range to a main point is within the maximum range.
  • isElementMoving» This function checks if an element is moving.
  • isElementWithinAColShape» This function checks if an element is within a collision shape element.
  • multi_check » This function checks one element to many, handy and clean.
  • setElementSpeed » This function allows you to set the speed of an element in kph or mph units.

Events

  • onVehicleWeaponFire » This code implements an event that is triggered when a player in a vehicle fires a vehicle's weapon.

Input functions

  • bindControlKeys » This function allows you to bind each key bound to a control individually. Doing this bypasses a little MTA restriction.
  • getBoundControls » This function returns a table of control names that are bound to the specified key.
  • unbindControlKeys » This function allows you to unbind each key bound to a control individually. Use this function with bindControlKeys.
  • getClipboard » This event returns the contents of the clipboard by pressing ctrl + v / ctrl + V. Event triggered ONLY if cursor is showing.

Data functions

  • byte2human » This function converts an integer (number of bytes) into a human-readable unit.
  • capitalize » This function capitalizes a given string.
  • convertNumber » This function converts and formats large numbers.
  • convertServerTickToTimeStamp » This function converts server ticks to a unix timestamp.
  • convertTextToSpeech » This function converts the provided text to a speech in the provided language which players can hear.
  • findRotation » This function takes two points and returns the direction from point A to point B.
  • findRotation3D » This function takes two sets of XYZ coordinates. It returns the 3D direction from point A to point B.
  • FormatDate » This function formats a date on the basis of a format string and returns it.
  • generateString » This function generates a random string with any characters.
  • generateRandomASCIIString » This function returns a random string which uses ASCII characters.
  • getAge » This function calculates the age of a given birthday.
  • getDistanceBetweenPointAndSegment2D » This function takes point coordinates and line (a segment) starting and ending coordinates. It returns the shortest distance between the point and the line.
  • getEasterDate » This function returns easter date monthday and month for a given year.
  • getKeyFromValueInTable » This function returns the key of the specified value in a table.
  • getOffsetFromXYZ » This function allows you to take an entity and a position and calculate the relative offset between them accounting for rotations.
  • getPointFromDistanceRotation » This function finds a point based on a starting point, direction and distance.
  • getRealMonthH » This function convert english months to arabic months
  • getRealMonthM » This function gives you the real months name
  • getRGColorFromPercentage »This function returns two integers representing red and green colors according to the specified percentage.
  • getScreenRotationFromWorldPosition » This function returns a screen relative rotation to a world position.
  • getTimestamp » This function returns the UNIX timestamp of a specified date and time.
  • isLeapYear » This function returns a boolean representing if a given year is a leap year.
  • isValidMail » This function checks whether a provided e-mail string is valid.
  • removeHex » This function is used to remove hexadecimal numbers (colors, for example) from strings.
  • RGBToHex » This function returns a string representing the color in hexadecimal.
  • secondsToTimeDesc » This function converts a plain seconds-integer into a user-friendly time description.
  • string.count » This function counts the amount of occurences of a string in a string.
  • string.explode » This function splits a string at a given separator pattern and returns a table with the pieces.
  • switch » This function allows the value of a variable or expression to control the flow of program execution via a multiway branch.
  • toHex » This function converts a decimal number to a hexadecimal number, as a fix to be used client-side.
  • var dump » This function outputs information about one or more variables using outputConsole.
  • wavelengthToRGBA » This function converts a physical wavelength of light to a RGBA color.
  • getDistanceBetweenElements » Esta funcion sirve para obtener la distancia entre dos elementos.
  • isLowerOrUpper »This function checks whether the letter is large or small.

GUI functions

  • centerWindow » This function centers a CEGUI window element responsively in any resolution.
  • guiMoveElement » This function moves guiElement by/like using moveObject.
Comboboxes
Gridlists
Labels
  • guiLabelAddEffect » This function add a effects to the gui-label like (shadow, outline).

Marker functions

Math functions

  • mathNumber » This function is a workaround for the client-side floating-point precision of 24-bits.
  • math.hypot » This function returns the Hypotenuse of the triangle given by sides x and y.
  • math.percent » This function returns a percentage from two number values.
  • math.round » Rounds a number whereas the number of decimals to keep and the method may be set.
  • reMap » Re-maps a number from one range to another.
  • math.isPointInPolygon » Check if point is inside polygon or not.
  • math.polygonArea » Compute area of any polygon.

Ped functions

  • getAlivePlayers » This function returns a table of the alive players client-side.
  • getAlivePlayersInTeam » This function returns a table of the alive players in a team.
  • getGuestPlayers » This function gets a players not login or players Guest .
  • getOnlineAdmins » This function returns a table of all logged-in administrators.
  • getPedEyesPosition » This function allows you to get peds eyes position.
  • getPedMaxHealth » This function returns a pedestrians's maximum health by converting it from their maximum health stat.
  • getPedMaxOxygenLevel » This function returns a ped's maximum oxygen level by converting it from their maximum underwater stamina stat.
  • getPlayerFromNamePart » This function returns a player from partial name.
  • getPlayerFromSerial » This function returns a player from their serial.
  • getPlayersByData » This function returns a table of players that have the specified data name.
  • getPlayersInGroup » This function returns all Players In Group .
  • getPlayersInPhotograph » This function returns a table of all players in photograph.
  • isPedAiming» This function checks if a pedestrian is aiming their weapon.
  • isPedAimingNearPed » This is similar to isPedAiming but uses a colshape to be more precise.
  • isPedDrivingVehicle » This function checks if a specified pedestrian is driving a vehicle.
  • isPlayerInTeam » This function checks if a player is in a specified team.

Player functions

  • countPlayersInRange » This function returns the number of players that are within a certain range of the specified coordinates.

Resource functions

Sound functions

Browser functions

  • playVideo » This function plays a video on the screen.

Table functions

  • rangeToTable » This function converts a string range to a table containing number values.
  • setTableProtected » This function protects a table and makes it read-only.
  • Sort_Functions » These functions are able to sort your tables by a key.
  • table.compare » This function checks whether two given tables are equal.
  • table.copy » This function copies a whole table and all the tables in that table.
  • table.empty » This function checks whether a table is empty.
  • table.map » This function goes through a table and replaces every field with the return of the passed function, where the field's value is passed as first argument and optionally more arguments.
  • table.merge » This function merges two or more tables together.
  • table.random » This function retrieves a random value from a table.
  • table.removeValue » This function removes a specified value from a table.
  • table.size » This function returns the absolute size of a table.

Team functions

Vehicle funcions

Weapon functions

XML functions

  • getXMLNodes » This function returns all children of a XML node.

Utility

  • animate » This function allows you to use interpolateBetween without render event and easily used.
  • callClientFunction » This function allows you to call any client-side function from the server's side.
  • callServerFunction » This function allows you to call any server-side function from the client's side.
  • Check » This function checks if its arguments are of the right type and calls the error-function if one is not.
  • coroutine.resume » This function applies a fix for hidden coroutine error messages.
  • getBanFromName » This functions returns the ban of the given playername.
  • getCurrentFPS » This function returns the frames per second at which GTA: SA is running.
  • IfElse » This function returns one of two values based on a boolean expression.
  • isCursorOnElement » This function checks whether the cursor is in a particular area.
  • isMouseInCircle » This function checks if a cursor position is in circular area or not.
  • isMouseInPosition » This function allows you to check whether the mouse cursor/pointer is within a rectangular position.
  • iterElements » This function returns a time-saving iterator for your for-loops.
  • thisCommandHandlersExist » This method checks a string if this exist as command Handlers
  • vector3:compare » This method checks whether two vectors match, with optional precision.