tsmlquery(3) FreeBSD Library Functions Manual tsmlquery(3)
NAME
Munger module for TSML databases - queries structure and content.
DESCRIPTION
The tsmlquery.munger module provides 4 functions to discover the
structure and content of databases created by tsml2sqlite(1). The
tsmlquery.munger module is installed in (libdir).
The following is an example TSML document that is queried by example
code.
[News Feed[
[Source[
[Title[Source Title]]
[Link[Source Link]]
[Description[Source Description]]
]]
[Item[
[Title[Item 1]]
[Link[Link 1]]
[Description[Description 1]]
]]
[Item[
[Title[Item 2]]
[Link[Link 2]]
[Description[Description 2]]
]]
]News Feed]
(get_content db data (items))
returns a list of records from the database that represent the immediate
children of a specified element. The first argument is a SQLite database
object. The second argument is a boolean flag specifying if the function
should return the data fields.
The element to be queried is specified by the index field of its record
or by a series of pairs of element names and ordinal positions. If only
one argument follows the second argument, the third argument is
interpreted as the index of the element to be queried. If more than 1
argument follows the second argument, those arguments are interpreted as
path pairs. Each pair specifies one element in the path to the element
to be queried. The first item of each pair is a string naming an
element. The second item is a number that specifies a particular
instance of the named element in its parent. Instances are numbered from
1.
If the specified element does not exist in the database, the empty list
is returned. Otherwise, a list of sublists is returned. If the second
argument is true, sublists contain 3 strings: a child's index, its path,
and its data. If the second argument is false, the data elements are
omitted.
The following example queries a database created from the example TSML
document.
(load (join "/" (libdir) "tsmlquery.munger"))
(when (stringp (setq db (sqlite_open "tsml.db")))
(die db))
(foreach println (get_content db 0 "News Feed" 1))
The output from the program follows. Note that the data children of the
"News Feed" element are the whitespace between the second level elements.
The whitespace includes newlines. For visual clarity, we do not ask for
the data fields in the query.
("2" "\News Feed\")
("3" "\News Feed\Source")
("14" "\News Feed\")
("15" "\News Feed\Item")
("26" "\News Feed\")
("27" "\News Feed\Item")
("38" "\News Feed\")
(get_elements db tag (items))
returns a list of the records that represent elements named by a
specified tag that are direct children of a specified element. The first
argument is a SQLite database object. The second argument is the desired
tag. The arguments after the second argument are interpreted in the same
manner as the arguments after the second argument for get_content.
If get_elements does not find data to satisfy the query, the function
returns the empty list. Otherwise, get_data returns a list of lists.
Each sublist contains 2 strings. If the second argument names a tag, the
first string is the index for one element record with that tag name. If
the second argument is a false value, the first string is the index of
one element record regardless of its tag name. The second string is the
path of the element whose index is the first string.
The following example queries a database created from the example TSML
document.
(load (join "/" (libdir) "tsmlquery.munger"))
(when (stringp (setq db (sqlite_open "tsml.db")))
(die db))
(foreach println (get_elements db 0 "News Feed" 1))
(newline)
(foreach println (get_elements db "Item" "News Feed" 1))
The output from the program follows. The first invocation of
get_elements returns the records of all the elements that are direct
children of "News Feed". The second invocation returns the records of
the elements named "Item" that are direct children.
("3" "\News Feed\Source")
("15" "\News Feed\Item")
("27" "\News Feed\Item")
("15" "\News Feed\Item")
("27" "\News Feed\Item")
(get_data db data (items))
returns a list of all the document data from records that are immediate
children of a specified element. The first argument is a SQLite database
object. The second argument is a boolean flag. The arguments after the
second argument are interpreted in the same manner as the arguments after
the second argument for get_content.
If get_data cannot find data to satisfy the query, get_data returns the
empty list. Otherwise, get_data returns a list of lists. Each sublist
contains a string. If the second argument is true, the string is data
for one data record. If the second argument is false, the string is the
index of one data record.
The following example queries a database created from the example TSML
document.
(load (join "/" (libdir) "tsmlquery.munger"))
(when (stringp (setq db (sqlite_open "tsml.db")))
(die db))
(println (concat (get_data db 1 "News Feed" 1 "Source" 1 "Title" 1)))
(println (concat (get_data db 1 "News Feed" 1 "Source" 1 "Link" 1)))
(println (concat (get_data db 1 "News Feed" 1 "Source" 1 "Description" 1)))
(newline)
(for (((setq n 1) (setq item (get_data db 1 "News Feed" 1 "Item" n "Title" 1)))
(item)
((newline) (inc n) (setq item (get_data db 1 "News Feed" 1 "Item" n "Title" 1))))
(println (concat item))
(println (concat (get_data db 1 "News Feed" 1 "Item" n "Link" 1)))
(println (concat (get_data db 1 "News Feed" 1 "Item" n "Description" 1))))
The output from the program follows.
Source Title
Source Link
Source Description
Item 1
Link 1
Description 1
Item 2
Link 2
Description 2
(get_data_segment db index)
returns one segment of document data. The first argument is a SQLite
database object. The second argument is the value of the index field of
a database record. The second argument can be expressed as a number or a
string. The function returns the data of the specified record as a
string.
AUTHORS
James Bailie <jimmy@mammothcheese.ca>
http://www.mammothcheese.ca
Wed Dec 06, 2017