summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/scripts/barracuda/lib-barcode/brcd-barcode.lua
blob: 1208adeb752e7bba639ab6f3c051470fcc1d3f58 (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
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
-- Barcode Abstract Class
-- Copyright (C) 2019-2022 Roberto Giacomelli
-- Please see LICENSE.TXT for any legal information about present software

local Barcode = {_classname = "Barcode"}
Barcode.__index = Barcode

-- barcode_type/submodule name
Barcode._available_enc = {-- keys must be lowercase
    code39  = "lib-barcode.brcd-code39",  -- Code 39
    code128 = "lib-barcode.brcd-code128", -- Code128
    ean     = "lib-barcode.brcd-ean",     -- EAN family (ISBN, EAN8, etc)
    i2of5   = "lib-barcode.brcd-i2of5",   -- Interleaved 2 of 5
    upc     = "lib-barcode.brcd-upc",     -- UPC
}
Barcode._builder_instances = {} -- encoder builder instances repository
Barcode._encoder_instances = {} -- encoder instances repository

-- common parameters to all the barcode objects
Barcode._super_par_order = {
    "ax",
    "ay",
    "debug_bbox",
}
Barcode._super_par_def = {}
local pardef = Barcode._super_par_def
-- set an Anchor point (ax, ay) relatively to the barcode bounding box
-- without considering any text object
-- ax = 0, ay = 0 is the lower left corner of the symbol
-- ax = 1, ay = 1 is the upper right corner of the symbol
Barcode.ax = 0.0
pardef.ax = {
    default = 0.0,
    unit = "sp", -- scaled point
    isReserved = false,
    fncheck = function (_self, ax, _) --> boolean, err
        if ax >= 0.0 and ax <= 1.0 then return true, nil end
        return false, "[OutOfRange] 'ax' out of [0, 1] interval"
    end,
}
Barcode.ay = 0.0
pardef.ay = {
    default = 0.0,
    unit = "sp", -- scaled point
    isReserved = false,
    fncheck = function (_self, ay, _) --> boolean, err
        if ay >= 0.0 and ay <= 1.0 then return true, nil end
        return false, "[OutOfRange] 'ay' out of [0, 1] interval"
    end,
}

-- debug only purpose
-- enable/disable bounding box drawing of symbols
Barcode.debug_bbox = "none"
pardef.debug_bbox = {
    default    = "none",
    isReserved = false,
    enum = {
        none = true, -- do nothing
        symb = true, -- draw bbox of the symbol
        qz = true, -- draw a bbox at quietzone border
        qzsymb = true, -- draw quietzone and symbol bboxes
    },
    fncheck    = function (self, e, _) --> boolean, err
        if type(e) ~= "string" then return false, "[TypeError] not a string" end
        local keys = self.enum
        if keys[e] == true then
            return true, nil
        else
            return false, "[Err] enumeration value '"..e.."' not found"
        end
    end,
}

-- Barcode methods

-- extract id from an encoder 'tree name'
local function parse_treename(treename) --> fam, var, name, err
    if not type(treename) == "string" then
        return nil, nil, nil, "[ArgErr] 'treename' arg must be a string"
    end
    if treename:find(" ") then
        return nil, nil, nil,
            "[ArgErr] spaces are not allowed in an encoder identifier"
    end
    local fam, var, name
    -- family name extraction
    local idash = treename:find("-")
    local icolon = treename:find(":")
    if idash then
        fam = treename:sub(1, idash - 1)
    else
        if icolon then
            fam = treename:sub(1, icolon - 1)
        else
            fam = treename
        end
    end
    if fam == "" then
        return nil, nil, nil, "[ArgErr] empty encoder id"
    end
    if idash then
        if icolon then
            var = treename:sub(idash + 1, icolon - 1)
        else
            var = treename:sub(idash + 1)
        end
        if var == "" then
            return nil, nil, nil, "[ArgErr] empty 'variant' encoder id"
        end
    end
    if icolon then
        name = treename:sub(icolon + 1)
        if name == "" then
            return nil, nil, nil, "[ArgErr] empty 'name' after colon"
        end
        if name:find("-") then
            return nil, nil, nil, "[ArgErr] the name mustn't contain a dash"
        end
        if name:find(":") then
            return nil, nil, nil, "[ArgErr] the name mustn't contain a colon"
        end
    end
    return fam, var, name, nil
end

-- main iterator on parameter definitions
-- optional argument 'filter' eventually excludes some parameters
-- "*all" -> encoder and Barcode parameters
-- "*enc" -> only encoder parameters
-- "*super" -> only Barcode superclass paramenters
function Barcode:param_ord_iter(filter)
    local is_iter_enc, is_iter_super = true, true
    if filter then
        if type(filter) ~= "string" then
            error("[param_ord_iter] 'filter' is not a string")
        elseif filter == "*enc" then
            is_iter_super = false
        elseif filter == "*super" then
            is_iter_enc = false
        elseif filter ~= "*all" then
            error("[param_ord_iter] 'filter' enumeration '"..filter.."' not found")
        end
    end
    local state = {}
    local ordkey = {}
    if is_iter_enc then
        local var = self._variant
        local p2_family  = self._par_def -- base family parameters
        local p2_family_var
        if var then
            local pvar = "_par_def_"..var
            p2_family_var = self[pvar] -- variant specific family parameters
        end
        local p2_idlist = self._par_order
        if p2_idlist then -- family parameters
            for i, pid in ipairs(p2_idlist) do
                if ordkey[pid] then
                    error("[Ops] duplicated entry in parameter ordered list")
                end
                ordkey[pid] = true
                local pdef -- parameter definition
                if var and p2_family_var then
                    pdef = p2_family_var[pid]
                end
                pdef = pdef or p2_family[pid]
                assert(pdef, "[Ops] parameter definition for option '"..pid.."' not found")
                state[i] = {
                    pname   = pid,
                    pdef    = pdef,
                    isSuper = false,
                }
            end
        end
        -- append variant parameters
        if var and self._par_def_variant then
            local p2_variant = self._par_def_variant[var]
            if p2_variant then
                local p2_idlist_var = self._par_variant_order[var] -- parameters' list
                if p2_idlist_var then
                    for _, pid in ipairs(p2_idlist_var) do
                        if ordkey[pid] then
                            error("[Ops] duplicated entry in variant parameter ordered list")
                        end
                        ordkey[pid] = true
                        local pdef = p2_variant[pid] -- parameter definition
                        assert(pdef, "[Ops] parameter definition for option '"..pid.."' not found")
                        state[#state + 1] = {
                            pname   = pid,
                            pdef    = pdef,
                            isSuper = false,
                        }
                    end
                end
            end
        end
    end
    if is_iter_super then
        -- append the super class parameter to the iterator state
        local p1_idlist_super = self._super_par_order
        local p1_super = self._super_par_def
        for _, pid in ipairs(p1_idlist_super) do
            if ordkey[pid] then
                error("[Ops] duplicated entry in superclass parameter ordered list")
            end
            ordkey[pid] = true
            local pdef = p1_super[pid] -- parameter definition
            assert(pdef, "[Ops] parameter definition for option '"..pid.."' not found")
            state[#state + 1] = {
                pname   = pid,
                pdef    = pdef,
                isSuper = true,
            }
        end
    end
    -- stateless iterator troughtout the ordered parameters collection
    local p_iter = function (st, i)
        i = i + 1
        local t = st[i]
        if t then
            return i, t
        end
    end
    return p_iter, state, 0
end

-- encoder costructor
-- Symbology can be a family with many variants. This is represented by the
-- first argument 'tree_name' formatted as <family>-<variant>:<id>.
-- i.e. when 'tree_name' is the string "ean-13", "ean" is the barcode family and
-- "13" is its variant name.
-- For whose barcodes that do not have variants, 'treename' is simply the
-- encoder id such as in the case of "code128".
-- <id> is an optional identifier useful if there are more than one encoders of
-- the same type
-- 'opt' is an optional table with the user-defined parameters setting up
-- encoders
function Barcode:new_encoder(treename, opt) --> object, err
    -- argument checking
    local family, variant, enc_name, err = parse_treename(treename)
    if err then
        return nil, err
    end
    local av_enc = self._available_enc
    local mod_path = av_enc[family]
    -- check family identifier
    if not mod_path then
        return nil, "[ArgErr] barcode family '"..family.."' not found"
    end
    -- retrive/load the builder
    local builder
    local tenc = self._builder_instances
    if tenc[family] then -- is the encoder builder already loaded?
        builder = tenc[family]
    else -- load the encoder builder
        builder = require(mod_path)
        tenc[family] = builder
    end
    -- check the variant identifier
    local av_var = builder._id_variant
    if av_var and variant and (not av_var[variant]) then
        local fmt = "[ArgErr] family '%s' does not have '%s' variant"
        return nil, string.format(fmt, family, variant)
    end
    -- check unique encoder identifier
    local enc_archive = self._encoder_instances
    if enc_archive[treename] then
        return nil, "[Err] encoder name '"..treename.."' already exists"
    end
    if type(opt) == "table" or opt == nil then
        opt = opt or {}
    else
        return nil, "[ArgErr] provided 'opt' is not a table"
    end
    local enc = {_classname = "Encoder"} -- the new encoder
    enc.__index = enc
    enc._variant = variant
    setmetatable(enc, {
        __index = function(_, k)
            if builder[k] ~= nil then
                return builder[k]
            end
            return self[k]
        end
    })
    enc_archive[treename] = enc
    -- parameters definition
    for _, tpar in enc:param_ord_iter() do
        local pname   = tpar.pname
        local pdef    = tpar.pdef
        local isSuper = tpar.isSuper
        local val = opt[pname] -- param = val
        if val ~= nil then
            local ok, perr = pdef:fncheck(val, enc)
            if ok then
                enc[pname] = val
            else -- parameter error!
                return nil, perr
            end
        else
            -- load the default value of <pname>
            local def_val; if pdef.fndefault then
                def_val = pdef:fndefault(enc)
            else
                def_val = pdef.default
            end
            if not isSuper then
                enc[pname] = def_val
            end
        end
    end
    if enc._config then -- this must be called after the parameter definition
        local ok, e = enc:_config()
        if not ok then return nil, e end
    end
    return enc, nil
end

-- retrive an encoder object already created
-- 'treename' is the special identifier of the encoder
function Barcode:enc_by_name(treename) --> <encoder object>, <err>
    -- argument checking
    local _family, _variant, _enc_name, err = parse_treename(treename)
    if err then
        return nil, err
    end
    local enc = self._encoder_instances[treename]
    if enc then
        return enc, nil
    else
        return nil, "[Err] encoder '"..treename.."' not found"
    end
end

-- base methods common to all the encoders

-- for numeric only simbology
-- elem_code : encoded char
-- elem_text : human readable char
-- err : error description
function Barcode:_check_char(c, parse_state) --> elem_code, elem_text, err
    if type(c) ~= "string" or #c ~= 1 then
        return nil, nil, "[InternalErr] invalid char"
    end
    local process_char = self._process_char
    if process_char then
        return process_char(self, c, parse_state)
    end
    local n = string.byte(c) - 48
    if n < 0 or n > 9 then
        return nil, nil, "[ArgErr] found a not digit char"
    end
    return n, nil, nil
end
--
function Barcode:_check_digit(n, parse_state) --> elem_code, elem_text, err
    if type(n) ~= "number" then
        return nil, nil, "[ArgErr: n] not a number"
    end
    local process_digit = self._process_digit
    if process_digit then
        return process_digit(self, n, parse_state)
    end
    if n < 0 or n > 9 then
        return nil, nil, "[ArgErr: n] not a digit"
    end
    return n, nil, nil
end

-- not empty string --> Barcode object
function Barcode:from_string(symb, opt) --> object, err
    if type(symb) ~= "string" then
        return nil, "[ArgErr] 'symb' is not a string"
    end
    if #symb == 0 then
        return nil, "[ArgErr] 'symb' is an empty string"
    end
    local chars_code = {}
    local chars_text
    local parse_state
    if self._init_parse_state then
        parse_state = self:_init_parse_state()
    else
        parse_state = {}
    end
    for c in string.gmatch(symb, ".") do
        local elem_code, elem_text, err = self:_check_char(c, parse_state)
        if err then
            return nil, err
        else
            if elem_code then
                chars_code[#chars_code + 1] = elem_code
            end
            if elem_text then
                chars_text = chars_text or {}
                chars_text[#chars_text + 1] = elem_text
            end
        end
    end
    -- build the barcode object
    local o = {
        _classname = "BarcodeSymbol",
        _code_data = chars_code, -- array of chars
        _code_text = chars_text,
    }
    setmetatable(o, self)
    if opt ~= nil then
        if type(opt) ~= "table" then
            return nil, "[ArgErr] 'opt' is not a table"
        else
            local ok, err = o:set_param(opt)
            if not ok then
                return nil, err
            end
        end
    end
    if o._finalize then
        local ok, e = o:_finalize(parse_state)
        if not ok then return nil, e end
    end
    return o, nil
end

-- positive integer --> Barcode object
function Barcode:from_uint(n, opt) --> object, err
    if type(n) ~= "number" then
        return nil, "[ArgErr] 'n' is not a number"
    end
    if n < 0 then
        return nil, "[ArgErr] 'n' must be a positive integer"
    end
    if n - math.floor(n) ~= 0 then
        return nil, "[ArgErr] 'n' is not an integer"
    end
    if opt ~= nil and type(opt) ~= "table" then
        return nil, "[ArgErr] 'opt' is not a table"
    end
    local digits_code = {}
    local digits_text
    local parse_state
    if self._init_parse_state then
        parse_state = self:_init_parse_state()
    else
        parse_state = {}
    end
    if n == 0 then
        local elem_code, elem_text, err = self:_check_digit(0, parse_state)
        if err then
            return nil, err
        end
        if elem_code then
            digits_code[1] = elem_code
        end
        if elem_text then
            digits_text = {elem_text}
        end
    else
        while n > 0 do
            local d = n % 10
            local elem_code, elem_text, err = self:_check_digit(d, parse_state)
            if err then
                return nil, err
            end
            if elem_code then
                digits_code[#digits_code + 1] = elem_code
            end
            if elem_text then
                digits_text = digits_text or {}
                digits_text[#digits_text + 1] = elem_text
            end
            n = (n - d) / 10
        end
        local rev_array = function (a)
            local len = #a
            for k = 1, len/2 do -- reverse the array
                local h = len - k + 1
                a[k], a[h] = a[h], a[k]
            end
        end
        rev_array(digits_code)
        if digits_text then
            rev_array(digits_text)
        end
    end
    -- build the barcode object
    local o = {
        _classname = "BarcodeSymbol",
        _code_data = digits_code, -- array of digits
        _code_text = digits_text, -- array of human readable information
    }
    setmetatable(o, self)
    if opt ~= nil then
        if type(opt) ~= "table" then
            return nil, "[ArgErr] 'opt' is not a table"
        else
            local ok, err = o:set_param(opt)
            if not ok then
                return nil, err
            end
        end
    end
    if o._finalize then
        local ok, e = o:_finalize(parse_state)
        if not ok then return nil, e end
    end
    return o, nil
end

-- recursive general Barcode costructor
function Barcode:new(code) --> object, err
    local t = type(code)
    if t == "string" then
        return self:from_string(code)
    elseif t == "number" then
        return self:from_uint(code)
    elseif t == "table" then
        local res = {}
        for _, c in ipairs(code) do
            local b, err = self:new(c)
            if err then return nil, err end
            res[#res + 1] = b
        end
        return res, nil
    else
        return nil, "[ArgErr] unsuitable type '"..t.."' for the input code"
    end
end

-- check a parameter set
-- this method check also reserved parameter
-- argments: {k=v, ...}, "default" | "current"
-- if ref is "default" parameters are checked with default values
-- if ref is "current" parameters are checked with current values
function Barcode:check_param(opt, ref) --> boolean, check report
    if type(opt) ~= "table" then
        return nil, "[ArgErr] opt is not a table"
    end
    if ref == nil then
        ref = "current"
    else
        if type(ref) ~= "string" then
            return nil, "[ArgErr] ref is not a string"
        end
        if (ref ~= "current") or (ref ~= "default") then
            return nil, "[ArgErr] ref can only be 'default' or 'current'"
        end
    end
    -- checking process
    local cktab  = {}
    local isOk   = true
    local err_rpt -- nil if no error
    for _, tpar in self:param_ord_iter() do
        local pname = tpar.pname
        local pdef  = tpar.pdef
        -- load the default value of <pname>
        local def_val; if pdef.fndefault then
            def_val = pdef:fndefault(cktab)
        else
            def_val = pdef.default
        end
        local val = opt[pname]
        if val ~= nil then
            local ok, err = pdef:fncheck(val, cktab)
            if ok then
                cktab[pname] = val
            else -- error!
                isOk = false
                if err_rpt == nil then err_rpt = {} end
                err_rpt[#err_rpt + 1] = {
                    param       = pname,
                    checked_val = val,
                    default_val = def_val,
                    isOk        = ok,
                    err         = err,
                }
            end
        end
        local v
        if ref == "current" then
            v = self[pname]
        else
            v = def_val
        end
        cktab[pname] = v
    end
    return isOk, err_rpt
end

-- restore to the default values all the parameter
-- (reserved parameters are unmodified so no need to restore it)
-- this need further investigation about the conseguence of a restore
-- that reset the parameter but "locally"
-- so this method must be considered experimental
function Barcode:restore_param() --> self :FIXME:
    for _, par in ipairs(self._par_id) do
        local pdef = self[par.."_def"]
        if not pdef.isReserved then
            self[par] = pdef.default
        end
    end
    return self
end

-- create a table with the information of the current barcode encoder
function Barcode:info() --> table
    local info = {
        name        = self._NAME,
        version     = self._VERSION,
        description = self._DESCRIPTION,
        param       = {},
    }
    local tpar = info.param
    for _, pdef in self:param_ord_iter() do
        local id = pdef.pname
        local def = pdef.pdef
        tpar[#tpar + 1] = {
            name       = id,
            descr      = def.descr,
            value      = self[id],
            isReserved = def.isReserved,
            unit       = def.unit,
        }
    end
    return info
end

-- return internal code representation
function Barcode:get_code() --> array
    if self._classname == "BarcodeSymbol" then
        local code = self._code_data
        local res = {}
        for _, c in ipairs(code) do
            res[#res + 1] = c
        end
        return res
    else
         error("[Err: OOP] 'BarcodeSymbol' only method")
    end
end

-- human readable interpretation hri or nil
function Barcode:get_hri() --> array|nil
    if self._classname == "BarcodeSymbol" then
        local code = self._code_text
        if code == nil then return nil end
        local res = {}
        for _, c in ipairs(code) do
            res[#res + 1] = c
        end
        return res
    else
         error("[Err: OOP] 'BarcodeSymbol' only method")
    end
end

-- make accessible by name parameter values
-- id: parameter identifier
function Barcode:get_param(id) --> value, err
    if type(id) ~= "string" then
        return nil, "[ArgErr] 'id' must be a string"
    end
    local par_def = self._par_def
    if not par_def[id] then
        return nil, "[Err] Parameter '"..id.."' doesn't exist"
    end
    local res = assert(self[id], "[InternalErr] parameter value unreachable")
    return res, nil
end

-- set a barcode parameter only if it is not reserved
-- arguments:
-- :set_param{key = value, key = value, ...}
-- :set_param(key, value)
function Barcode:set_param(arg1, arg2) --> boolean, err
    -- processing arguments
    local targ
    local isPair = true
    if type(arg1) == "table" then
        if arg2 ~= nil then
            return false, "[ArgErr] Further arguments not allowed"
        end
        targ = arg1
        isPair = false
    elseif type(arg1) == "string" then -- key/value
        if arg2 == nil then
            return false, "[ArgErr] 'value' as the second argument expected"
        end
        targ = {}
        targ[arg1] = arg2
    else
        return false, "[ArgErr] param name must be a string"
    end
    -- preparing the check process
    local cktab  = {}
    local ckparam = {}
    for _, tpar in self:param_ord_iter() do -- checking process
        local pname = tpar.pname
        local pdef  = tpar.pdef
        local val = targ[pname] -- par = val
        if val ~= nil then
            if pdef.isReserved then
                return false, "[Err] parameter '" .. pname ..
                    "' is reserved, create another encoder"
            end
            local ok, err = pdef:fncheck(val, cktab)
            if ok then
                cktab[pname] = val
                ckparam[pname] = val
            else -- error!
                return false, err
            end
        else -- no val in user option
            cktab[pname] = self[pname]
        end
    end
    for p, v in pairs(ckparam) do
        self[p] = v
    end
    return true, nil
end

-- canvas is a gaCanvas object
-- tx, ty is an optional point to place symbol local origin on the canvas plane
function Barcode:draw(canvas, tx, ty) --> canvas, err
    local nclass = self._classname
    if nclass == "Barcode" then
        error("[ErrOOP:Barcode] method 'draw' must be called only on a Symbol object")
    end
    if nclass == "Encoder" then
        error("[ErrOOP:Encoder] method 'draw' must be called only on a Symbol object")
    end
    assert(nclass == "BarcodeSymbol")
    if canvas._classname ~= "gaCanvas" then
        return nil, "[ErrOOP:canvas] object 'gaCanvas' expected"
    end
    local ga_fn = assert(
        self._append_ga,
        "[InternalErr] unimplemented '_append_ga' method"
    )
    local bb_info = ga_fn(self, canvas, tx or 0, ty or 0)
    local dbg_bbox = self.debug_bbox
    if dbg_bbox == "none" then
        -- do nothing
    else
        -- dashed style: phase = 3bp, dash pattern = 6bp 3bp
        local bp = canvas.bp
        local W = bp/10 -- 0.1bp
        local w = W/2
        assert(canvas:encode_linewidth(W))
        assert(canvas:encode_dash_pattern(3*bp, 6*bp, 3*bp))
        local x1, y1, x2, y2 = bb_info[1], bb_info[2], bb_info[3], bb_info[4]
        if dbg_bbox == "symb" then
            assert(canvas:encode_rect(x1 + w, y1 + w, x2 - w, y2 - w))
        elseif dbg_bbox == "qz" then
            local q1, q2, q3, q4 = bb_info[5], bb_info[6], bb_info[7], bb_info[8]
            x1 = x1 - (q1 or 0) + w
            y1 = y1 - (q2 or 0) + w
            x2 = x2 + (q3 or 0) - w
            y2 = y2 + (q4 or 0) - w
            assert(canvas:encode_rect(x1, y1, x2, y2))
        elseif dbg_bbox == "qzsymb" then
            local q1, q2, q3, q4 = bb_info[5], bb_info[6], bb_info[7], bb_info[8]
            x1 = x1 + w
            y1 = y1 + w
            x2 = x2 - w
            y2 = y2 - w
            if q1 then
                assert(canvas:encode_vline(y1, y2, x1))
                x1 = x1 - q1
            end
            if q3 then
                assert(canvas:encode_vline(y1, y2, x2))
                x2 = x2 + q3
            end 
            if q2 then
                assert(canvas:encode_hline(x1, x2, y1))
                y1 = y1 - q2
            end
            if q4 then
                assert(canvas:encode_hline(x1, x2, y2))
                y2 = y2 + q4
            end
            assert(canvas:encode_rect(x1, y1, x2, y2))
        else
            error("[InternalErr:debug_bbox] unrecognized enum value")
        end
        assert(canvas:encode_reset_pattern())
    end
    return canvas
end

return Barcode

--