The love-api from love2d-community

modules/keyboard/enums/KeyConstant.lua is broken

The contents seem to be dumped into the description string.

https://github.com/love2d-community/love-api/blob/master/modules/keyboard/enums/KeyConstant.lua

Any interest in adding "skeleton" code to the README?

Sometimes I want to do something simple and small with love-api, and I had been wishing I could copy and paste some base code so I could change it to do I wanted instead of having to look at the table structure and write code to loop through everything.

So maybe it would be useful to add something like this to the README?

Here is what I have now: (not thoroughly tested!)

local api = require('love-api.love_api')

-- api.version

local function loopArgumentsOrReturns(arguments, argumentOrReturn, function_, variant, module_, moduleOrTypeOrCallback, prefix)
    for _, argument in ipairs(arguments or {}) do
        -- argument.type
        -- argument.name
        -- argument.description
        -- argument.default (optional)

        for _, flag in ipairs(argument.table or {}) do
            -- flag.type
            -- flag.name
            -- flag.description
            -- flag.default (optional)
        end
    end
end

local function loopFunctions(functions, module_, moduleOrTypeOrCallback, prefix)
    for _, function_ in ipairs(functions or {}) do
        -- function_.name
        -- function_.description

        for _, variant in ipairs(function_.variants) do
            loopArgumentsOrReturns(variant.arguments, 'argument', function_, variant, module_, moduleOrTypeOrCallback, prefix)
            loopArgumentsOrReturns(variant.returns, 'return', function_, variant, module_, moduleOrTypeOrCallback, prefix)
        end
    end
end

local function loopTypes(types, module_)
    for _, type_ in ipairs(types or {}) do
        -- type_.name
        -- type_.description
        -- type_.parenttype

        for _, constructor in ipairs(type_.constructors or {}) do
            -- constructor
        end

        for _, supertype in ipairs(type_.supertypes or {}) do
            -- supertype
        end

        for _, subtype in ipairs(type_.subtypes or {}) do
            -- subtype
        end

        loopFunctions(type_.functions, type_, 'type', type_.name..':')
    end
end

loopFunctions(api.functions, nil, 'module', 'love.')
loopFunctions(api.callbacks, nil, 'callback', 'love.')
loopTypes(api.types, nil)

for _, module_ in ipairs(api.modules) do
    -- module_.name
    -- module_.description

    loopFunctions(module_.functions, module_, 'module', 'love.'..module_.name..'.')
    loopTypes(module_.types, module_)

    for _, enum in ipairs(module_.enums or {}) do
        -- enum.name
        -- enum.description

        for _, constant in ipairs(enum.constants or {}) do
            -- constant.name
            -- constant.description
        end
    end
end

So if I wanted to, for example, print out the functions which return a single boolean and have one or more arguments, I can copy and paste the code above and just write this in the variant loop:

if variant.returns and #variant.returns == 1 and variant.returns[1].type == 'boolean' and variant.arguments then
    print(prefix..function_.name)
    break
end

Annotation issue newQuad

LuaLS/lua-language-server#1913 (comment)

As shown in the link it will give warnings.

Typo in getPixelDimensions method definition

Hello,

I noticed a typo in the getPixelDimensions method, it currently reads getPixelDimenions().

Relevant code snippet:

love-api/modules/graphics/Graphics.lua

Lines 1245 to 1264 in 232b836

 { 

 name = 'getPixelDimenions', 

 description = 'Gets the width and height in pixels of the window.\n\nlove.graphics.getDimensions gets the dimensions of the window in units scaled by the screen\'s DPI scale factor, rather than pixels. Use getDimensions for calculations related to drawing to the screen and using the graphics coordinate system (calculating the center of the screen, for example), and getPixelDimensions only when dealing specifically with underlying pixels (pixel-related calculations in a pixel Shader, for example).', 

 variants = { 

 { 

 returns = { 

 { 

 type = 'number', 

 name = 'pixelwidth', 

 description = 'The width of the window in pixels.', 

 }, 

 { 

 type = 'number', 

 name = 'pixelheight', 

 description = 'The height of the window in pixels.', 

 }, 

 }, 

 }, 

 }, 

 },

Reference: https://love2d.org/wiki/love.graphics.getPixelDimensions

Typo (of sorts)

(Probably missed by the script used for this commit)

Here:
functions -> variants

Add love.handlers

There is a table inside love called love.handlers that doesn't fit into the normal categories. It's not a module, function, or callback. It's just a table where you can define functions to handle user-defined events. It is documented here:

Missing type definitions: CanvasFormat, TextureFormat, MouseConstant

These guys are missing definitions:

CanvasFormat (used with love.graphics.newCanvas)
TextureFormat (used with love.graphics.newImage)
MouseConstant (used with love.mouse.isDown)

(Also love.graphics.newShader uses mat4 and vec4, but those aren't explicitly defined either...)

Move love.conf to callbacks

The love.conf is currently documented in love-api in the functions of the love module. However, this function is not provided by Löve2D, but is expected to be provided by the Löve2D users. Furthermore, the Löve2D wiki does not list it with the functions of the love module, but with the callbacks. So it should be documented in the callbacks of the love module.

Add test to make sure there is a variants table

For example love.window.restore caused some issues for love-atom, because the empty variants table was omitted.

        {
            name = 'restore',
            description = 'Restores the size and position of the window if it was minimized or maximized.',
            variants = {
                {}
            }
        },

@positive07 Maybe you have some time to take a look at this? :)

Wrong structure

love-api/modules/physics/types/Contact.lua

Lines 10 to 27 in 75e55c1

 { 

 name = 'getChildren', 

 description = 'Gets the child indices of the shapes of the two colliding fixtures. For ChainShapes, an index of 1 is the first edge in the chain.\nUsed together with Fixture:rayCast or ChainShape:getChildEdge.', 

 variants = { 

 returns = { 

 { 

 type = 'number', 

 name = 'indexA', 

 description = 'The child index of the first fixture\'s shape.' 

 }, 

 { 

 type = 'number', 

 name = 'indexB', 

 description = 'The child index of the second fixture\'s shape.' 

 } 

 } 

 } 

 },

Missed table between variants and returns

No Data/love.data module.

https://github.com/love2d-community/love-api/blob/0a4a337c4dd16e64201cc49c11ec3ca8e5f816bb/love_api.lua#L68L86

How to handle function variants

Some functions have multiple variants like love.graphics.push. These variants sometimes have their descriptions on the wiki. The question is how to handle these in the documentation.

My suggestion would be this:

{
    name = 'push',
    description = 'Copies and pushes the current coordinate transformation to the transformation stack.\n\nThis function is always used to prepare for a corresponding pop operation later. It stores the current coordinate transformation state into the transformation stack and keeps it active. Later changes to the transformation can be undone by using the pop operation, which returns the coordinate transform to the state it was in before calling push.',
    functions = {
        {
            description = 'Pushes the current transformation to the transformation stack.',
        },
        { 
            description = 'Pushes a specific type of state to the stack.',
            arguments = {
                {
                    type = 'StackType',
                    name = 'stack',
                    description = 'The type of stack to push (e.g. just transformation state, or all love.graphics state).'
                },
            }
        }
    }
},

Translations

I think it might be nice if love-api had translated descriptions.

Things I'm unsure of:

How can the translated text can be automatically retrieved from the wiki? Would the scraper from SublimeLove be a useful starting point?
What's the best way of putting the translations into the love-api table?

One option is to have a translations table next to every description:

{
    name = 'hasTextInput',
    description = 'Gets whether text input events are enabled.',
    translations = {
        de = 'Gibt zurück, ob Texteingaben-Ereignisse aktiviert sind.',
        ja = 'テキスト入力イベントが有効であるかどうか取得します。',
        ko = '텍스트 입력을 감지하고 있는지 확인합니다.'
    }
    variants = {
	{
	    returns = {
		{
		    type = 'boolean',
		    name = 'enabled',
		    description = 'Whether text input events are enabled.'
                    translatations = {
                        de = 'Ob Text-Ereignisse aktiviert sind, oder nicht.',
                        jp = 'テキスト入力イベントが有効であれば true を、無効であれば false を返します。',
                        ko = '텍스트 입력을 감지하고 있으면 true.'
                    }
		}
	    }
	}
    }
},

Would it be useful to automatically translate (using Google Translate or something) missing descriptions? Maybe it could have tag at the end or something letting love-api users know what's automatically translated and what's not, like de = Ob Texteingabeereignisse aktiviert sind. [auto]'`

@rm-code, since you're a wiki translator I'm sure you have a much better idea about all of this stuff than me! :)

Also I just noticed now how much better the documentation could be for languages other than English... The module pages (e.g. http://www.love2d.org/wiki/love.keyboard_(Deutsch) ) only list translated functions (surely it would be better if the English version was there if the translated version was unavailable?), and the module links on the left side bar only link to English pages.

So, this all seems like a lot of work and I don't think it will/should happen necessarily, but I just wanted to post this as a "pie in the sky" feature. :)

Links

As discussed in the forum thread, having local links pointing to other sections of the doc would be nice, also having external links wouldnt hurt either. I would love to work on this feature, just wanted to know what format should we use for the links.

I was thinking that maybe using

`local link`

to enclose the text would be nice for local links and something like markdown []() syntax for external links.

What do you say?

Also there should be a method to get the url for a link (parse the text?), and a method to completely unformat the text (delete the characters [](), ` and links in order to make it clearer)

Lua 5.4's `require` corrupts tables

As of Lua 5.4, require returns a second value.

Docs of require for Lua 5.3:

Once a loader is found, require calls the loader with two arguments: modname and an extra value dependent on how it got the loader. (If the loader came from a file, this extra value is the file name.) 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].

Docs of require for Lua 5.4 (emphasis mine)

Once 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.

If using Lua 5.4 or greater, this breaks many scripts that rely on each module being a valid table object. This is because many of the tables, e.g. types / enums, are just made by calling require on the constituent objects. For example an example of how this breaks things, see, vim-love-docs.

Enforce HTTPS Access

I don't have access to the Settings page of this repo so I can't change this.

Is love.font docs missing completly?

Is this on purpose? I think it's missing by mistake... Fix?

Detailed Type Information for Tables and Functions

This will be useful for type annotations that, for example, supports array tables, annotated function return type, etc.

Auto-building for github pages

We already have set up travis. It would be nice if we could use it to also update the quick reference each time a new commit is pushed.

https://github.com/love2d-community/splashes is using automated builds, but I didn't have the time to check it out properly yet.

0.10.0 Update

The update to 0.10.0 is now happening on the develop branch. It's hard to differentiate between changes which are made because of 0.10.0 or just concern 0.9.2. So I will treat all changes as changes towards 0.10.0.

Feel free to contribute based on the changelog.

Latest revision as of 03:15, 17 December 2015

Additions

Removals

Functions deprecated in 0.9.x

Removed love.graphics.getMaxImageSize and love.graphics.getMaxPointSize (replaced by love.graphics.getSystemLimits.)
Removed Mesh:setImage, Mesh:getImage, SpriteBatch:setImage, SpriteBatch:getImage, ParticleSystem:setImage, and ParticleSystem:getImage (replaced by set/getTexture.)
Removed SpriteBatch:bind and SpriteBatch:unbind.
Removed Canvas:getFSAA and the "fsaa" flag in love.conf and love.window.setMode (replaced by Canvas:getMSAA and the "msaa" flag.)
Removed the "dxt" and "bc5" GraphicsFeature constants (replaced by love.graphics.getCompressedImageFormats.)
Removed the "hdrcanvas" GraphicsFeature constant (replaced by love.graphics.getCanvasFormats.)
Removed love.window.getWidth, love.window.getHeight and love.window.getDimensions (use love.graphics.getWidth, love.graphics.getHeight, love.graphics.getDimensions or love.window.getMode instead.)

Renamed APIs

Renamed the fullscreen type "normal" to "exclusive".
Renamed the DistanceModel constants "inverse clamped", "linear clamped", and "exponent clamped" to "inverseclamped", "linearclamped", and "exponentclamped".
Renamed blend modes "additive", "subtractive", and "multiplicative" to "add", "subtract", and "multiply".
Renamed the key constant and Scancode representing the spacebar from " " to "space".
Renamed File:eof to File:isEOF.
Renamed Canvas:getImageData to Canvas:newImageData.
Renamed love.image's CompressedData type to CompressedImageData.

Other Missing Items

Summary
The following methods are undocumented both here and the LÖVE Wiki.
These will need to be added to the LÖVE Wiki before adding them here, as per the contributing guidelines.
However, the two filesystem methods, should they be documented? Or at they marked as internal-only?

love.filesystem

getExecutablePath
setFused

Video Object

Video:getPixelDimensions
Video:getPixelHeight
Video:getPixelWidth

Physics Objects

Embed CSS into HTML

While generally not considered best practice, I think sticking the CSS into a <style> tag would be good for this. It would allow people to download the whole API reference, styled, in a single file.

Also maybe bump the font size up a bit? it's pretty small~

Description of structure in README

Maybe it would help people make use of it faster if there is a description of the table structure in the README. Here's what I came up with:

return {
    version = '0.10.1',
    functions = { -- love.something functions, currently only love.getVersion
        -- See function structure below
    },
    modules = {
        {
            name = 'modulename',
            description = 'Description.',
            types = {
                -- See type structure below
            },
            functions = {
                -- See function structure below
            },
            enums = {
                {
                    name = 'EnumName',
                    description = 'Description.',
                    constants = {
                        {
                            name = 'constantname',
                            description = 'Description.'
                        }
                    }
                }
            }
        }
    },
    types = { -- Currently only supertypes
        -- See type structure below
    },
    callbacks = {
        -- See function structure below
    }
}

types = {
    {
        name = 'TypeName',
        description = 'Description.',
        constructors = { -- Optional
            'newTypeName'
        },
        functions = { -- Optional
            -- See function structure below
        },
        supertypes = { -- Optional
            'Supertype'
        },
        subtypes = { -- Optional
            'Subtype'
        }
    }
}

functions = { -- callbacks = {
    {
        name = 'functionName',
        description = 'Description.',
        variants = {
            {
                returns = { -- Optional
                    {
                        type = 'type',
                        name = 'name',
                        description = 'Description.',
                        table = { -- If type is table
                            {
                                type = 'string',
                                name = 'name',
                                description = 'Description.'
                            }
                        }
                    }
                },
                arguments = { -- Optional
                    {
                        type = 'type',
                        name = 'name',
                        default = 'default argument', -- Optional
                        description = 'Description.',
                        table = { -- If type is table
                            {
                                type = 'string',
                                name = 'name',
                                default = 'nil', -- Optional
                                description = 'Description.'
                            }
                        }
                    }
                }
            }
        }
    }
}

Extend specs

We should add a test to cover cases like this:
28195d5

Empty tables instead of nil for optional tables

Currently, one has to check if an optional table (i.e. functions, types, enums, returns, arguments, constructors, supertypes, subtypes) exists before looping though it, like this:

if variant.arguments then
	for _, argument in ipairs(variant.arguments) do
	end
end

I think it would be nicer to use if had an empty table instead of nil, so things could be looped through without checking if they exist first.

To avoid adding unnecessary stuff to the files, I suggest that the empty tables be added after the table is created, i.e.:

local api =  {
    -- etc.
}

local function functions(f)
    for _, function_ in ipairs(f) do
        for _, variant in ipairs(function_.variants) do
            if not variant.returns then variant.returns = {} end
            if not variant.arguments then variant.arguments = {} end
        end
    end
end

local function types(t)
    for _, type_ in ipairs(t) do
        if not type_.functions then type_.functions = {} end
        if not type_.constructors then type_.constructors = {} end
        if not type_.supertypes then type_.supertypes = {} end
        if not type_.subtypes then type_.subtypes = {} end

        functions(type_.functions)
    end
end

functions(api.functions)
functions(api.callbacks)
types(api.types)

for _, module_ in ipairs(api.modules) do
    if not module_.functions then module_.functions = {} end
    if not module_.types then module_.types = {} end
    if not module_.enums then module_.enums = {} end

    functions(module_.functions)
    types(module_.types)
end

return api

This change can break things if the script using it is checking to see if something exists for purposes other than looping, so sometimes if variant.arguments then has to become if #variant.arguments > 0 then.

I don't want to make this change now and unexpectedly break people's scripts, but I think it's a worthwhile change, so maybe scripts using the current love-api table could use the above code to test and see if it breaks their code (and enjoy simplifying their code because of the change!), and if it all works then love-api could be changed.

I've updated html-generator.lua to use this empty table format, I'll make a pull request for it.

Error in documentation of methods

The following methods documented in love-api do not exist in Löve2D:

Canvas:isActive
Font:hasGlyph (it should be "hasGlyphs" according to the Löve2D wiki)

Add license

In the löve discord, someone brought this issue up since they can't incorporate this into their project since they cannot provide a license for it.

Start Documenting 12.0 Functions

While it's unknown when 12.0 will arrive, 12.0 bring many changes by whole that once 12.0 is released it may took long time to get this love-api adapted to all the change.

I'd suggest doing these in forks. Not sure if I have permission to set up new branch in this repository though.

Adding love-api-to-ldt-luadoc to README

love-api-to-ldt-luadoc uses love-api and seems like it should go in the projects list.

Version discrepancy (is 11.3 or 11.2 the latest version supported?)

The table's latest version is displayed in the upper left corner as 11.2.

The badge in the README file in this repo says 11.3.

The table structure example in the README says 11.2

Is this table updated for 11.3 or not? Kinda hard to tell.

Missing Transform variant of love.graphics.draw

love.graphics.draw accepts Transform as 2nd (for Drawable) or 3rd (for Texture+Quad) argument since LOVE 11.0.

Font size is too small, page does not respond to zoom well

Title says it all. On my 27" 1440p monitor at 100% scaling in Windows, the page looks like this:

Text is hard to read so I try zooming to 200%:

You can see the sidebar gets cut off on the bottom.

Also not sure what's up with the first two items in the list but figured I'd screenshot it too~

If I were to make a suggestion, you could create a couple font size buttons for users to be able to select. Maybe Small: 10pt, Normal: 16pt, and Large: 20, 22, or 24pt?

Color ranges are obsolete

They show as 0-255

love.graphics.draw incorrect signature

The second argument of love.graphics.draw should be a quad.

`love.data` doesn't show up on http://love2d-community.github.io/love-api/

The love.data module doesn't show up on http://love2d-community.github.io/love-api/. This is all I see:

Other Libraries

LÖVE provides a whole set of libraries with it:

It would be nice to provide access to this libraries in the same format, Is this in the scope of this project? If this is fine, I can write a few of them (UTF and Network libs mostly, since I have used them many times)

Update css for quick reference

@hahawoo I thought about maybe changing / updating the css styling for the quick-reference. I like the colors of the https://love2d.org/ main page.

Better Specs

With busted and travis set up it makes sense to add some more fine-grained tests to this repo. This should include checking if values have the correct type, if arguments and return variables are formatted correctly etc.

Santos sent me this on the love forums, but I didn't have time to port it to busted yet:

local api = require( 'love_api' )

local function check(t, ok, info)
    for ok_i, ok_v in ipairs(ok) do
        if (ok_v.optional and t[ok_v.name] ~= nil) or (not ok_v.optional) then
            if not (type(t[ok_v.name]) == ok_v.type) then
            print()
            print('Trying to find: '..info.. ' > '..ok_v.name)
            if type(t) == 'table' then
               print()
               print('Table contains:')
               for k, v in pairs(t) do
                  print(k, v)
               end
               print()
            else
               error('Is not table')
            end
            print('Found: '..tostring(t[ok_v.name]))
            print('Should be type: '..ok_v.type)
            print('Is type: '..type(t[ok_v.name]))
            print('Optional: '..tostring(ok_v.optional))
            error('')
         end
        end
    end

    for k, v in pairs(t) do
        local contains = false
        for ok_i, ok_v in ipairs(ok) do
            if k == ok_v.name then
                contains = true
            end
        end
      if not (contains == true) then
         print('Found extra key: '..info..' > '..k)
      end
    end
end

local function check_functions(functions, info)
    if not functions then
        return
    end

    for _, f in ipairs(functions) do
        check(f, {
            {name = 'name', type = 'string'},
            {name = 'description', type = 'string'},
            {name = 'variants', type = 'table'},
        }, info)

        for _, variant in ipairs(f.variants) do
            check(variant, {
                {name = 'returns', type = 'table', optional = true},
                {name = 'arguments', type = 'table', optional = true},
                {name = 'description', type = 'string', optional = true},
            }, info .. ' > variants')

            local function check_returns_or_arguments(a, info)
                if a then
                    for _, r in pairs(a) do
                        check(r, {
                            {name = 'type', type = 'string'},
                            {name = 'name', type = 'string'},
                            {name = 'default', type = 'string', optional = true},
                            {name = 'description', type = 'string'},
                            {name = 'table', type = 'table', optional = true},
                        }, info)

                        if r.table then
                            for _, v in pairs(r.table) do
                                check(v, {
                                    {name = 'type', type = 'string'},
                                    {name = 'name', type = 'string'},
                                    {name = 'default', type = 'string', optional = true},
                                    {name = 'description', type = 'string'},
                                }, info .. ' > table')
                            end
                        end
                    end
                end
            end

            check_returns_or_arguments(variant.returns, info .. ' > '..f.name..' > variants > returns')
            check_returns_or_arguments(variant.arguments, info .. ' > '..f.name..' > variants > returns')
        end
    end
end


local function check_types(types, info)
    if not types then
        return
    end

    for _, t in ipairs(types) do
      check(t, {
         {name = 'name', type = 'string'},
         {name = 'description', type = 'string'},
         {name = 'functions', type = 'table', optional = true},
         {name = 'supertypes', type = 'table', optional = true},
         {name = 'constructors', type = 'table', optional = true},
      }, info)

        check_functions(t.functions, info ..' > '..t.name..' > functions')
    end
end

local function check_enums(enums, info)
    if not enums then
        return
    end

    for _, enum in ipairs(enums) do
        check(enum, {
            {name = 'name', type = 'string'},
            {name = 'description', type = 'string', optional = true},
            {name = 'constants', type = 'table'},
        }, info)

        for _, constant in ipairs(enum.constants) do
            check(constant, {
                {name = 'name', type = 'string'},
                {name = 'description', type = 'string'},
            {name = 'notes', type = 'string', optional = true},
            }, info..' > '..enum.name..' > constants')
        end
    end
end

check(api, {
    {name = 'functions', type = 'table'},
    {name = 'modules', type = 'table'},
    {name = 'types', type = 'table'},
    {name = 'callbacks', type = 'table'},
    {name = 'config', type = 'table'},
}, 'love')

check_functions(api.functions, 'love > functions')
check_functions(api.callbacks, 'love > callbacks')
check_types(api.types, 'love > types')

for _, m in ipairs(api.modules) do
    check(m, {
        {name = 'name', type = 'string'},
        {name = 'description', type = 'string'},
        {name = 'types', type = 'table', optional = true},
        {name = 'functions', type = 'table', optional = true},
        {name = 'enums', type = 'table', optional = true},
    }, 'love > modules')

    check_functions(m.functions, 'love > modules > '..m.name..' > functions')
    check_types(m.types, 'love > modules > '..m.name..' > types')
    check_enums(m.enums, 'love > modules > '..m.name..' > enums')
end

Quick references for older versions

Each release could have its own reference, for people using older versions.

For example: http://love2d-community.github.io/love-api/0.9.2/

http://love2d-community.github.io/love-api/ could still be for the latest version.

module name

Hello,

I suggest to use uniq module names, something like require "api.love".
It should help to defined other API like the lua one (in api.lua).

See https://github.com/tst2005/love-api/tree/modnames

Regards,

Quick reference: love.conf doesn't show window/modules tables

love.graphics is undefined

I use the Lua extention by sumneko for VS Code. Config:

{
  "Lua.runtime.version": "LuaJIT",
  "Lua.diagnostics.globals": ["love", "lldebugger"],
  "Lua.workspace.library": ["${3rd}/love2d/library"],
  "Lua.workspace.checkThirdParty": false
}

But I get errors / warnings that graphics does not exist on love. But e.g. love.audio works. What's wrong?

.vscode\extensions\sumneko.lua-2.6.0\server\meta\3rd\love2d\library\love.lua

---@meta

-- version: 11.3
---@class love
love = {}

Merging modules back into love-api

In a personal conversation Santos brought up some good points for having the documentation as a single file.

Would love to hear what other people think, because for my own project (which uses the api) it doesn't matter at all.

Wiki scraping

I've finally made a wiki scraper, which means (ideally) we don't have to manually edit the table anymore.

It's not perfect, for example it doesn't scrape modules for their names and descriptions.

Removing variants which are redundant due to default arguments in other variants

For example, love.physics.newMotorJoint currently has two variants:

love.physics.newMotorJoint(body1, body2, correctionFactor [default: 0.3])
love.physics.newMotorJoint(body1, body2, correctionFactor [default: 0.3], collideConnected [default: false])

when really it has one variant, because the "collideConnected" argument has a default.

The functions I found which might be in this category are:

love.filesystem.mount (appendToPath default is false)
love.graphics.arc (ArcType default is "pie")
love.graphics.circle (segments has a default)
love.graphics.ellipse (segments has a default)
love.graphics.newFont (size default is 12)
love.graphics.newImage (has default flags)
love.graphics.newImageFont (extraspacing default is 0)
love.graphics.rectangle (rx default is 0)
love.graphics.setBlendMode (BlendAlphaMode default is "alphamultiply")
love.keyboard.isDown (extra keys are optional)
love.math.random (min default is 1)
love.physics.newMotorJoint (collideConnected is false)
love.physics.newPrismaticJoint (reference angle is 0)
love.physics.newWeldJoint (reference angle is 0)
love.window.setFullscreen (fstype is "desktop" or last used)
Joystick:setVibration (duration is -1)

This can be corrected in the wiki as well, however sometimes it might not always be appropriate to remove the variant from the wiki because the wiki retains information about all LOVE versions and the variants may have been added in different versions. If there are any instances of this I think love-api should differ from the wiki and remove them anyway because love-api only contains information for the version which it targets.

There is also another concept which the wiki doesn't currently use which is that an argument can be left out, i.e. be "none". I'm not suggesting we do anything about this necessarily, I just thought it was interesting:

love.image.newImageData (data can be none)
love.graphics.newMesh (vertexformat can be none)
love.joystick.saveGamepadMappings (file can be none)

If anyone is interested, here is a script which prints out functions which have more than one variant that I used to find the functions above:

api = require('love-api.love_api')

function printFunctions(functions, parent)
  for _, function_ in ipairs(functions) do
    if function_.variants and #function_.variants > 1 then
      for _, variant in ipairs(function_.variants) do
        local output = ''
        for returnIndex, return_ in ipairs(variant.returns or {}) do
          output = output..return_.name
          if returnIndex ~= #variant.returns then
            output = output..','
          end
          output = output..' '
        end
        if variant.returns then
          output = output..'= '
        end
        output = output..parent..function_.name..'('
        for argumentIndex, argument in ipairs(variant.arguments or {}) do
          output = output..argument.name
          if argument.default then
            output = output..' ['..argument.default..']'
          end
          if argumentIndex ~= #variant.arguments then
            output = output..', '
          end
        end
        output = output..')'
        print(output)
      end
    end
  end
end

printFunctions(api.functions, 'love.')

for _, module_ in ipairs(api.modules) do
  printFunctions(module_.functions, 'love.'..module_.name..'.')
  for _, type_ in ipairs(module_.types or {}) do
    if type_.functions then
      printFunctions(type_.functions, type_.name..':')
    end
  end
end

And the output is:

source = love.audio.newSource(filename, type ["stream"])
source = love.audio.newSource(file, type ["stream"])
source = love.audio.newSource(decoder, type ["stream"])
source = love.audio.newSource(soundData)
source = love.audio.newSource(fileData)
love.audio.pause()
love.audio.pause(source)
love.audio.resume()
love.audio.resume(source)
love.audio.rewind()
love.audio.rewind(source)
love.audio.stop()
love.audio.stop(source)
love.event.quit()
love.event.quit(exitstatus [0])
love.event.quit("restart")
success = love.filesystem.mount(archive, mountpoint)
success = love.filesystem.mount(archive, mountpoint, appendToPath [false])
data = love.filesystem.newFileData(contents, name, decoder ["file"])
data, err = love.filesystem.newFileData(filepath)
success, message = love.filesystem.write(name, data, size [all])
success, message = love.filesystem.write(name, data, size [all])
love.graphics.arc(drawmode, x, y, radius, angle1, angle2, segments [10])
love.graphics.arc(drawmode, arctype, x, y, radius, angle1, angle2, segments [10])
love.graphics.circle(mode, x, y, radius)
love.graphics.circle(mode, x, y, radius, segments)
love.graphics.clear()
love.graphics.clear(r, g, b, a [255])
love.graphics.clear(color, ...)
love.graphics.discard(discardcolor [true], discardstencil [true])
love.graphics.discard(discardcolors, discardstencil [true])
love.graphics.draw(drawable, x [0], y [0], r [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
love.graphics.draw(texture, quad, x [0], y [0], r [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
love.graphics.ellipse(mode, x, y, radiusx, radiusy)
love.graphics.ellipse(mode, x, y, radiusx, radiusy, segments)
love.graphics.intersectScissor(x, y, width, height)
love.graphics.intersectScissor()
love.graphics.line(x1, y1, x2, y2, ...)
love.graphics.line(points)
font = love.graphics.newFont(filename)
font = love.graphics.newFont(filename, size)
font = love.graphics.newFont(filename, imagefilename)
font = love.graphics.newFont(size)
mesh = love.graphics.newMesh(vertices, mode ["fan"], usage ["dynamic"])
mesh = love.graphics.newMesh(vertexcount, mode ["fan"], usage ["dynamic"])
mesh = love.graphics.newMesh(vertexformat, vertices, mode ["fan"], usage ["dynamic"])
mesh = love.graphics.newMesh(vertexformat, vertexcount, mode ["fan"], usage ["dynamic"])
image = love.graphics.newImage(filename)
image = love.graphics.newImage(imageData)
image = love.graphics.newImage(compressedImageData)
image = love.graphics.newImage(filename, flags)
font = love.graphics.newImageFont(filename, glyphs)
font = love.graphics.newImageFont(imageData, glyphs)
font = love.graphics.newImageFont(filename, glyphs, extraspacing [0])
shader = love.graphics.newShader(code)
shader = love.graphics.newShader(pixelcode, vertexcode)
video = love.graphics.newVideo(filename, loadaudio [nil])
video = love.graphics.newVideo(videostream, loadaudio [nil])
love.graphics.points(x, y, ...)
love.graphics.points(points)
love.graphics.points(points)
love.graphics.polygon(mode, ...)
love.graphics.polygon(mode, vertices)
love.graphics.print(text, x, y, r [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
love.graphics.print(coloredtext, x, y, angle [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
love.graphics.printf(text, x, y, limit, align ["left"], r [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
love.graphics.printf(coloredtext, x, y, wraplimit, align, angle [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
love.graphics.rectangle(mode, x, y, width, height)
love.graphics.rectangle(mode, x, y, width, height, rx, ry [rx], segments [nil])
love.graphics.setBackgroundColor(r, g, b, a [255])
love.graphics.setBackgroundColor(rgba)
love.graphics.setBlendMode(mode)
love.graphics.setBlendMode(mode, alphamode ["alphamultiply"])
love.graphics.setCanvas(canvas, ...)
love.graphics.setCanvas()
love.graphics.setCanvas(canvas1, canvas2, ...)
love.graphics.setColor(red, green, blue, alpha)
love.graphics.setColor(rgba)
love.graphics.setColorMask(red, green, blue, alpha)
love.graphics.setColorMask()
font = love.graphics.setNewFont(filename, size [12])
font = love.graphics.setNewFont(file, size [12])
font = love.graphics.setNewFont(data, size [12])
love.graphics.setShader()
love.graphics.setShader(shader)
love.graphics.setScissor(x, y, width, height)
love.graphics.setScissor()
love.graphics.setStencilTest(comparemode, comparevalue)
love.graphics.setStencilTest()
data = Canvas:newImageData()
data = Canvas:newImageData(x, y, width, height)
hasglyph = Font:hasGlyphs(character)
hasglyph = Font:hasGlyphs(codepoint)
attributecomponent, ... = Mesh:getVertex(index)
x, y, u, v, r, g, b, a = Mesh:getVertex(index)
Mesh:setDrawRange(min, max)
Mesh:setDrawRange()
Mesh:setTexture()
Mesh:setTexture(texture)
Mesh:setVertex(index, attributecomponent, ...)
Mesh:setVertex(index, vertex)
Mesh:setVertex(index, x, y, u, v, r [255], g [255], b [255], a [255])
Mesh:setVertex(index, vertex)
Mesh:setVertexMap(map)
Mesh:setVertexMap(vi1, vi2, vi3)
Mesh:setVertices(vertices)
Mesh:setVertices(vertices)
data = Image:getData()
data = Image:getData()
Image:refresh()
Image:refresh(x, y, width, height)
Image:setMipmapFilter(filtermode, sharpness [0])
Image:setMipmapFilter()
ParticleSystem:setQuads(quad1, quad2)
ParticleSystem:setQuads(quads)
Shader:send(name, number, ...)
Shader:send(name, vector, ...)
Shader:send(name, matrix, ...)
Shader:send(name, texture)
Shader:send(name, boolean, ...)
id = SpriteBatch:add(x, y, r [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
id = SpriteBatch:add(quad, x, y, r [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
SpriteBatch:set(id, x, y, r [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
SpriteBatch:set(id, quad, x, y, r [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
SpriteBatch:setColor(r, g, b, a [255])
SpriteBatch:setColor()
index = Text:add(textstring, x, y, angle [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
index = Text:add(coloredtext, x, y, angle [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
index = Text:addf(textstring, wraplimit, align, x, y, angle [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
index = Text:addf(coloredtext, wraplimit, align, x, y, angle [0], sx [1], sy [sx], ox [0], oy [0], kx [0], ky [0])
width, height = Text:getDimensions()
width, height = Text:getDimensions(index)
height = Text:getHeight()
height = Text:getHeight(index)
width = Text:getWidth()
width = Text:getWidth(index)
Text:set(textstring)
Text:set(coloredtext)
Text:set()
Text:setf(textstring, wraplimit, align ["left"])
Text:setf(coloredtext, wraplimit, align ["left"])
Text:setf()
compressed = love.image.isCompressed(filename)
compressed = love.image.isCompressed(fileData)
compressedImageData = love.image.newCompressedData(filename)
compressedImageData = love.image.newCompressedData(fileData)
imageData = love.image.newImageData(width, height)
imageData = love.image.newImageData(width, height, data)
imageData = love.image.newImageData(filename)
imageData = love.image.newImageData(filedata)
width, height = CompressedImageData:getDimensions()
width, height = CompressedImageData:getDimensions(level)
height = CompressedImageData:getHeight()
height = CompressedImageData:getHeight(level)
width = CompressedImageData:getWidth()
width = CompressedImageData:getWidth(level)
love.joystick.loadGamepadMappings(filename)
love.joystick.loadGamepadMappings(mappings)
mappings = love.joystick.saveGamepadMappings(filename)
mappings = love.joystick.saveGamepadMappings()
success = love.joystick.setGamepadMapping(guid, button, inputtype, inputindex, hatdirection)
success = love.joystick.setGamepadMapping(guid, axis, inputtype, inputindex, hatdirection)
inputtype, inputindex, hatdirection = Joystick:getGamepadMapping(axis)
inputtype, inputindex, hatdirection = Joystick:getGamepadMapping(button)
success = Joystick:setVibration(left, right)
success = Joystick:setVibration()
success = Joystick:setVibration(left, right, duration)
down = love.keyboard.isDown(key)
anyDown = love.keyboard.isDown(key, ...)
love.keyboard.setTextInput(enable)
love.keyboard.setTextInput(enable, x, y, w, h)
compressedData = love.math.compress(rawstring, format ["lz4"], level [-1])
compressedData = love.math.compress(data, format ["lz4"], level [-1])
rawstring = love.math.decompress(compressedData)
rawstring = love.math.decompress(compressedString, format)
rawstring = love.math.decompress(data, format)
lr, lg, lb = love.math.gammaToLinear(r, g, b)
lr, lg, lb = love.math.gammaToLinear(color)
lc = love.math.gammaToLinear(c)
convex = love.math.isConvex(vertices)
convex = love.math.isConvex(x1, y1, x2, y2, x3, y3, ...)
cr, cg, cb = love.math.linearToGamma(lr, lg, lb)
cr, cg, cb = love.math.linearToGamma(color)
c = love.math.linearToGamma(lc)
curve = love.math.newBezierCurve(vertices)
curve = love.math.newBezierCurve(x1, y1, x2, y2, x3, y3, ...)
rng = love.math.newRandomGenerator()
rng = love.math.newRandomGenerator(seed)
rng = love.math.newRandomGenerator(low, high)
value = love.math.noise(x)
value = love.math.noise(x, y)
value = love.math.noise(x, y, z)
value = love.math.noise(x, y, z, w)
number = love.math.random()
number = love.math.random(max)
number = love.math.random(min, max)
love.math.setRandomSeed(seed)
love.math.setRandomSeed(low, high)
triangles = love.math.triangulate(polygon)
triangles = love.math.triangulate(x1, y1, x2, y2, x3, y3, ...)
number = RandomGenerator:random()
number = RandomGenerator:random(max)
number = RandomGenerator:random(min, max)
RandomGenerator:setSeed(seed)
RandomGenerator:setSeed(low, high [0])
cursor = love.mouse.newCursor(imageData, hotx [0], hoty [0])
cursor = love.mouse.newCursor(filepath, hotx [0], hoty [0])
cursor = love.mouse.newCursor(fileData, hotx [0], hoty [0])
love.mouse.setCursor()
love.mouse.setCursor(cursor)
shape = love.physics.newChainShape(loop, x1, y1, x2, y2, ...)
shape = love.physics.newChainShape(loop, points)
shape = love.physics.newCircleShape(radius)
shape = love.physics.newCircleShape(x, y, radius)
joint = love.physics.newMotorJoint(body1, body2, correctionFactor [0.3])
joint = love.physics.newMotorJoint(body1, body2, correctionFactor [0.3], collideConnected [false])
shape = love.physics.newPolygonShape(x1, y1, x2, y2, ...)
shape = love.physics.newPolygonShape(vertices)
joint = love.physics.newPrismaticJoint(body1, body2, x, y, ax, ay, collideConnected [false])
joint = love.physics.newPrismaticJoint(body1, body2, x1, y1, x2, y2, ax, ay, collideConnected [false])
joint = love.physics.newPrismaticJoint(body1, body2, x1, y1, x2, y2, ax, ay, collideConnected [false], referenceAngle [0])
shape = love.physics.newRectangleShape(width, height)
shape = love.physics.newRectangleShape(x, y, width, height, angle [0])
joint = love.physics.newRevoluteJoint(body1, body2, x, y, collideConnected [false])
joint = love.physics.newRevoluteJoint(body1, body2, x1, y1, x2, y2, collideConnected [false], referenceAngle [0])
joint = love.physics.newWeldJoint(body1, body2, x, y, collideConnected [false])
joint = love.physics.newWeldJoint(body1, body2, x1, y1, x2, y2, collideConnected [false])
joint = love.physics.newWeldJoint(body1, body2, x1, y1, x2, y2, collideConnected [false], referenceAngle [0])
Body:applyForce(fx, fy)
Body:applyForce(fx, fy, x, y)
Body:applyLinearImpulse(ix, iy)
Body:applyLinearImpulse(ix, iy, x, y)
decoder = love.sound.newDecoder(file, buffer [2048])
decoder = love.sound.newDecoder(filename, buffer [2048])
soundData = love.sound.newSoundData(filename)
soundData = love.sound.newSoundData(file)
soundData = love.sound.newSoundData(data)
soundData = love.sound.newSoundData(samples, rate [44100], bits [16], channels [2])
thread = love.thread.newThread(filename)
thread = love.thread.newThread(fileData)
thread = love.thread.newThread(codestring)
Thread:start()
Thread:start(arg1, arg2, ...)
videostream = love.video.newVideoStream(filename)
videostream = love.video.newVideoStream(file)
value = love.window.fromPixels(pixelvalue)
x, y = love.window.fromPixels(px, py)
success = love.window.setFullscreen(fullscreen)
success = love.window.setFullscreen(fullscreen, fstype)
success = love.window.showMessageBox(title, message, type ["info"], attachtowindow [true])
pressedbutton = love.window.showMessageBox(title, message, buttonlist, type ["info"], attachtowindow [true])
pixelvalue = love.window.toPixels(value)
px, py = love.window.toPixels(x, y)

Making the reference work well offline

I think it would be good if the API reference worked well offline. There are two issues I can see:

1: The page uses an image. If the page is saved from a browser, the image will be saved with the HTML file in a folder. I think it would be better if there was just a single HTML page to download, and the image was embedded. My data-url-embedder could help with this.

2: If the page is saved from Chrome using "Save as..." the links on the page will link to the URLs on GitHub making them unusable, i.e. the link to "#callbacks" becomes "https://love2d-community.github.io/love-api/#callbacks". If the page is saved from right clicking on a link to it, or by finding the HTML file on GitHub, then the links are fine, but the menu is unusable because the image is missing. I can think of two solutions to this:

1: Have a download link on the page to itself, and embed the image.

2: Change the links using JavaScript by putting this code at end of the body:

<script>
var a = document.getElementsByTagName('a');
for (var i = 0; i < a.length; i++) {
    a[i].href = a[i].href.replace("https://love2d-community.github.io/love-api/", "");
}
</script>

Missing argument 'presses' on love.mousepressed callback

The 'presses' argument is missing on the love.mousepressed callback. It is available since LÖVE 11.0.

Some ideas

I've had a few ideas about this project, and I thought I'd put them all in one issue instead of creating heaps of issues, all of which maybe no one else would think are good ideas. :P I'm sorry there's so much text here, feel free to not read it anyone.

Some of these ideas involve diverging from the wiki a bit, and the idea of this project currently is to stick to what is in the wiki, and I respect that so I might make my own "experimental" fork (and move out the code I've been temporarily storing in the "test" folder of the gh-pages branch), but I thought I'd share my ideas here anyway just in case any of them are useful.

Here are the ideas:

Have a "serializer" for the table, so the table can be changed in Lua code and then resaved into the same file structure. This could be useful for adding/changing fields or table structure. I've kind of already made this here, using LOVE so that creating directories is easy (maybe it's also easy in plain Lua too, I didn't try).
Have extra commas at the end of tables (i.e. "},"), it might look a bit weird but it could make copy and pasting and removing code in the table easier, and plus I think it makes the serializer code a little bit simpler.
Maybe it would be cool to have support for images (or maybe not). If there were images, there should also be a way to get the description without images, for text-only uses.
Also support for example code, maybe? (I actually don't think example code or images are necessarily appropriate for this API reference, because I think it would be more suitable for a different type of documentation; like how the function descriptions in the Lua reference manual don't have many code examples. But, maybe.)
Putting the "love" module in its own module folder like the other modules may or may not be useful.
When I first made the table my idea was to put the wiki information in a table in the simplest way possible, but what I should have done also is to provide easy ways of using it. I thought of adding some base code to the README for this purpose (#51), but now I think it would be more useful to post-process the table to make it easier to use so that code isn't necessary (the full table structure I have in mind and post-processing code can be found here):
- Tables for functions, types, arguments etc. could have a "what" field with what that table is, i.e. 'function', 'type', etc.
- There could be a list of all the tables with a "what" field, and other lists which contain just the functions, just the types, etc.
- Each table could have references to its "context", i.e. a method could have references to its type, the module it's in, etc.
- There could be other fields which would be useful, like a full name for a function (i.e. the name 'draw' and the full name 'love.graphics.draw'), the corresponding getter/setter of a function, and whatever else would be useful. There are things I haven't added yet which may or may not be useful, like a synopsis for variants and unique string IDs for each table.
This is an extremely minor and silly quibble, but I'm not sure about the repo name and the table name differing only by the hyphen/underscore, because it leads to it being required like 'love-api.love_api', which is so close to the same name twice, I think I tripped up on this one time using two underscores or something and got confused, so I would be inclined to want it to be either the same name twice.

These are the "diverging from the wiki" ideas:

Removing the "notes" field from KeyConstant enum. The "notes" field isn't used anywhere else, and the information can be merged in to the "description" field.
Global/object state can have an initial value, which isn't documented in the wiki, for example the initial color state is (255, 255, 255, 255). It might be useful to document this.
It might also be useful to document ways in the which the function can error or fail without error (i.e. the filesystem functions).
The wiki has mini description for functions which are used on the module/type pages, which I think could be useful especially for languages other than English where the function name by itself isn't self-explanatory. I wrote some code which grabbed this information from the wiki, but then I realized that it's basically a copy of the first line of the full description. So, perhaps "the first line of the description should work as the mini description" could be a thing.
Checking the consistency of the documentation. For example, the description of getters often start with both "Returns the" and "Gets the", and names of argument/returns sometimes use camelCase and sometimes use lowercase.
Removing references in descriptions to previous versions, i.e. 'In version 0.9.2 and older...'. I don't think this is useful information to keep around, because if one is using a previous version they can use a previous release of the LOVE-API table.
Combining variants which differ only by argument type (see this thread).

0.11.0 Update

Started a branch at https://github.com/love2d-community/love-api/tree/update_to_love0110

TODO:

Remove keyreleased variant

All callbacks should have a single variant, since all arguments will always be provided, it's the decision of the user to ignore them or not. This is the case for ALL callbacks but keyreleased.

This callback provides both a variant with a second argument which is the Scancode and a variant without.

My proposal is to remove the variant that has no Scancode which can be found in lines 775 to 783

	{
	name = 'getPixelDimenions',
	description = 'Gets the width and height in pixels of the window.\n\nlove.graphics.getDimensions gets the dimensions of the window in units scaled by the screen\'s DPI scale factor, rather than pixels. Use getDimensions for calculations related to drawing to the screen and using the graphics coordinate system (calculating the center of the screen, for example), and getPixelDimensions only when dealing specifically with underlying pixels (pixel-related calculations in a pixel Shader, for example).',
	variants = {
	{
	returns = {
	{
	type = 'number',
	name = 'pixelwidth',
	description = 'The width of the window in pixels.',
	},
	{
	type = 'number',
	name = 'pixelheight',
	description = 'The height of the window in pixels.',
	},
	},
	},
	},
	},

	{
	name = 'getChildren',
	description = 'Gets the child indices of the shapes of the two colliding fixtures. For ChainShapes, an index of 1 is the first edge in the chain.\nUsed together with Fixture:rayCast or ChainShape:getChildEdge.',
	variants = {
	returns = {
	{
	type = 'number',
	name = 'indexA',
	description = 'The child index of the first fixture\'s shape.'
	},
	{
	type = 'number',
	name = 'indexB',
	description = 'The child index of the second fixture\'s shape.'
	}
	}
	}
	},

love2d-community / love-api Goto Github PK

love-api's People

Contributors

Stargazers

Watchers

Forkers

love-api's Issues

Additions

Removals

Functions deprecated in 0.9.x

Renamed APIs

Recommend Projects

Recommend Topics

Recommend Org