NAME

Font::GlyphNames - Convert between glyph names and characters

VERSION

Version 1.00000

SYNOPSIS

  use Font::GlyphNames qw[
                           name2str
                           name2ord
                           str2name
                           ord2name
                           ord2ligname
                         ];
  # or:
  use Font::GlyphNames ':all';
  
  name2str     qw[one two three s_t Psi uni00D4];
  name2ord     qw[one two three s_t Psi uni00D4];
  str2name     qw[1 2 3 st Ψ Ô];
  ord2name     qw[49 50 51 115 116 936 212];
  ord2ligname  qw[49 50 51 115 116 936 212];

  # Or you can use the OO interface:
  
  use Font::GlyphNames;
  
  $gn = new Font::GlyphNames; # use default glyph list
  $gn = new Font::GlyphNames 'my-glyphs.txt'; # custom list

  $gn->name2ord(qw[ a slong_slong_i s_t.alt ]);
  # etc.
  

DESCRIPTION

This module uses the Adobe Glyph Naming convention (see "SEE ALSO") for converting between glyph names and characters (or character codes).

METHODS/FUNCTIONS

Except for new (which is only a method), each item listed here is both a function and a method.

new ( LIST )

This class method constructs and returns a new Font::GlyphNames object. If an error occurs, it returns undef (check $@ for the error; note also that new() clobbers any existing value of $@, whether there is an error or not). LIST is a list of files to use as a glyph list. If LIST is omitted, the Zapf Dingbats Glyph List and the Adobe Glyph List (see "SEE ALSO") will be used instead.

new \%options

new can also take a hashref of options, which are as follows:

lists

list

(You can specify it with or without the 's'.) Either the name of the file containing the glyph list, or a reference to an array of file names. In fact, if you want an object with no glyph list (not that you would), you can use lists => [].

search_inc

If this is set to true, 'Font/GlyphNames/' will be added to the beginning of each file name, and the files will then be searched for in the folders listed in @INC.

substitute

Set this to a string that you want name2str to output for each invalid glyph name. The default is undef. (Actually, it doesn't have to be a string; it could be anything, but it will be stringified if name2str is called in scalar context with more than one argument.)

name2str ( LIST )

LIST is a list of glyph names. This function returns a list of the string equivalents of the glyphs in list context. In scalar context the individual elements of the list are concatenated. Invalid glyph names and names beginning with a dot (chr 0x2E) produce undef. Some examples:

  name2str   's_t'             # returns 'st'
  name2str qw/Psi uni00D4/     # returns ("\x{3a8}", "\xd4")
  name2str   '.notdef'         # returns undef
  name2str   'uni12345678'     # returns "\x{1234}\x{5678}"
  name2str qw/one uni32 three/ # returns ('1', undef, '3')

If, for invalid glyph names, you would like something other than undef (the null char, for instance), you can either use the OO interface and the substitute option to "new", or replace it afterwards like this:

  map +("\0",$_)[defined], name2str ...

name2ord ( LIST )

LIST is a list of glyph names. This function returns a list of the character codes that the glyphs represent. If called in scalar context with more than one argument, the behaviour is undefined (and subject to change in future releases). Invalid glyph names and names beginning with a dot (chr 0x2E) produce -1. Some examples:

  name2ord   's_t'             # returns 115, 116
  name2ord qw/Psi uni00D4/     # returns 0x3a8, 0xd4
  name2ord   '.notdef'         # returns -1
  name2ord   'uni12345678'     # returns 0x1234, 0x5678
  name2ord qw/one uni32 three/ # returns 49, -1, 51

str2name ( LIST )

LIST is a list of strings. This function returns a list of glyph names that correspond to all the arguments passed to it. If a string is more than one character long, the resulting glyph name will be a ligature name. An empty string will return '.notdef'. If called in scalar context with more than one argument, the behaviour is undefined (and subject to change in future releases).

  str2name 'st'               # returns   's_t'
  str2name "\x{3a8}", "\xd4"  # returns qw/Psi Ocircumflex/
  str2name "\x{3a8}\xd4"      # returns   'Psi_Ocircumflex'
  str2name "\x{1234}\x{5678}" # returns   'uni12345678'
  str2name "\x{05D3}\x{05B9}" # returns   'daletholam'

ord2name ( LIST )

LIST is a list of character codes. This function returns a list of glyph names that correspond to all the arguments passed to it. If called in scalar context with more than one argument, the behaviour is undefined (and subject to change in future releases).

  ord2name 115            # returns 's'
  ord2name 0x3a8, 0xd4    # returns 'Psi', 'Ocircumflex'
  ord2name 0x1234, 0x5678 # returns 'uni1234', 'uni5678'

ord2ligname ( LIST )

LIST is a list of character codes. This function returns a glyph name for a ligature that corresponds to the arguments passed to it, or '.notdef' if there are none.

  ord2ligname 115, 116       # returns 's_t'
  ord2ligname 0x3a8, 0xd4    # returns 'Psi_Ocircumflex'
  ord2ligname 0x1234, 0x5678 # returns 'uni12345678'
  ord2ligname 0x05D3, 0x05B9 # returns 'daletholam'

THE GLYPH LIST FILE FORMAT

Note: This section is not intended to be normative. It simply describes how this module parses glyph list files--which works with those provided by Adobe.

All lines that consist solely of whitespace or that have a sharp sign (#) preceded only by whitespace (if any) are ignored. All others lines must consist of the glyph name followed by a semicolon, and the character numbers in hex, separated and optionally surrounded by whitespace. If there are multiple character numbers, the glyph is understood to represent a sequence of characters. The line breaks must be either CRLF sequences (as in Adobe's lists) or native line breaks. If a glyph name occurs more than once, the first instance will be used.

COMPATIBILITY

This module requires perl 5.8.0 or later.

BUGS

Please e-mail me if you find any.

AUTHOR & COPYRIGHT

Copyright (C) 2006-8, Father Chrysostomos <name2str qw[s p r o u t at c p a n period o r g]>

SEE ALSO

Unicode and Glyph Names

http://partners.adobe.com/public/developer/opentype/index_glyph.html

Glyph Names and Current Implementations

http://partners.adobe.com/public/developer/opentype/index_glyph2.html

Adobe Glyph List

http://partners.adobe.com/public/developer/en/opentype/glyphlist.txt

ITC Zapf Dingbats Glyph List

http://partners.adobe.com/public/developer/en/opentype/zapfdingbats.txt