Saucexages v0.2.0 Saucexages.Font View Source
Module used for working with font data embedded into certain SAUCE types.
The primary use-cases of this module are to help with building interfaces, displaying SAUCE file data, and to help with analysis of SAUCE data.
A more specific common-use case for instance is a viewer app may wish to know how to display a particular piece of ANSi or ASCII art. One of the primary purposes of SAUCE was to facilitate such a case by conveying the author’s intentions. For example, spacing or pixel properties may look incorrect on many settings, or the character set used may be off-putting using the OS or user default.
Working with Fonts
SAUCE embeds various information via the presence of a font name, for example “IBM VGA”. This name correlates to a number of combinations of settings depending on the viewer’s preference and capabilities. Interpreting this information prevents incorrect display and helps viewers more closely match the original intention. This information can be used to upgrade, transition and/or adapt media display accordingly (ex: fallback fonts). Another use for this information is to do things such as answer questions - ex: “How much of this artwork was intended for Amiga fonts?” or “Which ANSI artwork do I own that I should not display in the common cp437 encoding?”
Why Decode Fonts
Most SAUCE libraries simply choose to return just the font name. Saucexages instead chooses to allow API consumers to get more info about the encoded information, rather than to yet again defer to another library or force the consumer to re-implement the SAUCE spec. In other words, the intention is to provide a single abstraction that is data-driven which programmers can leverage to “get things done.”
In real-world terms, the neglect of font information and other metadata has lead to buggy viewers, inconsistent experiences, and outright failures handling media. Although many files in the wild lack the proper font information regardless, it is surprisingly easy to re-write this information and correct these mistakes. For example, many major art groups relied on IBM VGA-based fonts. Ascii groups by contrast often also used Amiga fonts. Even when this information cannot be inferred per-group, many authors have actually written their display preferences inside the art itself. With some patience and time, Saucexages can be used to fix artwork so it displays properly.
Simply put, Saucexages gives you the tools you need to fix your artwork and display it right instead of making it someone else’s job who doesn’t’ exist.
Link to this section Summary
Functions
Lists all the default font ids as supported by the SAUCE standard
Lists all the default font names as supported by the SAUCE standard
Lists all the default fonts, with their font info as supported by the SAUCE standard
Returns the corresponding encoding for a given encoding id
Returns the corresponding encoding name for a given encoding id
Returns the font_id corresponding to the given font_name
Returns the full font info for a given font_id or font_name
Returns the font name that corresponds to the given font id
Returns the font option for the given font_id and font_size. Each font id should have 0 to one font option for a given size
Lists all the possible font options according to the SAUCE standard
Returns the font options for the given font_id. Each font id may have one or more options
Generates a full list of Font Info based on all fonts that support multiple encodings
Generates a full list of Font Options based on all fonts that support multiple encodings
Generates a list of Font Info based on a set of encodings and a font name
Generates a list of Font Options based on a set of encodings and a font name
Builds a font option name for the given font option
Builds a font option name for the given font information
Returns the SAUCE font for the given font_id and specified size
Creates a list of valid fonts for use with SAUCE that have full font information, including display properties
Returns a list of SAUCE fonts for the given font_id
Lists all encoding ids supported by the SAUCE standard
Lists all encoding names supported by the SAUCE standard
Lists all encodings supported by the SAUCE standard
Link to this section Types
Link to this section Functions
Lists all the default font ids as supported by the SAUCE standard.
Lists all the default font names as supported by the SAUCE standard.
These names are each valid values within a sauce record for any record that has a corresponding mapping to FontName for t_info_s. For instance, these values may appear in the t_info_s for any file with its sauce record set to :ansi in the data_type_id field.
Lists all the default fonts, with their font info as supported by the SAUCE standard.
encoding(encoding_id()) :: Saucexages.FontEncoding.t()
Returns the corresponding encoding for a given encoding id.
Examples
iex> Saucexages.Font.encoding(:cp437)
%Saucexages.FontEncoding{
encoding_id: :cp437,
encoding_name: "437",
friendly_name: "MS-DOS Latin US"
}encoding_name(encoding_id()) :: String.t()
Returns the corresponding encoding name for a given encoding id.
Examples
iex> Saucexages.Font.encoding_name(:cp437)
"437"Returns the font_id corresponding to the given font_name.
Useful for translating SAUCE record font names found t_info_s fields into font ids.
Examples
iex> Saucexages.Font.font_id("Amiga Topaz 1")
:amiga_topaz_1
iex> Saucexages.Font.font_id("IBM VGA")
:ibm_vgaReturns the full font info for a given font_id or font_name.
Examples
iex> Saucexages.Font.font_info(:ibm_vga)
%Saucexages.FontInfo{
encoding_id: :cp437,
font_id: :ibm_vga,
font_name: "IBM VGA"
}Returns the font name that corresponds to the given font id.
Examples
iex> Saucexages.Font.font_name(:amiga_topaz_1)
"Amiga Topaz 1"
iex> Saucexages.Font.font_name(:ibm_vga)
"IBM VGA"Returns the font option for the given font_id and font_size. Each font id should have 0 to one font option for a given size.
Examples
iex> Saucexages.Font.font_option_for(:ibm_vga, {9, 16})
%Saucexages.FontOption{
font_id: :ibm_vga,
properties: %Saucexages.FontProperties{
display: {4, 3},
font_size: {9, 16},
pixel_ratio: {20, 27},
resolution: {720, 400},
vertical_stretch: 35.0
}
}Lists all the possible font options according to the SAUCE standard.
font_options(font_id()) :: [Saucexages.FontOption.t()]
Returns the font options for the given font_id. Each font id may have one or more options
Examples
iex> Saucexages.Font.font_options(:ibm_vga)
[
%Saucexages.FontOption{
font_id: :ibm_vga,
properties: %Saucexages.FontProperties {
display: {4, 3},
font_size: {9, 16},
pixel_ratio: {20, 27},
resolution: {720, 400},
vertical_stretch: 35.0
}
},
%Saucexages.FontOption{
font_id: :ibm_vga,
properties: %Saucexages.FontProperties{
display: {4, 3},
font_size: {8, 16},
pixel_ratio: {6, 5},
resolution: {640, 400},
vertical_stretch: 20.0
}
}
]generate_all_font_info_groups([Saucexages.FontEncoding.t()]) :: [ Saucexages.FontInfo.t() ]
Generates a full list of Font Info based on all fonts that support multiple encodings.
This scheme is used in the SAUCE standard commonly in the form of FONT NAME ### where FONT_NAME corresponds to a font name, ex: IBM VGA 50 and ### corresponds to an encoding name, ex: 437.
generate_all_font_option_groups([Saucexages.FontEncoding.t()]) :: [ Saucexages.FontOption.t() ]
Generates a full list of Font Options based on all fonts that support multiple encodings.
This scheme is used in the SAUCE standard commonly in the form of FONT NAME ### where FONT_NAME corresponds to a font name, ex: IBM VGA 50 and ### corresponds to an encoding name, ex: 437.
generate_font_info_group(font_id(), [Saucexages.FontEncoding.t()]) :: [Saucexages.FontInfo.t()] | []
Generates a list of Font Info based on a set of encodings and a font name.
This scheme is used in the SAUCE standard commonly in the form of FONT NAME ### where FONT_NAME corresponds to a font name, ex: IBM VGA 50 and ### corresponds to an encoding name, ex: 437.
generate_font_option_group(font_id(), [Saucexages.FontEncoding.t()]) :: [Saucexages.FontOption.t()] | []
Generates a list of Font Options based on a set of encodings and a font name.
This scheme is used in the SAUCE standard commonly in the form of FONT NAME ### where FONT_NAME corresponds to a font name, ex: IBM VGA 50 and ### corresponds to an encoding name, ex: 437.
option_name(Saucexages.FontOption.t()) :: String.t()
Builds a font option name for the given font option.
Useful for interface building, logging, and labeling.
Examples
iex> Saucexages.Font.option_name(:ibm_vga, 9, 16)
"IBM VGA 9x16"option_name(font_id(), pos_integer(), pos_integer()) :: String.t()
Builds a font option name for the given font information.
Useful for interface building, logging, and labeling.
Returns the SAUCE font for the given font_id and specified size.
Examples
iex> Saucexages.Font.sauce_font_for(:ibm_vga, {9, 16})
%Saucexages.SauceFont{
display: {4, 3},
encoding_id: :cp437,
font_id: :ibm_vga,
font_name: "IBM VGA",
font_size: {9, 16},
pixel_ratio: {20, 27},
resolution: {720, 400},
vertical_stretch: 35.0
}Creates a list of valid fonts for use with SAUCE that have full font information, including display properties.
sauce_fonts(font_id()) :: [Saucexages.SauceFont.t()]
Returns a list of SAUCE fonts for the given font_id.
Examples
iex> Saucexages.Font.sauce_fonts(:ibm_vga)
[
%Saucexages.SauceFont{
display: {4, 3},
encoding_id: :cp437,
font_id: :ibm_vga,
font_name: "IBM VGA",
font_size: {9, 16},
pixel_ratio: {20, 27},
resolution: {720, 400},
vertical_stretch: 35.0
},
%Saucexages.SauceFont{
display: {4, 3},
encoding_id: :cp437,
font_id: :ibm_vga,
font_name: "IBM VGA",
font_size: {8, 16},
pixel_ratio: {6, 5},
resolution: {640, 400},
vertical_stretch: 20.0
}
]supported_encoding_ids() :: [encoding_id()]
Lists all encoding ids supported by the SAUCE standard.
supported_encoding_names() :: [String.t()]
Lists all encoding names supported by the SAUCE standard.
supported_encodings() :: [Saucexages.FontEncoding.t()]
Lists all encodings supported by the SAUCE standard.