Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "LDT/Developer Area/Lua API Model 2"
< LDT
(→Sample) |
|||
| (10 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
=Lua API Model= | =Lua API Model= | ||
| − | The idea is to define a model of the external API of a Lua file | + | The idea is to define a model of the external API of a Lua file.<br/> |
| − | This model will be | + | This model will then be the main input of: |
| − | * | + | * documentation generator, |
* auto-completion engine, | * auto-completion engine, | ||
| − | * type checking | + | * type-checking. |
| + | |||
| + | The code relative to this model is based on lua and metalua, it is accessible [[LDT/MetaLua|here]]. | ||
| + | This model is build from [[LDT/User_Area/Documentation_Language|lua documentation language]] in code comments and later from lua code analysis. (see also : [[LDT/Developer_Area/Lua_Comment_Model|Lua Comment Model]]) | ||
====File==== | ====File==== | ||
| − | A Lua file | + | A Lua file declares some global variable and types. |
| − | A file | + | A file returns values (this is the values you get when you require this file) |
file | file | ||
| Line 19: | Line 22: | ||
====TypeDef==== | ====TypeDef==== | ||
| − | There are some primitive | + | There are some primitive types like string, number, boolean, any, nil, table, function.<br/> |
| − | TypeDef allow users to define | + | TypeDef allow users to define theirs own custom types.<br/> |
| − | There are 2 | + | There are 2 kinds of typedef. |
| − | typeDef= | + | typeDef = recordTypeDef | functionTypeDef |
| − | + | A recordTypeDef can be used to define a record (a tuple), a module or an object. (It may be a sub-type of table) | |
recordTypeDef | recordTypeDef | ||
| − | .string | + | .string name |
.string shortdescription | .string shortdescription | ||
.string description | .string description | ||
.map(fieldname,item) fields | .map(fieldname,item) fields | ||
| − | + | A functionTypeDef allows to define a function. Most of the time, the type and the item holding it are merged. | |
| − | + | It may be useful to name the type of function (for iterator perhaps) | |
| − | + | functionTypeDef | |
.string name | .string name | ||
.string shortdescription | .string shortdescription | ||
| Line 52: | Line 55: | ||
(.boolean hidden) | (.boolean hidden) | ||
| − | '''Remarks''': Hidden could be | + | '''Remarks''': Hidden could be use when there is a parameter we don't want to expose in the API<br/> |
| − | '''Remarks''': | + | '''Remarks''': hidden and optional does not need to be in the 1st version. |
====Item==== | ====Item==== | ||
| Line 65: | Line 68: | ||
====TypeRef==== | ====TypeRef==== | ||
| − | It's a reference to a type. There 3 | + | It's a reference to a type. There are 3 kinds of reference. |
typeref: externaltyperef | internaltyperef |primitivetyperef | typeref: externaltyperef | internaltyperef |primitivetyperef | ||
| Line 80: | Line 83: | ||
====Return values==== | ====Return values==== | ||
| − | + | A return value has references to a type defined in the Lua file. | |
| − | + | A return value is a list of possible values to return. | |
| − | e.g. if a function | + | e.g. if a function returns a number, or nil and err. |
| − | + | your function will have 2 return values : | |
| − | + | * <code>number</code> a result | |
| − | + | * <code>nil, err</code> if an error occured | |
return | return | ||
| Line 93: | Line 96: | ||
(.defaultuse) | (.defaultuse) | ||
| − | '''Remarks''': Perhaps we could have a defaultuse entry to define the return value the type | + | '''Remarks''': Perhaps we could have a defaultuse entry to define the return value the type checker should use. At the moment, the first entry in types list is used to type the return value. |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
Latest revision as of 12:35, 16 July 2014
Lua API Model
The idea is to define a model of the external API of a Lua file.
This model will then be the main input of:
- documentation generator,
- auto-completion engine,
- type-checking.
The code relative to this model is based on lua and metalua, it is accessible here. This model is build from lua documentation language in code comments and later from lua code analysis. (see also : Lua Comment Model)
File
A Lua file declares some global variable and types. A file returns values (this is the values you get when you require this file)
file .string shortdescription .string description .map(typename, typedef) types .map(varname,item) globalvars .list(returnvalues) returns
TypeDef
There are some primitive types like string, number, boolean, any, nil, table, function.
TypeDef allow users to define theirs own custom types.
There are 2 kinds of typedef.
typeDef = recordTypeDef | functionTypeDef
A recordTypeDef can be used to define a record (a tuple), a module or an object. (It may be a sub-type of table)
recordTypeDef .string name .string shortdescription .string description .map(fieldname,item) fields
A functionTypeDef allows to define a function. Most of the time, the type and the item holding it are merged. It may be useful to name the type of function (for iterator perhaps)
functionTypeDef .string name .string shortdescription .string description .list(parameter) params .list(returnvalues) returns
Parameter
parameter .string name .typeref type .string description (.boolean optional) (.boolean hidden)
Remarks: Hidden could be use when there is a parameter we don't want to expose in the API
Remarks: hidden and optional does not need to be in the 1st version.
Item
item .string name .string shortdescription .string description .typeref type
TypeRef
It's a reference to a type. There are 3 kinds of reference.
typeref: externaltyperef | internaltyperef |primitivetyperef externaltyperef .string modulename .string typename internaltyperef .string typename primitivetyperef .string typename
Return values
A return value has references to a type defined in the Lua file. A return value is a list of possible values to return.
e.g. if a function returns a number, or nil and err. your function will have 2 return values :
-
numbera result -
nil, errif an error occured
return .list(typeref) types .string description (.defaultuse)
Remarks: Perhaps we could have a defaultuse entry to define the return value the type checker should use. At the moment, the first entry in types list is used to type the return value.