80 lines
3.5 KiB
XML
80 lines
3.5 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<!DOCTYPE article [
|
|
<!ENTITY % medit-defines SYSTEM "medit-defines.ent">
|
|
%medit-defines;
|
|
]>
|
|
<chapter id="chapter-script-lua">
|
|
<?dbhtml filename="lua-moo.html"?>
|
|
<title>&medit; Lua API</title>
|
|
|
|
<sect1 id="section-script-lua-introduction">
|
|
<title>Introduction</title>
|
|
<para>Lua scripts running in &medit; have access to its
|
|
functionality through the <code>moo</code> package.</para>
|
|
<warning>
|
|
Functions which are not documented here may or may not work differently in
|
|
the future and they may disappear without notice. Contact the author if you
|
|
need functions which are not present here.
|
|
</warning>
|
|
</sect1>
|
|
|
|
<sect1 id="section-script-lua-object-model">
|
|
<title>&medit; object model</title>
|
|
<para>&medit; uses a very simple object model where its objects are
|
|
represented as user data in Lua and methods are provided via metatable
|
|
shared by all objects of all "classes". Method dispatch is dynamic,
|
|
i.e. metatable does not contain functions which correspond to methods,
|
|
and <code>obj:method</code> returns a function object which knows which
|
|
method on which object it is going to call.</para>
|
|
<para>This manual lists and talks about "classes", but it is merely
|
|
to avoid complicated terminology. When we say that an object belongs
|
|
to or is an instance of a class <code>Foo</code>, it just means that
|
|
it has methods listed in manual section for class <code>Foo</code>
|
|
and methods of parent classes, if any.</para>
|
|
<note>
|
|
To call a method, you can use both <code>obj:method(args)</code>
|
|
and <code>obj.method(args)</code>.
|
|
</note>
|
|
</sect1>
|
|
|
|
<sect1 id="section-script-lua-notations">
|
|
<title>Notations</title>
|
|
<para>This manual uses the following conventions:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Optional parameters</term>
|
|
<listitem>
|
|
<programlisting>func(arg1=val1, arg2=val, arg3=val3)</programlisting>
|
|
<code><parameter>arg</parameter>=val</code> means that
|
|
parameter <parameter>arg</parameter> is optional, and function receives
|
|
value <code>val</code> if it's missing. Not all parameters are necessarily
|
|
optional. For example, <programlisting>insert_text(text, where=nil)</programlisting>
|
|
means that <parameter>text</parameter> may not be missing or <constant>nil</constant>
|
|
(unless documentation says otherwise), and <parameter>where</parameter> is optional.
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Keyword parameters</term>
|
|
<listitem>
|
|
<programlisting>func{arg1, arg2, kwarg1=kwval1, kwarg2=kwval2}</programlisting>
|
|
This means that function can be called in an alternative way: actual parameters are
|
|
taken from the single table parameter, which must be a dictionary with keys
|
|
<parameter>kwarg1</parameter>, <parameter>kwarg2</parameter>, etc., and whose array part
|
|
must contain exactly as many values as there are non-optional arguments. Similarly
|
|
to regular parameters, <code><parameter>kwarg</parameter>=kwval</code> means that
|
|
<parameter>kwarg</parameter> is optional. For example, above function can be called
|
|
as follows.
|
|
<programlisting>
|
|
<!-- -->func{1, 2, kwarg1='foo'} -- equivalent to func(1, 2, 'foo')
|
|
<!-- -->func{3, 4, kwarg2='bar'} -- equivalent to func(3, 4, kwval1, 'bar')
|
|
<!-- -->func{5, 6, kwarg2='baz', kwarg1='bud', } -- equivalent to func(5, 6, 'bud', 'baz')</programlisting>
|
|
This is similar to Python keyword arguments (with the difference that keyword arguments
|
|
may be used only if function is documented to support them).
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</sect1>
|
|
###GENERATED###
|
|
</chapter>
|