Skip to content

Commit

Permalink
Add lua to bindings documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@mlschroe
mlschroe committed Mar 25, 2024
1 parent 0d6e498 commit 73eceaa
Show file tree
Hide file tree
Showing 4 changed files with 175 additions and 9 deletions.
126 changes: 122 additions & 4 deletions doc/gen/libsolv-bindings.3
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
.\" Title: Libsolv-Bindings
.\" Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 01/31/2023
.\" Date: 03/25/2024
.\" Manual: LIBSOLV
.\" Source: libsolv
.\" Language: English
.\"
.TH "LIBSOLV\-BINDINGS" "3" "01/31/2023" "libsolv" "LIBSOLV"
.TH "LIBSOLV\-BINDINGS" "3" "03/25/2024" "libsolv" "LIBSOLV"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
Expand Down Expand Up @@ -391,7 +391,9 @@ Stringification is done by calling the object\(cqs \(lqstr\(rq method\&.
.RE
.\}
.sp
There is one exception: you have to use \(lqstringify\(rq for Datamatch objects, as swig reports a clash with the \(lqstr\(rq attribute\&. Some objects also support a \(lq==\(rq method for equality tests, and a \(lq!=\(rq method\&.
There is one exception: you have to use \(lqstringify\(rq for Datamatch objects, as swig reports a clash with the \(lqstr\(rq attribute\&.
.sp
Some classes also support a \(lq==\(rq method for equality tests, and a \(lq!=\(rq method\&.
.sp
Swig implements all constants as numeric variables, constants belonging to a libsolv class are prefixed with the class name:
.sp
Expand All @@ -405,6 +407,122 @@ Swig implements all constants as numeric variables, constants belonging to a lib
.if n \{\
.RE
.\}
.sp
Iterators also work as expected:
.sp
.if n \{\
.RS 4
.\}
.nf
\fBfor\fR \fIsolvable\fR \fBin\fR \fIpool\fR\fB\&.solvables_iter() do \&.\&.\&.\fR
.fi
.if n \{\
.RE
.\}
.SH "LUA SPECIFICS"
.sp
Libsolv\(cqs lua bindings can be loaded with the following statement:
.sp
.if n \{\
.RS 4
.\}
.nf
\fBrequire("solv")\fR
.fi
.if n \{\
.RE
.\}
.sp
Objects are either created by calling the constructor method for a class or they are returned by calling methods on other objects\&.
.sp
.if n \{\
.RS 4
.\}
.nf
\fIpool\fR \fB= solv\&.Pool()\fR
\fIrepo\fR \fB=\fR \fIpool\fR\fB:add_repo("my_first_repo")\fR
.fi
.if n \{\
.RE
.\}
.sp
Note the \(lq:method\(rq syntax that makes lua add the object as first argument\&.
.sp
Attributes can be accessed as usual:
.sp
.if n \{\
.RS 4
.\}
.nf
\fIpool\fR\fB\&.appdata = 42\fR
\fBprint("appdata is "\&.\&.pool\&.appdata)\fR
.fi
.if n \{\
.RE
.\}
.sp
Iterators also work as expected:
.sp
.if n \{\
.RS 4
.\}
.nf
\fBfor\fR \fIsolvable\fR \fBin\fR \fIpool\fR\fB\&.solvables do \&.\&.\&.\fR
.fi
.if n \{\
.RE
.\}
.sp
Note that some functions return a table instead of an iterator, so you need to use \(lqipairs\(rq for iteration:
.sp
.if n \{\
.RS 4
.\}
.nf
\fBfor\fR \fI_\fR\fB,solvable\fR \fBin ipairs(\fR\fIjob\fR\fB\&.solvables()) do \&.\&.\&.\fR
.fi
.if n \{\
.RE
.\}
.sp
Arrays are passed and returned as tables:
.sp
.if n \{\
.RS 4
.\}
.nf
\fIjobs\fR \fB= {}\fR
\fIproblems\fR \fB=\fR \fIsolver\fR\fB\&.solve(\fR\fIjobs\fR\fB)\fR
\fBif #problems != 0 then \&.\&.\&.\fR
.fi
.if n \{\
.RE
.\}
.sp
The bindings define a \(lq__tostring\(rq method for many classes:
.sp
.if n \{\
.RS 4
.\}
.nf
\fBprint(\fR\fIdep\fR\fB)\fR
\fBprint(("Package: %\fR\fIs\fR\fB"):format(\fR\fIsolvable\fR\fB))\fR
.fi
.if n \{\
.RE
.\}
.sp
Constants live in the namespace of the class they belong to:
.sp
.if n \{\
.RS 4
.\}
.nf
\fIpool\fR\fB:set_flag(Solv\&.Pool\&.POOL_FLAG_OBSOLETEUSESCOLORS, 1)\fR;
.fi
.if n \{\
.RE
.\}
.SH "THE SOLV CLASS"
.sp
This is the main namespace of the library, you cannot create objects of this type but it contains some useful constants\&.
Expand Down Expand Up @@ -3609,7 +3727,7 @@ Update the matching installed packages to their best version\&. If none of the s
.PP
\fBSOLVER_WEAKENDEPS\fR
.RS 4
Allow breaking the dependencies of the matching packages\&. Handle with care\&.
Allow one to break the dependencies of the matching packages\&. Handle with care\&.
.RE
.PP
\fBSOLVER_MULTIVERSION\fR
Expand Down
4 changes: 2 additions & 2 deletions doc/gen/libsolv-pool.3
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
.\" Title: Libsolv-Pool
.\" Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 03/02/2022
.\" Date: 03/25/2024
.\" Manual: LIBSOLV
.\" Source: libsolv
.\" Language: English
.\"
.TH "LIBSOLV\-POOL" "3" "03/02/2022" "libsolv" "LIBSOLV"
.TH "LIBSOLV\-POOL" "3" "03/25/2024" "libsolv" "LIBSOLV"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
Expand Down
4 changes: 2 additions & 2 deletions doc/gen/testsolv.1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
.\" Title: testsolv
.\" Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 09/14/2018
.\" Date: 03/25/2024
.\" Manual: LIBSOLV
.\" Source: libsolv
.\" Language: English
.\"
.TH "TESTSOLV" "1" "09/14/2018" "libsolv" "LIBSOLV"
.TH "TESTSOLV" "1" "03/25/2024" "libsolv" "LIBSOLV"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
Expand Down
50 changes: 49 additions & 1 deletion doc/libsolv-bindings.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,8 @@ Stringification is done by calling the object's ``str'' method.
There is one exception: you have to use ``stringify'' for Datamatch
objects, as swig reports a clash with the ``str'' attribute.
Some objects also support a ``=='' method for equality tests, and a
Some classes also support a ``=='' method for equality tests, and a
``!='' method.
Swig implements all constants as numeric variables, constants belonging
Expand All @@ -186,6 +187,53 @@ to a libsolv class are prefixed with the class name:
TCL $pool set_flag $solv::Pool_POOL_FLAG_OBSOLETEUSESCOLORS 1
TCL puts [$solvable lookup_str $solv::SOLVABLE_SUMMARY]
Iterators also work as expected:
for solvable in pool.solvables_iter() do ...
Lua Specifics
-------------
Libsolv's lua bindings can be loaded with the following statement:

require("solv")

Objects are either created by calling the constructor method for a class or they
are returned by calling methods on other objects.

pool = solv.Pool()
repo = pool:add_repo("my_first_repo")

Note the ``:method'' syntax that makes lua add the object as first argument.

Attributes can be accessed as usual:

pool.appdata = 42
print("appdata is "..pool.appdata)

Iterators also work as expected:

for solvable in pool.solvables do ...

Note that some functions return a table instead of an iterator, so you
need to use ``ipairs'' for iteration:

for _,solvable in ipairs(job.solvables()) do ...

Arrays are passed and returned as tables:

jobs = {}
problems = solver.solve(jobs)
if #problems != 0 then ...

The bindings define a ``__tostring'' method for many classes:

print(dep)
print(("Package: %s"):format(solvable))

Constants live in the namespace of the class they belong to:

pool:set_flag(Solv.Pool.POOL_FLAG_OBSOLETEUSESCOLORS, 1);


The Solv Class
--------------
Expand Down

0 comments on commit 73eceaa

Please sign in to comment.