# Writing scripts to change fonts in PfaEdit

PfaEdit includes an interpreter so you can write scripts to modify fonts.

- Starting a script
- Scripting language
  - Built in variables
  - Built in procedures
  - Examples
- The Execute Script dialog
- The Scripts menu

## Starting scripts

If you start pfaedit with a script on the command line it will not put up any windows and it will exit when the script is done.

>     $ pfaedit -script scriptfile.pe {fontnames}

PfaEdit can also be used as an interpreter that the shell will automatically pass scripts to. If you a mark your script files as executable
`$ chmod +x scriptfile.pe`
and begin each one with the line
`#!/usr/local/bin/pfaedit`
(or wherever pfaedit happens to reside on your system) then you can invoke the script just by typing
`$ scriptfile.pe {fontnames}`

If you wish PfaEdit to read a script from stdin then you can use "-" as a "filename" for stdin. (If you build PfaEdit without X11 then pfaedit will attempt to read a script file from `stdin` if none is given on the command line.)

You can also start a script from within PfaEdit with `File->Execute Script`, and you can use the Preference Dlg to define a set of frequently used scripts which can be invoked directly by menu.

The scripting language provides access to much of the functionality found in the font view's menus. It does not currently (and probably never will) provide access to everything. (If you find a lack let me know, I may put it in for you). It does not provide commands for building up a character out of splines, instead it allows you to do high level modifications to characters.

If you set the environment variable `PFAEDIT_VERBOSE` (it doesn't need a value, just needs to be set) then PfaEdit will print scripts to stdout as it executes them.

In general I envision this as being useful for things like taking a latin font and extending it to contain cyrillic characters. So the script might:

- Reencode the font
- Place a reference to Latin "A" at Cyrillic "A"
- Copy Latin "R" to Cyrillic "YA"
- Flip "YA" horizontally
- Correct its direction
- ... and so forth

## Scripting Language

The syntax is rather like a mixture of C and shell commands. Every file corresponds to a procedure. As in a shell script arguments passed to the file are identified as $1, $2, ... $n. $0 is the file name itself. $argc gives the number of arguments. $argv[<expr>] provides array access to the arguments.

Terms can be

- A variable name (like "$1" or "i" or "@fontvar" or "_global")
  The scope of the variable depends on the initial character of its name.
  - A '$' signifies that it is a built-in variable. The user cannot create any new variables beginning with '$'. Some, but not all, of these may be assigned to.
  - A '_' signifies that the variable is global, it is always available. You can use these to store context across different script files (or to access data within nested script files).
  - A '@' signifies that the variable is associated with the font. Any two scripts looking at the same font will have access to the same variables.
  - A variable which begins with a letter is a local variable. It is only meaningful within the current script file. Nested script files may have different variables with the same names.
- an integer expressed in decimal, hex or octal
- a unicode code point (which has a prefix of "0u" or "0U" and is followed by a string of hex digits. This is only used by the select command.
- A string which may be enclosed in either double or single quotes
- a procedure to call or file to invoke.
- an expression within parentheses

There are three different comments supported:

- Starting with a "#" character and proceding to end of line
- Starting with "//" and proceding to end of line
- Starting with "/*" and proceding to "*/"

Expressions are similar to those in C, a few operators have been omitted, a few added from shell scripts. Operator precedence has been simplified slightly. So operators (and their precedences) are:

- unary operators (+, -, !, ~, ++ (prefix and postfix), --(prefix and postfix), () (procedure call), [] (array index), :h, :t, :r, :e
  Most of these are as expected in C, the last four are borrowed from shell scripts and are applied to strings
  - :h gives the head (directory) of a pathspec
  - :t gives the tail (filename) of a pathspec
  - :r gives the pathspec without the extension (if any)
  - :e gives the extension
- *, /, % (binary multiplicative operators)
- +, - (binary arithmetric operators)
  If the first operand of + is a string then + will be treated as concatenation rather than addition. If the second operand is a number it will be converted to a string (decimal representation) and then concatenated.
- ==, !=, >, <, >=, <= (comparison operators, may be applied to either two integers or two strings)
- &&, & (logical and, bitwise and. (logical and will do short circuit evaluation))
- ||, |, ^ (logical or, bitwise or, bitwise exclusive or (logical or will do short circuit evaluation))
- =, +=, -=, *=, /=, %= (assignment operators as in C. The += will act as concatenation if the first operand is a string.)

Note there is no comma operator, and no "?:" operator. The precedence of "and" and "or" has been simplified, as has that of the assignment operators.

Procedure calls may be applied either to a name token, or to a string. If the name or string is recognized as one of PfaEdit's internal procedures it will be executed, otherwise it will be assumed to be a filename containing another pfaedit script file, this file will be invoked (since filenames can contain characters not legal in name tokens it is important to allow general strings to specify filenames). If the procedure name does not contain a directory then it is assumed to be in the same directory as the current script file.

Arrays are passed by reference, strings and integers are passed by value.

Variables may be created by assigning a value to them (only with the "="), so:
`i=3`
could be used to define "i" as a variable. Variables are limited in scope to the current file, they will not be inherited by called procedures.

A statement may be

- an expression
- `if ( expression )
  statements
  {elseif ( expression )
  statements}
  [else
  statements]
  endif`
- `while ( expression )
  statements
  endloop`
- `foreach
  statements
  endloop`
- `return [ expression ]`
- `shift`

As with C, non-zero expressions are defined to be true.
A return statement may be followed by a return value (the expression) or a procedure may return nothing (void).
The shift statement is stolen from shell scripts and shifts all arguments down by one. (argument 0, the name of the script file, remains unchanged.
The foreach statement requires that there be a current font. It executes the statements once for each character in the selection. Within the statements only one character at a time will be selected. After execution the selection will be restored to what it was initially. (Caveat: Don't reencode the font within a foreach statement).
Statements are terminated either by a new line or a semicolon.

Trivial example:

>     i=0;	#semicolon is not needed here, but it's ok
>     while ( i<3 )
>        if ( i==1 /* pointless comment */ )
>     	Print( "Got to one" )	// Another comment
>        endif
>        ++i
>     endloop

PfaEdit maintains the concept of a "current font" almost all commands refer only to the current font (and require that there be a font). If you start a script with File->Execute Script, the font you were editing will be current, otherwise there will be no initial current font. The Open(), New() and Close() commands all change the current font. PfaEdit also maintains a list of all fonts that are currently open. This list is in no particular order. The list starts with $firstfont.

Similarly when working with cid keyed fonts, PfaEdit works in the "current sub font", and most commands refer to this font. The CIDChangeSubFont() command can alter that.

All builtin variables begin with "$", you may not create any variables that start with "$" yourself (though you may assign to (some) already existing ones)

- `$0` the current script filename
- `$1` the first argument to the script file
- `$2` the second argument to the script file
- ...
- `$argc` the number of arguments passed to the script file (this will always be at least 1 as $0 is always present)
- `$argv` allows you to access the array of all the arguments
- `$curfont` the name of the filename in which the current font resides
- `$firstfont` the name of the filename of the font which is first on the font list (Can be used by Open()), if there are no fonts loaded this returns an empty string. This can be used to determine if any font at all is loaded into pfaedit.
- `$nextfont` the name of the filename of the font which follows the current font on the list (or the empty string if the current font is the last one on the list)
- `$fontchanged` returns 1 if the current font has changed, 0 if it has not changed since it was read in (or saved).
- `$fontname` the name contained in the postscript FontName field
- `$familyname` the name contained in the postscript FamilyName field
- `$fullname` the name contained in the postscript FullName field
- `$weight` the name contained in the postscript Weight field
- `$copyright` the name contained in the postscript Notice field
- `$filename` the name of the file containing the font.
- `$fontversion` the string containing the font's version
- `$cidfontname` returns the fontname of the top-level cid-keyed font (or the empty string if there is none)
  Can be used to detect if this is a cid keyed font.
- `$cidfamilyname, $cidfullname, $cidweight, $cidcopyright` similar to above
- `$italicangle` the value of the postscript italic angle field
- `$curcid` returns the fontname of the current font
- `$firstcid` returns the fontname of the first font within this cid font
- `$nextcid` returns the fontname of the next font within this cid font (or the empty string if the current sub-font is the last)
- `$bitmaps` returns an array containing all bitmap pixelsizes generated for this font. (If the font database contains greymaps then they will be indicated in the array as `(<BitmapDepth><<16)|<PixelSize>`)
- `$selection` returns an array containing one entry for each character in the current font indicating whether that character is selected or not (0=>not, 1=>selected)
- `$panose` returns an array containing the 10 panose values for the font.
- `$trace` if this is set to one then PfaEdit will trace each procedure call.
- `$version` returns a string containing the current version of pfaedit. This should look something like "020817".
- `$`<Preference Item> (for example `$AutoHint`) allows you to examine the value of that preference item (to set it use `SetPref`)

The following example will perform an action on all loaded fonts:

>     file = $firstfont
>     while ( file != "" )
>        Open(file)
>        /* Do Stuff */
>        file = $nextfont
>     endloop

The built in procedures are very similar to the menu items with the same names.

Print(arg1,arg2,arg3,...)
  This corresponds to no menu item. It will print all of its arguments to stdout. It can execute with no current font.
PostNotice(str)
  When run from the UI will put up a window displaying the string (the window will not block the program and will disappear after a minute or so). When run from the command line will write the string to stderr.
Error(str)
  Prints out str as an error message and aborts the current script
AskUser(question[,default-answer])
  Asks the user the question and returns an answer (a string). A default-answer may be specified too.
Array(size)
  Allocates an array of the indicated size.

  >     a = Array(10)
  >     i = 0;
  >     while ( i<10 )
  >        a[i] = i++
  >     endloop
  >     a[3] = "string"
  >     a[4] = Array(10)
  >     a[4][0] = "Nested array";

SizeOf(arr)
  Returns the number of elements in an array.
Strsub(str,start[,end])
  Returns a substring of the string argument. The substring beings at position indexed by start and ends at the position indexed by end (if end is omitted the end of the string will be used, the first position is position 0). Thus `Strsub("abcdef",2,3) == "c"` and `Strsub("abcdef",2) == "cdef"`
Strlen(str)
  Returns the length of the string.
Strstr(haystack,needle)
  Returns the index of the first occurance of the string needle within the string haystack (or -1 if not found).
Strrstr(haystack,needle)
  Returns the index of the last occurance of the string needle within the string haystack (or -1 if not found).
Strcasestr(haystack,needle)
  Returns the index of the first occurance of the string needle within the string haystack ignoring case in the search (or -1 if not found).
Strcasecmp(str1,str2)
  Compares the two strings ignoring case, returns zero if the two are equal, a negative number if str1<str2 and a positive number if str1>str2
Strtol(str[,base])
  Parses as much of str as possible and returns the integer value it represents. A second argument may be used to specify the base of the conversion (it defaults to 10). Behavior is as for strtol(3).
Strskipint(str[,base])
  Parses as much of str as possible and returns the offset to the first character that could not be parsed.
GetPref(str)
  Gets the value of the preference item whose name is contained in str. Only boolean, integer, real, string and file preference items may be returned. Boolean and real items are returned with integer type and file items are returned with string type.
SetPrefs(str,val[,val2])
  Sets the value of the preference item whose name is containted in str. If the preference item has a real type then a second argument may be passed and the value set will be val/val2.
UnicodeFromName(name)
  Looks the string "name" up in PfaEdit's database of commonly used glyph names and returns the unicode value associated with that name, or -1 if not found. This does not check the current font (if any).
Chr(int)
Chr(array)
  Takes an integer [0,255] and returns a single character string containing that code point. Internally PfaEdit interprets strings as if they were in ISO8859-1 (well really, PfaEdit just uses ASCII-US internally). If passed an array, it should be an array of integers and the result is the string.
Ord(string[,pos])
  Returns an array of integers represenging the encoding of the characters in the string. If pos is given it should be an integer less than the string length and the function will return the integer encoding of that character in the string.
Utf8(int)
  Takes an integer [0,0x10ffff] and returns the utf8 string representing that unicode code point. If passed an array of integers it will generate a utf8 string containing all of those unicode code points. (it does not expect to get surrogates).

FontsInFile(filename)
  Returns an array of strings containing the names of all fonts within a file. Most files contain one font, but some (mac font suitcases, dfonts, ttc files, svg files, etc) may contain several. If the file contains no fonts (or the file doesn't exist, or the fonts aren't named), a zero length array is returned. It does not open the font. It can execute without a current font.
Open(filename[,flags])
  This makes the font named by filename be the current font. If filename has not yet been loaded into memory it will be loaded now. It can execute without a current font.
  When loading from a ttc file (mac suitcase, dfont, svg, etc), a particular font may be selected by placing the fontname in parens and appending it to the filename, as `Open("gulim.ttc(Dotum)")`
  The optional flags argument current has only one flag in it:
  - 1 => the user does have the appropriate license to examine the font no matter what the fstype setting is.
New()
  This creates a new font. It can execute with no current font.
Close()
  This frees up any memory taken up by the current font and drops it off the list of loaded fonts. After this executes there will be no current font.
Save([filename])
  If no filename is specified then this saves the current font back into its sfd file (if the font has no sfd file then this is an error). With one argument it executes a SaveAs command, saving the current font to that filename.
Generate(filename[,bitmaptype[,fmflags[,res[,mult-sfd-file]]]])
  Generates a font. The type of font is determined by the extension of the filename. Valid extensions are:
  - pfa
  - pfb
  - bin (a mac postscript (pfb) resource in a mac binary wrapper)
    res (on the Mac itself PfaEdit will put the result directly into a font suitcase file, and the extension should be ".res" rather than ".bin")
  - mult (splits a big font up into multiple pfb fonts each with 256 characters)
  - ps (type 0)
  - cid (non-otf cid font)
  - ttf
  - sym.ttf (a truetype file with a symbol (custom) encoding)
  - ttf.bin (a mac truetype resource in a mac binary wrapper)
    suit (on the Mac itself PfaEdit will put the result directly into a font suitcase file, and the extension should be ".suit" not ".ttf.bin")
  - dfont (a mac truetype resource in a dfont file)
  - otf (either cid or not depending on the font)
  - otf.dfont (a mac opentype resource in a dfont file)
  - svg (an svg font)
  - <null extension> If you don't want to generate an outline font at all (but do want to provide a filename for bitmap or metrics files) then provide a null extension (ie. `"Times."` but NOT `"Times"`).

  If present, bitmaptype may be one of:

  - bdf
  - ttf (for EBDT/bdat table in truetype/opentype)
  - sbit (for EBDT/bdat table in truetype without any outline font)
  - bin (for nfnt in macbinary)
  - dfont (for nfnt in dfont)
  - fnt (For windows FNT format)
  - otb (For X11 opentype bitmap format)
  - "" for no bitmaps

  If you do not wish to generate an outline font then give the filename the extension of ".bdf".
  fmflags controls whether an afm or pfm file should be generated

  - -1 => default (generate an afm file for postscript fonts, never generate a pfm file, full 'post' table, ttf hints)
  - fmflags&1 => generate an afm file
  - fmflags&2 => generate a pfm file
  - fmflags&4 => generate a short 'post' table with no character name info in it.
  - fmflags&8 => do not include ttf instructions
  - fmflags&16 => where apple and ms/adobe differ about the format of a true/open type file, use apple's definition (otherwise use ms/adobe)
    Currently this affects bitmaps stored in the font (Apple calls the table 'bdat', ms/adobe 'EBDT'), the PostScript name in the 'name' table (Apple says it must occur exactly once, ms/adobe say at least twice), and whether morx/feat/kern/opbd/prop/lcar or GSUB/GPOS/GDEF tables are generated.
  - fmflags&0x20 => generate a 'PfEd' table and store glyph comments
  - fmflags&0x40 => generate a 'PfEd' table and store glyph colors
  - fmflags&0x80 => generate tables so the font will work on both Apple and MS platforms.
  - fmflags&0x10000 => generate a tfm file
  - fmflags&0x40000 => do not do flex hints
  - fmflags&0x80000 => do not include postscript hints

  res controls the resolution of generated bdf fonts. A value of -1 means pfaedit will guess for each strike.

  If the filename has a ".mult" extension then a "mult-sfd-file" may be present. This is the filename of a file containing the mapping from the current encoding into the subfonts. Here is an example. If this file is not present PfaEdit will go through its default search process to find a file for the encoding, and if it fails the fonts will not be saved.

GenerateFamily(filename,bitmaptype,fmflags,array-of-font-filenames)
  Generates a mac font family (FOND) the fonts (which must be loaded) in the array-of-font-filenames. filename, bitmaptype, fmflags are as above.

  >     #!/usr/local/bin/pfaedit
  >     a = Array($argc-1)
  >     i = 1
  >     j = 0
  >     while ( i < $argc )
  >     # Open each of the fonts
  >       Open($argv[i], 1)
  >     # and store the filenames of all the styles in the array
  >       a[j] = $filename
  >       j++
  >       i++
  >     endloop

  >     GenerateFamily("All.otf.dfont","dfont",16,a)

ControlAfmLigatureOutput(script,lang,ligature-tag-list)
  All three arguments must be strings. The first two must be strings containing four or fewer characters, the third a string containing a comma seperated list of 4 (or fewer) character strings. Ligatures will be placed in an AFM file only if
  - their tags match one of the entries in the list
  - they are active in the given script with the given language ("*" acts as a wildcard for both script and language).

  The default setting is:

  >     ControlAfmLigatureOutput("*","dflt","liga,rlig")

Import(filename)
  Either imports a bitmap font into the database, or imports background image[s] into various characters. There may be one or two arguments. The first must be a string representing a filename. The extension of the file determines how the import procedes. If present the second argument must be an integer, if the first argument is a bitmap font then the second argument controls whether it is imported into the bitmap list (0) or to fill up the backgrounds of characters (1).
  - If the extension is ".bdf" then a bdf font will be imported
  - If the extension is ".pcf" then a pcf font will be imported.
  - If the extension is ".ttf" then the EBDT or bdat table of the ttf file will be searched for bitmap fonts
  - If the extension is "pk" then a metafont pk (bitmap font) file will be import and by default placed in the background
  - Otherwise if the extension is an image extension, and any loaded images will be placed in the background.
    - If the filename contains a "*" then it should be a recognized template in which case all images which match that template will be loaded appropriately and stored in the background
    - Otherwise there may be several filenames (seperated by semicolons), the first will be placed in the background of the first selected character, the second into the background of the second selected character, ...
  - Finally if the extension is "eps" then an encapsulated postscript file will be merged into the foreground. The file may be specified as for images (except the extension should be "eps" rather than an image extension). PfaEdit is very limitted in its ability to read eps files.
Export(format[,bitmap-size])
  For each selected character in the current font, this command will export that character into a file in the current directory. Format must be a string and must be one of
  - eps -- the selected characters will have their splines output into eps files. The files will be named "<glyph-name>_<font-name>.eps".
  - fig -- the selected characters will have their splines converted (badly) into xfig files. The files will be named "<glyph-name>_<font-name>.fig".
  - xbm -- The second argument specifies a bitmap font size, the selected characters in that bitmap font will be output as xbm files. The files will be named "<glyph-name>_<font-name>.xbm".
  - bmp -- The second argument specifies a bitmap font size, the selected characters in that bitmap font will be output as bmp files. The files will be named "<glyph-name>_<font-name>.bmp".
  - png -- The second argument specifies a bitmap font size, the selected characters in that bitmap font will be output as png files. The files will be named "<glyph-name>_<font-name>.png".
MergeKern(filename)
  Loads Kerning info out of either an afm or a tfm file and merges it into the current font.
PrintSetup(type,[printer[,width,height]])
  Allows you to configure the print command. Type may be a value between 0 and 4
  - 0 => print with lp
  - 1 => print with lpr
  - 2 => output to ghostview
  - 3 => output to file
  - 4 => other printing command

  If the type is 4 (other) and the second argument is specified, then the second argument should be a string containing the "other" printing command.
  If the type is 0 (lp) or 1 (lpr) and the second argument is specified, then the second argument should contain the name of a laser printer
  (If the second argument is a null string neither will be set).

  The third and fourth arguments should specify the page width and height respectively. Units are in points, so 8.5x11" paper is 612,792 and A4 paper is (about) 595,842.

PrintFont(type[,pointsize[,sample-text-file[,output-file]]])
  Prints the current font according to the PrintSetup. The values for type are (meanings are described in the section on printing):
  - 0 => Prints a full font display at the given pointsize
  - 1 => Prints selected characters to fill page
  - 2 => Prints selected characters at multiple pointsizes
  - 3 => Prints a text sample at the given pointsize(s)

  The pointsize is either a single integer or an array of integers. It is only meaningful for types 0 and 3. If omitted or set to 0 a default value will be chosen. The font display will only look at one value.

  If you selected print type 3 then you may provide the name of a file containing sample text. This file may either be in ucs2 format (preceded by a 0xfeff value), or in the current default encoding. A null string or an omitted argument will cause PfaEdit to use a default value.

  If your PrintSetup specified printing to a file then the fourth argument provides the filename of the output file.

Quit(status)
  Causes PfaEdit to exit with the given status. It can execute with no current font.

Cut
  Makes a copy of all selected characters and saves it in the clipboard, then clears out the selected characters
Copy
  Makes a copy of all selected characters.
CopyReference
  Makes references to all selected characters and stores them in the clipboard.
CopyWidth
  Stores the widths of all selected characters in the clipboard
CopyVWidth
  Stores the vertical widths of all selected characters in the clipboard
CopyLBearing
  Stores the left side bearing of all selected characters in the clipboard
CopyRBearing
  Stores the right side bearing of all selected characters in the clipboard
Paste
  Copies the clipboard into the selected characters of the current font (removing what was there before)
PasteInto
  Copies the clipboard into the current font (merging with what was there before)
SameGlyphAs
  If the clipboard contains a reference to a single character then this makes all selected characters refer to that one.
Clear
  Clears out all selected characters
ClearBackground
  Clears the background of all selected characters
CopyFgToBd
  Copies all foreground splines into the background in all selected characters
Join([fudge])
  Joins open paths in selected characters. If fudge is specified then the endpoints only need to be within fudge em-units of each other to be merged.
UnlinkReference
  Unlinks all references within all selected characters
SelectAll
  Selects all characters
SelectNone
  Deselects all characters
Select(arg1, arg2, ...)
  This clears out the current selection, then for each pair of arguments it selects all characters between (inclusive) the bounds specified by the pair. If there is a final singleton argument then that single character will be selected. An argument may be specified by:
  - an integer which specifies the location in the current font's encoding
  - a postscript unicode name which gets mapped into the current font's encoding
  - a unicode code point (0u61) which gets mapped to the current font's encoding
  - If Select is given exactly one argument and that argument is an array then the selection will be set to that specified in the array. So array[0] would set the selection of the character at encoding 0 and so forth. The array may have a different number of elements from that number of characters in the font.
SelectMore(arg1, arg2, ...)
  The same as the previous command except that it does not clear the selection, so it extends the current selection.
SelectIf(arg1,arg2, ...)
  The same as Select() except that instead of signalling an error when a character is not in the font it returns an error code.
  - 0 => there were no errors but no characters were selected
  - <a positive number> => there were no errors and this many characters were selected
  - -2 => there was an error and no characters were selected
  - -1 => there was an error and at least one character was selected before that.
SelectByATT(type,tags,contents,search-type)
  See the Select By ATT menu command. The values for type are:

  `"Position"` | Simple position
  `"Pair"` | Pairwise positioning (but not kerning)
  `"Substitution"` | Simple substitution
  `"AltSubs"` | Alternate substitution
  `"MultSubs"` | Multiple substitution
  `"Ligature"` | Ligature
  `"LCaret"` | Ligature caret
  `"Kern"` | Kerning
  `"VKern"` | Vertical Kerning
  `"Anchor"` | Anchor class

  And for search_type

  1. Select Results
  2. Merge Selection
  3. Restrict Selection

Reencode(encoding-name[,force])
  Reencodes the current font into the given encoding which may be:
  compacted,original,
  iso8859-1, isolatin1, latin1, iso8859-2, latin2, iso8859-3, latin3, iso8859-4, latin4, iso8859-5, iso8859-6, iso8859-7, iso8859-8, iso8859-9, iso8859-10, isothai, iso8859-13, iso8859-14, iso8859-15, latin0, koi8-r, jis201, jisx0201, AdobeStandardEncoding, win, mac, symbol, wansung, big5, johab, jis208, jisx0208, jis212, jisx0212, sjis, gh2312, gb2312packed, unicode, iso10646-1, TeX-Base-Encoding, one of the user defined encodings, or something of the form "unicode-plane-%x" to represent the x'th iso10646 plane (where the BMP is plane 0).
  You may also specify that you want to force the encoding to be the given one.
SetCharCnt(cnt)
  Sets the number of characters in the font.
LoadEncodingFile(filename)
SetFontOrder(order)
  Sets the font's order. Order must be either 2 (quadratic) or 3 (cubic).
SetFontNames(fontname[,family[,fullname[,weight[,copyright-notice[,fontversion]]]]])
  Sets various postscript names associated with a font. If a name is omitted (or is the empty string) it will not be changed.
SetItalicAngle(angle[,denom])
  Sets the postscript italic angle field appropriately. If denom is specified then angle will be divided by denom before setting the italic angle field (a hack to get real values). The angle should be in degrees.
SetPanose(array)
SetPanose(index,value)
  This sets the panose values for the font. Either it takes an array of 10 integers and sets all the values, or it takes two integer arguments and sets `font.panose[index] = value`
SetUniqueID(value)
  Sets the postscript uniqueid field as requested. If you give a value of 0 then PfaEdit will pick a reasonable random number for you.
SetTeXParams(type,design-size,slant,space,stretch,shrink,xheight,quad,extraspace[...])
  Sets the TeX (text) font parameters for the font.
  Type may be 1, 2 or 3, depending on whether the font is text, math or math extension.
  DesignSize is the pointsize the font was designed for.
  The remaining parameters are described in Knuth's The MetaFont Book, pp. 98-100.
  Slant is expressed as a percentage. All the others are expressed in em-units.
  If type is 1 then the 9 indicated arguments are required. If type is 2 then 24 arguments are required (the remaining 15 are described in the metafont book). If type is 3 then 15 arguments are required.
SetCharName(name[,set-from-name-flag])
  Sets the currently selected character to have the given name. If set-from-name-flag is absent or is present and true then it will also set the unicode value and the ligature string to match the name.
SetUnicodeValue(uni[,set-from-value-flag])
  Sets the currently selected character to have the given unicode value. If set-from-value-flag is absent or is present and true then it will also set the name and the ligature string to match the value.
SetCharColor(color)
  Sets any currently selected characters to have the given color (expressed as 24 bit rgb (0xff0000 is red) with the special value of -2 meaning the default color.
SetCharComment(comment)
  Sets the currently selected character to have the given comment. The comment is converted via the current encoding to unicode.
BitmapsAvail(sizes)
  Controls what bitmap sizes are stored in the font's database. It is passed an array of sizes. If a size is specified which is not in the font database it will be generated. If a size is not specified which is in the font database it will be removed. A size which is specifed and present in the font database will not be touched.
  If you want to specify greymap fonts then the low-order 16 bits will be the pixel size and the high order 16 bits will specify the bits/pixel. Thus 0x8000c would be a 12 pixel font with 8 bits per pixel, while either 0xc or 0x1000c could be used to refer to a 12 pixel bitmap font.
BitmapsRegen(sizes)
  Allows you to update specific bitmaps in an already generated bitmap font. It will regenerate the bitmaps of all selected characters at the specified pixelsizes.
ApplySubstitution(script,lang,tag)
  All three arguments must be strings of no more that four characters (shorter strings will be padded with blanks to become 4 character strings). For each selected character this command will look up that character's list of substitutions, and if it finds a substitution with the tag "tag" (and if that substitution matches the script and language combination) then it will apply the substitution-- that is it will find the variant character specified in the substitution and replace the current character with the variant, and remove the variant from the font.

  PfaEdit recognizes the string "*" as a wildcard for both the script and the language (not for the tag though). So you wish to replace all glyphs with their vertical variants:

  >     SelectAll()
  >     ApplySubstitution("*","*","vrt2")

Transform(t1,t2,t3,t4,t5,t6)
  Each argument will be divided by 100. and then all selected characters will be transformed by this matrix
HFlip([about-x])
  All selected characters will be horizontally flipped about the vertical line through x=about-x. If no argument is given then all selected characters will be flipped about their central point.
VFlip([about-y])
  All selected characters will be vertically flipped about the horizontal line through y=about-y. If no argument is given then all selected characters will be flipped about their central point.
Rotate(angle[,ox,oy])
  Rotates all selected character the specified number of degrees. If the last two args are specified they provide the origin of the rotation, otherwise the center of the character is used.
Scale(factor[,yfactor][,ox,oy])
  All selected characters will be scaled (scale factors are in percent)
  - with one argument they will be scaled uniformly about the character's center point
  - with two arguments the first specifies the scale factor for x, the second for y. Again scaling will be about the center point
  - with three arguments they will be scaled uniformly about the specified center
  - with four arguments they will be scaled differently about the specified center
Skew(angle[,ox,oy])
  All selected characters will be skewed by the given angle.
Move(delta-x,delta-y)
  All selected characters will have their points moved the given amount.
ScaleToEm(em-size)
ScaleToEm(ascent,descent)
  Change the font's ascent and descent and scale everything in the font to be in the same proportion to the new em (which is the sum of ascent and descent) value that it was to the old value.
NonLinearTransform(x-expression,y-expression)
  Takes two string arguments which must contain valid expressions of x and y and transforms all selected characters using those expressions.

  >     <e0> := "x" | "y" | "-" <e0> | "!" <e0> | "(" <expr> ")" |
  >     	"sin" "(" <expr> ")" | "cos" "(" <expr> ")" | "tan" "(" <expr> ")" |
  >     	"log" "(" <expr> ")" | "exp" "(" <expr> ")" | "sqrt" "(" <expr> ")" |
  >     	"abs" "(" <expr> ")" |
  >     	"rint" "(" <expr> ")" | "float" "(" <expr> ")" | "ceil" "(" <expr> ")"
  >     <e1> := <e0> "^" <e1>
  >     <e2> := <e1> "*" <e2> | <e1> "/" <e2> | <e1> "%" <e2>
  >     <e3> := <e2> "+" <e3> | <e2> "-" <e3>
  >     <e4> := <e3> "==" <e4> | <e3> "!=" <e4> |
  >     	<e3> ">=" <e4> | <e3> ">" <e4> |
  >     	<e3> "<=" <e4> | <e3> "<" <e4>
  >     <e5> := <e4> "&&" <e5> | <e4> "||" <e5>
  >     <expr> := <e5> "?" <expr> ":"

  Example: To do a perspecitive transformation with a vanishing point at (200,300):

  >     NonLinearTrans("200+(x-200)*abs(y-300)/300","y")

  This command is not available in the default build, you must modify the file `configure-pfaedit.h` and then rebuild PfaEdit.

ExpandStroke(width)
ExpandStroke(width,line cap, line join)
ExpandStroke(width,line cap, line join,0,Kanou's removeinternal /external flag)
ExpandStroke(width,caligraphic-angle,height-numerator,height-denom)
  In the first format a line cap of "butt" and line join of "round" are implied.
  A value of 1 for remove internal/external will remove the internal contour, a value of 2 will remove the external contour.
Outline(width)
  Strokes all selected characters with a stroke of the specified width (internal to the characters). The bounding box of the character will not change. In other words it produces what the mac calls the "Outline Style".
Inline(width,gap)
  Produces an outline as above, and then shrinks the character so that it fits inside the outline. In other words, it produces an inlined character.
Shadow(angle,outline-width,shadow-width)
  Converts the selected characters into shadowed versions of themselves.
Wireframe(angle,outline-width,shadow-width)
  Converts the selected characters into wireframed versions of themselves.
RemoveOverlap()
  Does the obvious.
OverlapIntersect()
  Removes everything but the intersection.
FindIntersections()
  Finds everywhere that splines cross and creates points there.
Simplify()
Simplify(flags,error[,tan_bounds[,bump_size]])
  With no arguments it does the obvious. If flags is -1 it does a Cleanup, otherwise flags should be a bitwise or of
  - 1 -- Slopes may change at the end points.
  - 2 -- Points which are extremum may be removed
  - 4 -- Corner points may be smoothed into curves
  - 8 -- Smoothed points should be snapped to a horizontal or vertical tangent if they are close
  - 16 -- Remove bumps from lines

  The error argument is the number of pixels by which the modified path is allowed to stray from the true path.
  The tan_bounds argument specifies the angle between the curves at which smoothing will stop
  And bump_size gives the maximum distance a bump can move from the line and still be smoothed out.

AddExtrema()
RoundToInt()
AutoTrace()
CorrectDirection([unlinkrefs])
  If the an argument is present it must be integral and is treated as a flag controlling whether flipped references should be unlinked before the CorrectDirection code runs. If the argument is not present, or if it has a non-zero value then flipped references will be unlinked.
DefaultATT(tag)
  For all selected characters make a guess as to what might be an appropriate value for the given tag. If the tag is "*" then PfaEdit will apply guesses for all features it can.
AddATT(type,script-lang,tag,flags,variant)
AddATT("Position",script-lang,tag,flags,xoff,yoff,h_adv_off,v_adv_off)
AddATT("Pair",script-lang,tag,flags,name,xoff,yoff,h_adv_off,v_adv_off,xoff2,yoff2,h_adv_off2,v_adv_off2)
  Allows you to add an Advanced Typography feature to a single selected character. The first argument may be either: Position, Pair, Substitution, AltSubs, MultSubs or Ligature. The second argument should be a script-lang list where each 4-character script name is followed by a comma seperated list of 4 character language names (with the languages enclosed in curly braces). As:
  `grek{dflt} latn{dflt,VIT ,ROM }`
  The third arg should be a 4 character opentype feature tag. The fourth argument should be the otf flags (or -1 to make PfaEdit guess appropriate flags). The remaining argument(s) vary depending on the value of the first (type) argument. For Position tags there are 4 integral arguments which specify how this feature modifies the metrics of this character. For Pair type the next argument is the name of the other character in the pair followed by 8 integral arguments, the first 4 specify the changes in positioning to the first character, the next four the changes for the second char. For substitution tags the fifth argument is the name of another glyph which will replace the current one. For an AltSubs tag the argument is a space seperated list of glyph names any of which will replace the current one. For a MultSubs the argument is a space seperated list of names all of which will replace the current one. For a Ligature the argument is a space seperated list of glyph names all of which will be replaced by the current glyph.
RemoveATT(type,script-lang,tag)
  Removes any feature tags which match the arguments (which are essentially the same as above, except that any of them may be "*" which will match anything).
BuildComposit()
BuildAccented()
MergeFonts(other-font-name[,flags])
  Loads other-font-name, and extracts any characters from it which are not in the current font and moves them to the current font. The flags argument is the same as that for Open. Currently the only relevant flag is to say that you do have a lisence to use a font with fstype=2.

AutoHint()
AutoInstr()
ClearHints()
ClearPrivateEntry(key)
  Removes the entry indexed by the given key from the private dictionary of the font.
ChangePrivateEntry(key,val)
  Changes (or adds if the key is not already present) the value in the dictionary indexed by key. (all values must be strings even if they represent numbers in PostScript)
GetPrivateEntry(key)
  Returns the entry indexed by key in the private dictionary. All return values will be strings. If an entry does not exist a null string is returned.
SetWidth(width[,relative])
  If the second argument is absent or zero then the width will be set to the first argument, if the second argument is 1 then the width will be incremented by the first, and if the argument is 2 then the width will be scaled by <first argument>/100.0 .
SetVWidth(vertical-width[,relative])
  If the second argument is absent or zero then the vertical width will be set to the first argument, if the second argument is 1 then the vertical width will be incremented by the first, and if the argument is 2 then the vertical width will be scaled by <first argument>/100.0 .
SetLBearing(lbearing[,relative])
  If the second argument is absent or zero then the left bearing will be set to the first argument, if the second argument is 1 then the left bearing will be incremented by the first, and if the argument is 2 then the left bearing will be scaled by <first argument>/100.0 .
SetRBearing(rbearing[,relative])
  If the second argument is absent or zero then the right bearing will be set to the first argument, if the second argument is 1 then the right bearing will be incremented by the first, and if the argument is 2 then the right bearing will be scaled by <first argument>/100.0 .
CenterInWidth()
AutoWidth(spacing)
  Guesses at the widths of all selected characters so that two adjacent "I" characters will appear to be spacing em-units apart. (if spacing is the negative of the em-size (sum of ascent and descent) then a default value will be used).
AutoKern(spacing,threshold[,kernfile])
  (AutoKern doesn't work well in general)
  Guesses at kerning pairs by looking at all selected characters, or if a kernfile is specified, PfaEdit will read the kern pairs out of the file.
SetKern(ch2,offset)
  Sets the kern between any selected characters and the character ch2 to be offset. The first argument may be specified as in Select(), the second is an integer representing the kern offset.
RemoveAllKerns()
  Removes all kern pairs and classes from the current font.
SetVKern(ch2,offset)
  Sets the kern between any selected characters and the character ch2 to be offset. The first argument may be specified as in Select(), the second is an integer representing the kern offset.
VKernFromHKern()
  Removes all vertical kern pairs and classes from the current font, and then generates new vertical kerning pairs by copying the horizontal kerning data for a pair of characters to the vertically rotated versions of those characters.
RemoveAllVKerns()
  Removes all vertical kern pairs and classes from the current font.

CIDChangeSubFont(new-sub-font-name)
  If the current font is a cid keyed font, this command changes the active sub-font to be the one specified (the string should be the postscript FontName of the subfont)
CIDSetFontNames(fontname[,family[,fullname[,weight[,copyright-notice]]]])
  Sets various postscript names associated with the top level cid font. If a name is omitted (or is the empty string) it will not be changed. (this is just like SetFontNames except it works on the top level cid font rather than the current font).
CIDFlattenByCMap(cmap-filename)
ConvertToCID(registry, ordering, supplement)
  Converts current font to a CID-keyed font using given registry, ordering and supplement. registry and ordering must be strings, supplenmet must be a integer.
ConvertByCMap(cmapfilename)
  Converts curernt font to a CID-keyed font using specified CMap file. cmapfilename must be a path name of a file conforming Adobe CMap File Format.

CharCnt()
  Returns the number of characters in the current font
InFont(arg)
  Returns whether the argument is in the font. The argument may be an integer in which case true is returned if the value is >= 0 and < total number of characters in the font. Otherwise if the argument is a unicode code point or a postscript character name, true is returned if that character is in the font.
WorthOutputting(arg)
  Arg is as above. This returns true if the character contains any splines, references or has had its width set.
CharInfo(str)
CharInfo("Kern",character-spec)
CharInfo("VKern",character-spec)
CharInfo(str,script,lang,tag)
  There must be exactly one character selected in the font, and this returns information on it. The information returned depends on str with the obvious meanings:
  - "Name" returns the character's name
  - "Unicode" returns the character's unicode encoding
  - "Encoding" returns the character's encoding in the current font
  - "Width" returns the character's width
  - "VWidth" returns the character's Vertical width
  - "LBearing" returns the character's left side bearing
  - "RBearing" returns the character's right side bearing
  - "BBox" returns a 4 element array containing [minimum-x-value, minimum-y-value, maximum-x-value, maximum-y-value] of the character.
  - "Kern" (there must be a second argument here which specifies another character as in Select()) Returns the kern offset between the two characters (or 0 if none).
  - "VKern" (there must be a second argument here which specifies another character as in Select()) Returns the vertical kern offset between the two characters (or 0 if none).
  - "Color" returns the character's color as a 24bit rgb value (or -2 if no color has been assigned to the character).
  - "Comment" returns the character's comment (it will be converted from unicode into the default encoding).
  - "Changed" returns whether the character has been changed since the last save or load.
  - "Position" takes three additional arguments, a script, a language and a tag (all 4 character strings) and returns whether the character has a Position alternate with that tag.
  - "Pair" takes three additional arguments, a script, a language and a tag (all 4 character strings) and returns whether the character has a Pairwise positioning alternate with that tag.
  - "Substitution" takes three additional arguments, a script, a language and a tag (all 4 character strings) and returns the name of the Simple Substitution alternate with that tag (or a null string if there is none).
  - "AltSubs" takes three additional arguments, a script, a language and a tag (all 4 character strings) and returns a space seperated list of the names of all alternate substitutions with that tag (or a null string if there is none).
  - "MultSubs" takes three additional arguments, a script, a language and a tag (all 4 character strings) and returns a space seperated list of all the names of all glyphs this glyph gets decomposed into with that tag (or a null string if there is none).
  - "Ligature" takes three additional arguments, a script, a language and a tag (all 4 character strings) and returns a space seperated list of the names of all components with that tag (or a null string if there is none).
  - "GlyphIndex" returns the index of the current glyph in the ttf 'glyf' table, or -1 if it has been created since. This value may change when a truetype/opentype font is generated (to the index in the generated font).

  Examples:

  >     Select("A")
  >     lbearing = CharInfo("LBearing")
  >     kern = CharInfo("Kern","O")
  >     Select(0u410)
  >     SetLBearing(lbearing)
  >     SetKern(0u41e,kern)
  >     Select("a")
  >     verta = CharInfo("Substitution","*","dflt","vrt2")

## Examples

- PfaEdit's testsuite (such as it is)
- Directory of donated scripts
- Scripts used in other projects
  - x-symbol

### Example 1:

>     #Set the color of all selected characters to be yellow
>     #designed to be run within an interactive pfaedit session.
>     foreach
>       SetCharColor(0xffff00)
>     endloop

### Example 2:

>     #!/usr/local/bin/pfaedit
>     #Take a Latin font and apply some simple transformations to it
>     #prior to adding cyrillic letters.
>     #can be run in a non-interactive pfaedit session.
>     Open($1);
>     Reencode("KOI8-R");
>     Select(0xa0,0xff);
>     //Copy those things which look just like latin
>     BuildComposit();
>     BuildAccented();

>     //Handle Ya which looks like a backwards "R"
>     Select("R");
>     Copy();
>     Select("afii10049");
>     Paste();
>     HFlip();
>     CorrectDirection();
>     Copy();
>     Select(0u044f);
>     Paste();
>     CopyFgToBg();
>     Clear();

>     //Gamma looks like an upside-down L
>     Select("L");
>     Copy();
>     Select(0u0413);
>     Paste();
>     VFlip();
>     CorrectDirection();
>     Copy();
>     Select(0u0433);
>     Paste();
>     CopyFgToBg();
>     Clear();

>     //Prepare for editing small caps K, etc.
>     Select("K");
>     Copy();
>     Select(0u043a);
>     Paste();
>     CopyFgToBg();
>     Clear();

>     Select("H");
>     Copy();
>     Select(0u043d);
>     Paste();
>     CopyFgToBg();
>     Clear();

>     Select("T");
>     Copy();
>     Select(0u0442);
>     Paste();
>     CopyFgToBg();
>     Clear();

>     Select("B");
>     Copy();
>     Select(0u0432);
>     Paste();
>     CopyFgToBg();
>     Clear();

>     Select("M");
>     Copy();
>     Select(0u043C);
>     Paste();
>     CopyFgToBg();
>     Clear();

>     Save($1:r+"-koi8-r.sfd");
>     Quit(0);

## The Execute Script dialog

This dialog allows you to type a script directly in to PfaEdit and then run it. Of course the most common case is that you'll have a script file somewhere that you want to execute, so there's a button [Call] down at the bottom of the dlg. Pressing [Call] will bring up a file picker dlg looking for files with the extension *.pe (you can change that by typing a wildcard sequence and pressing the [Filter] button). After you have selected your scipt the appropriate text to text to invoke it will be placed in the text area.

The current font of the script will be set to whatever font you invoked it from.

## The Scripts Menu

You can use the preference dialog to create a list of frequently used scripts. Invoke File->Preferences and select the Scripts tag. In this dialog are ten possible entries, each one should have a name (to be displayed in the menu) and an associated script file to be run.

After you have set up your preferences you can invoke scripts from the font view, either directly from the menu (File->Scripts-><your name>) or by a hot key. The first script you added will be invoked by Cnt-Alt-1, then second by Cnt-Alt-2, and the tenth by Cnt-Alt-0.

The current font of the script will be set to whatever font you invoked it from.

-- Prev -- TOC -- Next --