\input minim-doc.sty \chapter Programming macros This chapter describes the programming helper modules on which all the above modules depend. It mainly concerns register allocation, callback management and format file inclusion. They can be loaded separately by saying ⟦\input minim-alloc⟧; thereafter, you can use ⟦local M = require('minim-alloc')⟧ to access the lua interface. In this chapter, when discussing lua functions, you are assumed to have issued the latter statement, so that the table ⟦M⟧ refers to the contents of this module. The callback-related code lives in a separate file that can and must be loaded separately as ⟦local C = require('minim-callbacks')⟧. This is the only file in this collection that does not itself depend on the minim-alloc module. There is a large functional overlap between this module and the ltluatex package. You can use both at the same time, however, and the order in which you load both packages should not matter. \section Format files A major motivation for writing this module (and not, instead, depending on ltluatex) is the ability to write lua-heavy code that can be safely included in format files. For this purpose, the register allocation functions described below allow ensuring that the allocation is made only once. Apart from registers, you need only do two more things to make your code format file safe. The first is saying ⟦*M.remember('your-file.lua')⟧ somewhere, anywhere. This will mark your file for inclusion in the format. At the start of every job, all remembered files will be executed (in order) and their return values will be stored to be retrieved whenever you say ⟦require('your-file')⟧. Note that while this feature does not improve speed in any meaningful way, it will ensure the lua file used by the format is identical to the one used to create it. It does mean, however, that your file may be executed twice: once when building the format and once when the format is used. In most cases (e.g. callback registration) this is exactly what you want. Sometimes however, you may need to store variable (configurable) data in the format file. You can do this by saying ⟦*local t = M.saved_table('identifier', default-table)⟧. This will retrieve the table from the format file if possible; otherwise, it will return ⟦default-table⟧ and mark it to be saved to the format. A missing second argument is equivalent to an empty table. Saved tables may only contain (arbitrary but non-cyclic nestings of) tables, numbers and strings. \section Register allocation For allocating the new luatex registers, you can use the following: ⟦*\newfunction⟧, ⟦*\newattribute⟧, ⟦*\newwhatsit⟧, ⟦*\newluabytecode⟧, ⟦*\newluachunkname⟧, ⟦*\newcatcodetable⟧ and ⟦*\newuserrule⟧. Note the one difference with ltluatex, which has ⟦\newluafunction⟧ instead. (The reason for this is that ltluatex, instead of a more sensible method, uses this macro for determining whether it has been read before.) Internally, the very same counts are used for keeping track of register allocation as in ltluatex. Their effect should therefore be identical in all circumstances, with one exception: no bounds checking is performed on any allocation macro defined by minim. Please do not go and use more than sixty five thousand different whatsits. All the above and all traditional registers can be allocated from within lua as well, using ⟦*M.new_count('name')⟧, ⟦*M.new_whatsit('name')⟧ etc. All return the allocated number. The (optional) string ⟦name⟧ prevents the same allocation from being made twice: if another register has been retrieved with the same name, the number of that register will be returned. You will need this when you want to allow your lua code to be included in a format file; it has nothing to do with the tex-side ⟦\countdef⟧ and the like. If you want to access from lua a register defined in tex, the function ⟦*M.registernumber('name')⟧ will give you the index of register ⟦\name⟧. Besides ⟦\newluachunkname\name⟧, you can also use ⟦*\setluachunkname \name {actual name}⟧ to enter the value of the name directly. Finally, for the registers for which etex defines a local allocation macro (and for those only), you can use ⟦*M.local_count()⟧ etc. These allocation functions take no parameters. \section Callbacks As noted at the beginning of this chapter, the callback functions are only available after you say ⟦local C = require('minim-callbacks')⟧. The simple function of this module is allowing multiple callbacks to co-exist. Different callbacks call for different implementations, and some callbacks can only contain a single function. Its interface matches the primitive interface, with ⟦*C.register(callback, fn)⟧, ⟦*C.find(callback)⟧ and ⟦*C.list()⟧ taking the same arguments. In addition to these, ⟦*C.deregister(fn)⟧ will allow you to remove a callback. This is necessary when you want to remove a callback from a list or from the bottom of a stack. The ⟦fn⟧ variable should point to the same object. Any callbacks that are already assigned before loading this module will be preserved and the primitive callback interface is still available, though callbacks registered through the latter will actually use the new functions. Ltluatex may be loaded either before or after this module. You can create your own callbacks with ⟦*C.new_callback(name, type)⟧. The ⟦type⟧ should be one of the types mentioned below or ⟦'single'⟧ for callbacks that allow only one function. If the ⟦name⟧ is that of a primitive callback, new registrations will target your new callback. You can call the new callback with ⟦*C.call_callback(name, ...)⟧, adding any number of parameters. Callbacks of type ⟦*node⟧ operate on a node list: for these, all registered functions will be called in order, each function receiving the result of the last. After one function returns ⟦false⟧, no others will be called. Callbacks of this type are ⟦pre_output_filter⟧, ⟦post_linebreak_filter⟧, ⟦pre_linebreak_filter⟧, ⟦hpack_filter⟧, ⟦vpack_filter⟧ and ⟦mlist_to_mlist⟧. Similarly, for the ⟦*data⟧ callbacks ⟦process_jobname⟧, ⟦process_output_buffer⟧ and ⟦process_input_buffer⟧, all registered functions will be called in order on the output of the previous. Returning ⟦false⟧ will in this case result in the output of the previous function passing to the next. For ⟦*stack⟧ callbacks, a stack is kept and only the top function on the stack will be called. These are ⟦mlist_to_hlist⟧, ⟦hpack_quality⟧, ⟦vpack_quality⟧, ⟦hyphenate⟧, ⟦linebreak_filter⟧, ⟦buildpage_filter⟧ and ⟦build_page_insert⟧. Register ⟦nil⟧ at the callback to pop a function off the stack. Finally, for the ⟦*simple⟧ callbacks ⟦uselanguage⟧, ⟦contribute_filter⟧, ⟦pre_dump⟧, ⟦wrapup_run⟧, ⟦finish_pdffile⟧, ⟦finish_pdfpage⟧, ⟦insert_local_par⟧, ⟦ligaturing⟧, ⟦kerning⟧ and ⟦process_rule⟧. all registered functions are called in order with the same arguments. Two callbacks are new: the new ⟦*mlist_to_mlist⟧ callback is called before ⟦mlist_to_hlist⟧ and should not convert noads to nodes, while the ⟦*uselanguage⟧ callback is called from ⟦\uselanguage⟧. If you create a new callback with a number for a name, that callback will replace the ⟦*process_rule⟧ callback when its number matches the index property of the rule. \section PDF resources This package can perform sophisticated pdf resource management, assigning to every page a resource object containing only the resources referenced on that page. pdf resources are ⟦ExtGstate⟧, ⟦ColorSpace⟧, ⟦Pattern⟧ and ⟦Shading⟧ objects that have to be referenced by name (⟦/name⟧) instead of with the usual object references (⟦n 0 R⟧).\footnote {*}{This is of course also the case for ⟦Font⟧ resources, but those are already managed by luatex’s pdf backend.} Currently, the only other package managing pdf resources for plain tex is tikz/pgf, and the latter does so by collecting all resources in a single (global) resource object. That approach is not wrong per se, but may cause other tools processing the resulting pdf to retain unneeded resources. Both implementations can safely be used together, but since pgf does not keep track of actual resource use, any resources defined through pgf will be added to the resource dictionary of every subsequent page. The resource management is implemented in minim-pdfresources.lua and minim-pdfresources.tex, of which the tex file currently only includes pgf compatibility code (and may thus be omitted in the absence of pgf). In the following, ⟦R = require 'minim-pdfresources'⟧ is understood. You must register resources before you use them. This can be done with ⟦*R.add_resource(kind, name, resource)⟧, where ⟦kind⟧ is one of the resource types, ⟦name⟧ is the name you want to use for it (without a preceding slash) and ⟦resource⟧ is a table that may contain any data you want to associate with the resource. In the ⟦resource⟧ table, either the key ⟦value⟧ must be present (containing the (raw) contents of the resource; will be written to the pdf as-is) or the key ⟦write⟧ (which must be a function that will be called once, to generate the ⟦value⟧). Registered resources can be retrieved again with ⟦*R.get_resource(kind, name)⟧. You can refer to registered resources with the ⟦name⟧ you used to register them. Whenever you do so, however, you must mark the reference with a special ⟦late_lua⟧ node that will tell minim to include the resource in the resource list for the page it appears on. These nodes can be created from lua with ⟦*R.use_resource_node(kind, name)⟧ or directly inserted by tex with ⟦*\withpdfresource {kind} {name}⟧ (the braces are optional). \section Programming helpers Optional keyword arguments to tex macros can be defined with help of ⟦*M.options_scanner()⟧. An example from the definition of minim-pdf’s ⟦\outline⟧: ⟦ local s = M.options_scanner() :keyword('open', 'closed') :string('dest') :scan() s.title = token.scan_string() M.add_bookmark(s)⟧ Here, the ⟦keyword⟧ function adds two opposite keywords: if one is present, its value will be set to ⟦true⟧ and the other’s to ⟦false⟧ (the second keyword is optional). The ⟦string⟧ function stores the result of ⟦token.scan_string⟧ under its key. Of the same form you have ⟦int⟧, ⟦glue⟧, ⟦dimen⟧, ⟦argument⟧, ⟦word⟧ and ⟦list⟧. All these take an optional second argument: if ⟦true⟧ then the keyword can be repeated and its values will be stored as a list. The ⟦scan⟧ function, finally, scans all keywords, which may appear in any order. You can give it a table with default values. In the example given above, the argument ⟦s⟧ to ⟦M.add_bookmark⟧ will consist of a table with at most the following entries: ⟦open⟧, ⟦closed⟧, ⟦dest⟧ and ⟦title⟧, though entries whose keywords do not occur will not be present. This function is particularly useful when used with ⟦*M.luadef('csname', function, ...)⟧, which defines primitive-like tex macros from lua. There, ⟦function⟧ can be any function (it will be assigned a lua function register) and at the place of the dots you may append ⟦'protected'⟧ and/or ⟦'global'⟧. \section Miscellaneous functions The small functions ⟦*M.msg(...)⟧, ⟦*M.log(...)⟧ and ⟦*M.err(...)⟧ include a call to ⟦M.string.format⟧; additionally, ⟦*M.amsg(...)⟧ and ⟦*M.alog(...)⟧ do not start a new line. Both ⟦*M.unset⟧ and ⟦*\unset⟧ contain the value ⟦-0x7FFFFFFF⟧ that can be used for clearing attributes. When writing data to pdf literals, ⟦*M.pdf_string(...)⟧, ⟦*M.pdf_name(...)⟧ and ⟦*M.pdf_date(...)⟧ may be useful: they produce strings that can be written to the pdf directly. Surrounding ⟦<>⟧ or ⟦()⟧ characters or a leading ⟦/⟧ will be included in the return value. The ⟦M.pdf_date⟧ function expects a value of the form ⟦yyyy[-mm[-dd]]⟧ and returns a date of the form ⟦(D:yyyymmdd)⟧. The function ⟦M.pdf_string⟧ is also available to tex through the macro ⟦*\pdfstring⟧. Finally the function ⟦*M.table_to_text(table)⟧ may be useful when debugging lua code: it dumps a table as a (lua-readable) string. Cyclic references will spin in into an eternal loop, however. \section Miscellaneous helper macros On the tex side, ⟦*\voidbox⟧, ⟦*\ignore⟧, ⟦*\spacechar⟧, ⟦*\unbrace⟧, ⟦*\firstoftwo⟧ and ⟦*\secondoftwo⟧ should be self-explanatory and uncontroversial additions. ⟦*\Ucharcat⟧ works as in xetex. For looking ahead, you can use ⟦*\nextif \token {executed if present} {executed if not}⟧ or its siblings ⟦*\nextifx⟧ and ⟦*\nextifcat⟧. For defining macros with optional arguments, ⟦*\withoptions[default]{code}⟧ will ensure something within square brackets follows ⟦code⟧. Finally, ⟦*\splitcommalist {code} {list}⟧ will apply ⟦code⟧ to every nonempty item on a comma-separated ⟦list⟧. Items of the list will be re-tokenised and have surrounding spaces removed. This macro is fully expandable. Because of their usefulness and simplicity, these macros have been made available without special characters in their names; I hope you can tolerate their presence. Please let me know if their names clash with something important. \endinput