summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/scripts/texdoc/search.tlu
blob: 1499c65414a0d7596bf1a8a0a71ced44c4e7a464 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
-- search.tlu: file searching functions for texdoc.
--
-- Manuel Pégourié-Gonnard, GPLv3, see texdoclib.tlu for details

-- Warning: every single function here assumes init_databases() has been called.

-- shared by all functions in this file
local s_doclist -- the Doclist objet to be populated by various functions
local s_meta -- {[normname] = meta, ...} (populated by init_tlp_database)
local vanilla -- is this a vanilla TL or a re-package one without tlpdb?

-----------------------   docfile and doclist objects   ------------------------

--[[
doclist = {
    [1] = docfile1, [2] = docfiles2, ...,
    inv = { realpath1 = index1, ... }
}

The inv subtable is such that for all i
doclist.inv(doclist[i].realpath:lower()) == i
Paths are lowercased in order to avoid duplicates on windows.
--]]

local Doclist = {}
Doclist.__index = Doclist

-- create a new list of docfiles
function Doclist:new()
    local dl = { inv = {} }
    setmetatable(dl, self)
    return dl
end

-- add a docfile to a list
function Doclist:add(df)
    if not df.realpath then return end -- useful if vanilla == false
    local index = self.inv[df.realpath:lower()]
    if index then
        self[index]:mergein(df)
    else
        local newindex = #self + 1
        self[newindex] = df
        self.inv[df.realpath:lower()] = newindex
    end
end

-- stops a doclist
function Doclist:stop()
    self.inv = nil
end

--[[
docfile = {
    -- name and tree are mendatory
    name      = filename (used for scoring only)
    tree      = code of the tree, see below
    -- at least one of the following fields should exist
    matches   = {pattern1, pattern2, ...} or {}
    runtodoc  = true if there is a runfile -> docfile association
    tlptodoc  = true if there is a tlp name -> docfile association
    -- those are virtual members, see below
    realpath  = full path
    normname  = nomrmalised (path removed up to the 'doc' component)
    shortname = short name used for scoring
    basename  = basename
    lang      = language tag from the catalogue metadata
    details   = details tag from the catalogue metadata
    quality   = 'good', 'bad', or 'killed' depending on score
    ext_pos   = position of the extension in ext_list
    -- set for elements of a list as a side effect of sort_doclist()
    score     = score
}
if tree > 1, this is the index of the tree in TEXDOCS
if tree = 0, then name is relative to TLROOT
tree = - 1 if and only if file is a sty file. Here name is absolute.
--]]

-- Docfile objects inherit members from Docfile
-- and have virtual members implemented by get_<member>() methods
-- for best cache performance, getters should not return nil
local Docfile = {}
function Docfile:__index(key)
    if Docfile[key] then return Docfile[key] end
    local getter = Docfile['get_'..key]
    if getter then
        rawset(self, key, getter(self))
        return rawget(self, key)
    end
end

-- create a new docfile objet using initilisation info
-- required fields: name, tree
function Docfile:new(info)
    local df = {}
    setmetatable(df, self)
    for k, v in pairs(info) do
        if k == 'pattern' then
            df.matches = { info.pattern }
        else
            df[k] = v
        end
    end
    return df
end

-- merge a second docfile objet in, assuming it represents the same file
function Docfile:mergein(df)
    for k, v in pairs(df) do
        if k == 'matches' then
            for _, m in ipairs(df.matches or {}) do
                table.insert(self.matches, m)
            end
        else
            self[k] = v
        end
    end
end

-- return the full path to the file
function Docfile:get_realpath()
    if self.tree > 0 then 
        return texdocs_tree_to_path(self.tree, self.name)
    elseif self.tree == 0 then
        if vanilla then
            return get_tlroot()..'/'..self.name
        else
            return kpse.find_file(self.normname, 'TeX system documentation')
        end
    else
        return self.name
    end
end

-- normalise a name from the tlpdb (use for s_meta indexes)
function reloc_tlpdb_path(name)
    return string.gsub(name, '^texmf[^/]*/doc/', '', 1)
end

-- return normalised name
function Docfile:get_normname()
    return (self.tree == 0) and reloc_tlpdb_path(self.name) or self.name
end

-- retrieve the lang from meta
function Docfile:get_lang()
    local meta = s_meta[self.normname]
    return meta and (meta.lang or false) or false
end

-- retrieve the details from meta
function Docfile:get_details()
    local meta = s_meta[self.normname]
    return meta and (meta.details or false) or false
end

-- return the short name used for scoring
function Docfile:get_shortname()
    if self.tree == -1 then return self.name end
    -- remove first component of name if at least two directory levels
    return string.match(self.normname, '^..-/(.+/.+)$') or self.normname
end

-- return the base name
function Docfile:get_basename()
    return string.gsub(self.name, '.*/', '', 1)
end

-- for interface consistency, matches should always be a table, never nil
function Docfile:get_matches()
    return {}
end

-- from score.tlu
Docfile.get_quality = docfile_quality

-- from score.tlu
function Docfile:get_ext_pos()
    return ext_pos(self.basename)
end

---------------------   manage TEXDOCS trees à la kpse   ----------------------

do -- scope of doc_roots
local doc_roots

--[[
doc_roots[i] = {
    path    = initial path,
    db      = { [file1] = basename1, [file2] = basename2, ... },
}
--]]

-- populate the doc_roots filename databases
function init_texdocs_database()
    doc_roots = {}
    local sep = (os.type == 'windows') and ';' or ':'
    local kpse_texdocs = kpse.expand_var("$TEXDOCS")
    -- expand the path and turn it into a lua list
    local raw_doc_roots = string.explode(kpse.expand_braces(kpse_texdocs), sep)
    local max = #raw_doc_roots + 1
    for j, dir in ipairs(raw_doc_roots) do
        local i = max - j
        local n
        local path, db
        -- get path, !! and // values
        dir, n = string.gsub (dir, '//$', '')
        local recursion_allowed = (n == 1)
        local path, n = string.gsub (dir, '^!!', '')
        local index_mandatory = (n == 1)
        deb_print('texdocs', string.format(
            'texdocs[%d] = %s (index_mandatory=%s, recursion_allowed=%s)',
            i, path, tostring(index_mandatory), tostring(recursion_allowed)))
        -- decide if we should use a ls-R index, the filesystem, or do nothing
        local root, shift = lsr_root(path)
        if root and shift and recursion_allowed then
            deb_print('texdocs', string.format(
                'texdocs[%d] using index: %s (shift=%s)', i, root, shift))
            db = init_lsr_db(root, shift)
        elseif not index_mandatory and lfs.isdir(path) then
            deb_print('texdocs', string.format(
                'texdocs[%d] using filesystem search', i))
            db = init_tree_db(path, recursion_allowed)
        end
        -- register this in docroots
        doc_roots[i] = { path = path, db = db }
    end
end

-- return the real path from a texdocs tree number + relative path
function texdocs_tree_to_path(tree, rel)
    return doc_roots[tree].path..'/'..rel
end

-- find docfiles in texdocs directories
function get_doclist_texdocs(patlist)
    for code, dr in ipairs(doc_roots) do
        if dr.db then scan_db(patlist, code, dr.db) end
    end
end

end -- scope of doc_roots

-- find a ls-R file in a parent directory and return it or nil
function lsr_root (path)
    if not lfs.isdir (path) then return end
    local root, shift = path, ''
    if string.sub(root, -1) == '/' then root = string.sub(root, 1, -2) end
    while string.find(root, '/', 1, true) do
        if lfs.isfile(root..'/ls-R') then
            return root, shift
        end
        local last_comp = string.match(root, '^.*/(.*)$')
        -- /!\ cannot put last_comp in a regex: can contain special char
        root = string.sub(root, 1, - (#last_comp + 2))
        shift = last_comp..'/'..shift
    end
end

-- build a db from a ls-R file
function init_lsr_db(root, shift)
    -- open the file
    local lsr = assert(io.open(root..'/ls-R', 'r'))
    local _ = lsr:read('*line') -- throw away first line (comment)
    -- scan it
    local db = {}
    local maybe_dir, isdoc = true, false
    local current_dir
    local l = #shift
    while true do
        local line = lsr:read('*line')
        while line == '' do line, maybe_dir = lsr:read('*line'), true end
        if line == nil then break end -- EOF
        local dir_line = maybe_dir and string.match(line, '^%./(.*):$')
        if dir_line then
            maybe_dir = false -- next line may not be a dir
            if string.sub(dir_line..'/', 1, l) == shift then
                isdoc = true
                current_dir = string.sub(dir_line, l+1)
                db[current_dir] = nil
            elseif isdoc then
                break -- we're exiting the ./doc (or shift) dir, so it's over
            end
        elseif isdoc then
            local file = (current_dir == '') and line or current_dir..'/'..line
            if check_ext(line) then db[file] = line end
        end
    end
    lsr:close()
    return db
end

-- build a db for a tree without ls-R index
function init_tree_db(base, recurse)
    local db = {}
    local function init_tree_db_rec(dir)
        for file in lfs.dir(base..'/'..dir) do
            if file ~= '.' and file ~= '..' then
                local f = (dir == '') and file or dir..'/'..file
                if lfs.isdir(base..'/'..f) then
                    if recurse then init_tree_db_rec(f) end
                else
                    if check_ext(file) then db[f] = file end
                end
            end
        end
    end
    init_tree_db_rec('')
    return db
end

--------------------   select results from TEXDOCS trees   ---------------------

-- scan a database
function scan_db(patlist, code, lsr_db)
    for file, basename in pairs(lsr_db) do
        local df = process_file(patlist, basename, file, code)
        if df then s_doclist:add(df) end
    end
end

-- says if file has a known extenstion according to ext_list
-- (or known basename according to basename_list)
function check_ext(file)
    file = string.lower(file)
    -- remove zipext if applicable
    file = parse_zip(file)
    -- then do the normal thing
    for _, e in ipairs(config.ext_list) do
        if e == '*' then
            return true
        elseif (e == '') then
            if not string.find(file, '.', 1, true) then
                return true
            end
        else
            local dot_e = '.'..e
            if string.sub(file, -string.len(dot_e)) == dot_e then
                return true
            end
        end
    end
    -- is the basename good?
    for _, b in ipairs(config.basename_list) do
        if file:find('^'..b..'$') or file:find('^'..b..'%.') then
            return true
        end
    end
    return false
end

-- say if a file (with its path) matches a pattern
function matches(pattern, file)
    if pattern.original then
        return string.find(file:lower(), pattern.name:lower(), 1, true)
    else
        return is_exact(file, pattern.name)
    end
end

-- return a docfile object if file "matches", nil ortherwise
function process_file(patlist, file, pathfile, code)
    local docfile
    local pattern
    for _, pattern in ipairs(patlist) do
        if matches(pattern, pathfile) then
            local info = {
                name    = pathfile,
                tree    = code,
                pattern = pattern,
            }
            if docfile then
                docfile:mergein(Docfile:new(info))
            else
                docfile = Docfile:new(info)
            end
        end
    end
    return docfile
end

----------------------------   look for sty files   ----------------------------

-- add doclist entries for sty files in patlist
function get_doclist_sty(patlist)
    for _, pat in ipairs(patlist) do
        local file = kpse.find_file(pat.name)
        if file then
            local df = Docfile:new({
                name    = file,
                tree    = -1,
                pattern = pat,
            })
            s_doclist:add(df)
        end
    end
end

--------------------------------   use tlpdb   ---------------------------------

-- tlpdb mean TeX Live Package DataBase and tlp means TeX Live Package

-- find the TeX Live root
function get_tlroot()
    local tlroot = kpse.var_value('SELFAUTOPARENT')
    get_tlroot = function() return tlroot end
    return tlroot
end

-- return true if cache exists and is newer than original, false otherwise
function good_cache(cache, ori)
    local cache_date = lfs.attributes(cache, 'modification')
    if not cache_date then return false end
    local ori_date = assert(lfs.attributes(ori, 'modification'))
    return cache_date > ori_date
end

-- make sure a given directory exists, or return nil plus an error string
function mkdir_p(dir)
    if lfs.isdir(dir) then return true end
    local parent = path_parent(dir)
    if parent then
        local ok, msg = mkdir_p(parent)
        if not ok then return nil, msg end
    end
    return lfs.mkdir(dir)
end

-- get tlpinfo tables initialised by whatever mean
function init_tlp_database()
    local TEXMFVAR = kpse.var_value('TEXMFVAR')
    local cache_file = TEXMFVAR..'/'..C.cache_name
    local texlive_tlpdb = get_tlroot()..'/tlpkg/texlive.tlpdb'
    vanilla = lfs.isfile(texlive_tlpdb)
    if vanilla then
        if good_cache(cache_file, texlive_tlpdb) then
            deb_print('tlpdb', 'Using cached data from '..cache_file)
            get_tlpinfo_from_cache(cache_file)
        else
            deb_print('tlpdb', 'Getting data from tlpdb file '..texlive_tlpdb)
            get_tlpinfo_from_tlpdb(texlive_tlpdb)
            deb_print('tlpdb', 'Writing data in cache file '..cache_file)
            local ok, msg = mkdir_p(path_parent(cache_file))
            if not ok then
                err_print('warning',
                'Failed to create cache file in '..cache_file..':')
                err_print('warning', msg)
            else
                print_out_tlpinfo(cache_file)
            end
        end
    else
        deb_print('tlpdb', 'Using shipped tlpdb data.')
        get_tlpinfo_from_dist()
    end
end

do -- begin scope of tlpinfo tables
local tlp_from_runfile -- { [runfile_basename] = {tlp1 = true, ...}, ... }
local tlp_doclist -- { [tlp_name] = { relname1, relname2, ...}, ... }

-- populate tlpinfo tables using the given texlive.tlpdb
function get_tlpinfo_from_tlpdb(filename)
    s_meta, tlp_from_runfile, tlp_doclist = {}, {}, {}
    local curr_tlp
    local state = 'none'
    for line in io.lines(filename) do
        if state == 'none' and string.find(line, '^name ') then
            -- begin a new package
            curr_tlp = string.lower(string.sub(line, 6, -1))
            tlp_doclist[curr_tlp] = {}
        elseif state == 'docfiles' then
            if not string.find(line, '^ ') then
                state = 'none'
            else
                local file = string.match(line, '^ ([^ ]*)')
                local meta = string.match(line, '^ [^ ]* (.+)')
                local basename = string.match(file, '([^/]*)$')
                if check_ext(basename) then
                    -- we've got a docfile here, add it
                    table.insert(tlp_doclist[curr_tlp], file)
                    if meta then
                        local details = string.match(meta, 'details="([^"]+)"')
                        local lang = string.match(meta, 'language="([^"]+)"')
                        s_meta[reloc_tlpdb_path(file)] = {
                            details = details,
                            lang = lang,
                        }
                    end
                end
            end
        elseif state == 'runfiles' then
            if not string.find(line, '^ ') then
                state = 'none'
            else
                -- check for interesting runfiles
                local e = string.sub(line, -4, -1)
                if e == '.tex' or e == '.sty' or e == '.cls' then
                    local f = string.match(line, '.*/(.*)%.')
                    tlp_from_runfile[f] = tlp_from_runfile[f] or {}
                    tlp_from_runfile[f][curr_tlp] = true
                end
            end
        end
        -- update state
        if string.find(line, '^docfiles ') then
            state = 'docfiles'
        elseif string.find(line, '^runfiles ') then
            state = 'runfiles'
        end
    end
    remove_useless_tlp()
end

-- remove entries for tlp without any docfile
function remove_useless_tlp()
    for tlp, doclist in pairs(tlp_doclist) do
        if #doclist == 0 then tlp_doclist[tlp] = nil end
    end
    for runfile, tlp_set in pairs(tlp_from_runfile) do
        for tlp in pairs(tlp_set) do
            if not tlp_doclist[tlp] then
                tlp_from_runfile[runfile][tlp] = nil
            end
        end
    end
end

-- print out data from tlpdb in dofile()-able form
function print_out_tlpinfo(filename)
    local fh = assert(io.open(filename, 'w'))
    local function printf(s, ...) fh:write(string.format(s, ...)) end
    -- s_meta
    printf('local s_meta = {\n')
    for k, v in pairs(s_meta) do
        printf('  [%q] = {', k)
        for i, j in pairs(v) do printf('[%q] = %q, ', i, j) end
        printf('},\n')
    end
    printf('}\n')
    -- tlp_from_runfile
    printf('local tlp_from_runfile = {\n')
    for k, v in pairs(tlp_from_runfile) do
        printf('  [%q] = {', k)
        for f in pairs(v) do printf('[%q]=true,', f) end
        printf('},\n')
    end
    printf('}\n')
    -- tlp_doclist
    printf('local tlp_doclist = {\n')
    for k, v in pairs(tlp_doclist) do
        printf('  [%q] = {\n', k)
        for _, f in ipairs(v) do printf('    %q,\n', f) end
        printf('  },\n')
    end
    printf('}\n')
    printf('return s_meta, tlp_from_runfile, tlp_doclist\n')
    fh:close()
end

-- get pre-hashed tlpdb info from a cache file
function get_tlpinfo_from_cache(filename)
    s_meta, tlp_from_runfile, tlp_doclist = dofile(filename)
end

-- get pre-hashed tlpdb info from a pseudo-cache file
function get_tlpinfo_from_dist()
    local f = assert(kpse.find_file(C.data_tlpdb_name, 'texmfscripts'))
    s_meta, tlp_from_runfile, tlp_doclist = dofile(f)
end

-- get docfiles for pattern using specific tlpdb information
function get_doclist_tlpdb(pattern)
    -- runfile to tlp to docfile
    if tlp_from_runfile[pattern] then
        for tlp in pairs(tlp_from_runfile[pattern]) do
            for _, file in ipairs(tlp_doclist[tlp]) do
                s_doclist:add(Docfile:new{
                    name        = file,
                    tree        = 0,
                    runtodoc    = true,
                })
            end
        end
    end
    -- tlp name to docfile
    if tlp_doclist[pattern] then
        for _, file in ipairs(tlp_doclist[pattern]) do
            s_doclist:add(Docfile:new{
                name            = file,
                tree            = 0,
                tlptodoc        = true,
            })
        end
    end
end

end --scope of tlpinfo table

------------------------------   main function   -------------------------------

-- initialise the various databases (must be called first)
function init_databases()
    init_texdocs_database()
    init_tlp_database()
end

-- find docfiles according to pattern
function get_doclist(pattern, no_alias)
    -- get patterns (inc. aliases)
    local normal, sty = normal_vs_sty(get_patterns(pattern, no_alias))
    -- initialise result list
    s_doclist = Doclist:new()
    -- get results
    get_doclist_sty(sty)
    get_doclist_texdocs(normal)
    get_doclist_tlpdb(pattern)
    -- finally, sort results
    sort_doclist(s_doclist, pattern)
    return s_doclist
end

-- separate sty patterns from the rest
function normal_vs_sty(list)
    local normal, sty = {}, {}
    for _, p in ipairs(list) do
        if string.match(string.lower(p.name), '%.([^/.]*)$') == 'sty' then
            table.insert(sty, p)
        else
            table.insert(normal, p)
        end
    end
    return normal, sty
end

return {
    init_databases = init_databases,
    get_doclist    = get_doclist,
}