# feaLib: Read and write OpenType feature files

## Overview

fontTools’ `feaLib` allows for the creation and parsing of Adobe Font Development Kit for OpenType feature (`.fea`) files. The syntax of these files is described here.

`.fea` files are primarily used for writing human-readable definitions for the OpenType features stored in a font’s `GSUB` and `GPOS` tables.

## Supporting modules

feaLib contains modules for parsing and inspecting `.fea` files as well as utilities for converting `.fea` rules into `GSUB` and `GPOS` tables and inserting them into fonts.

> - parser: Lexing and parsing OpenType feature files
> - ast: Interrogate and generate OpenType feature files

The `fontTools.feaLib.parser.Parser` class can be used to parse files into an abstract syntax tree, and from there the `fontTools.feaLib.builder.Builder` class can add features to an existing font file. You can inspect the parsed syntax tree, walk the tree and do clever things with it, and also generate your own feature files programmatically, by using the classes in the `fontTools.feaLib.ast` module.

## fontTools.feaLib.builder

fontTools.feaLib.builder.addOpenTypeFeatures(font, featurefile, tables=None, debug=False)

  Add features from a file to a font. Note that this replaces any features currently present.

  Parameters:

    - font (feaLib.ttLib.TTFont) – The font object.

    - featurefile – Either a path or file object (in which case we parse it into an AST), or a pre-parsed AST instance.

    - tables – If passed, restrict the set of affected tables to those in the list.

    - debug – Whether to add source debugging information to the font in the `Debg` table

fontTools.feaLib.builder.addOpenTypeFeaturesFromString(font, features, filename=None, tables=None, debug=False)

  Add features from a string to a font. Note that this replaces any features currently present.

  Parameters:

    - font (feaLib.ttLib.TTFont) – The font object.

    - features – A string containing feature code.

    - filename – The directory containing `filename` is used as the root of relative `include()` paths; if `None` is provided, the current directory is assumed.

    - tables – If passed, restrict the set of affected tables to those in the list.

    - debug – Whether to add source debugging information to the font in the `Debg` table

class fontTools.feaLib.builder.Builder(font, featurefile)

  Bases: `object`

  supportedTables = frozenset({'BASE', 'GDEF', 'GPOS', 'GSUB', 'OS/2', 'STAT', 'head', 'hhea', 'name', 'vhea'})
  build(tables=None, debug=False)
  get_chained_lookup_(location, builder_class)
  add_lookup_to_feature_(lookup, feature_name)
  get_lookup_(location, builder_class, mapping=None)
  build_feature_aalt_()
  build_head()
  build_hhea()
  build_vhea()
  get_user_name_id(table)
  buildFeatureParams(tag)
  build_name()
  build_OS_2()
  setElidedFallbackName(value, location)
  addDesignAxis(designAxis, location)
  addAxisValueRecord(axisValueRecord, location)
  build_STAT()
  build_codepages_(pages)
  buildBASE()
  buildBASECoord(c)
  buildBASEAxis(axis)
  buildGDEF()
  buildGDEFGlyphClassDef_()
  buildGDEFMarkAttachClassDef_()
  buildGDEFMarkGlyphSetsDef_()
  buildDebg()
  buildLookups_(tag)
  makeTable(tag)
  makeFeatureVariations(table, table_tag)
  any_feature_variations(feature_tag, table_tag)
  get_lookup_name_(lookup)
  add_language_system(location, script, language)
  get_default_language_systems_()
  start_feature(location, name, use_extension=False)
  end_feature()
  start_lookup_block(location, name, use_extension=False)
  end_lookup_block()
  add_lookup_call(lookup_name)
  set_font_revision(location, revision)
  set_language(location, language, include_default, required)
  getMarkAttachClass_(location, glyphs)
  getMarkFilterSet_(location, glyphs)
  set_lookup_flag(location, value, markAttach, markFilter)
  set_script(location, script)
  find_lookup_builders_(lookups)

    Helper for building chain contextual substitutions

    Given a list of lookup names, finds the LookupBuilder for each name. If an input name is None, it gets mapped to a None LookupBuilder.

  add_attach_points(location, glyphs, contourPoints)
  add_feature_reference(location, featureName)
  add_featureName(tag)
  add_cv_parameter(tag)
  add_to_cv_num_named_params(tag)

    Adds new items to `self.cv_num_named_params_` or increments the count of existing items.

  add_cv_character(character, tag)
  set_base_axis(bases, scripts, vertical, minmax=[])
  set_size_parameters(location, DesignSize, SubfamilyID, RangeStart, RangeEnd)
  add_any_subst_(location, mapping)
  add_single_subst(location, prefix, suffix, mapping, forceChain)
  add_multiple_subst(location, prefix, glyph, suffix, replacements, forceChain=False)
  add_alternate_subst(location, prefix, glyph, suffix, replacement)
  add_ligature_subst(location, prefix, glyphs, suffix, replacement, forceChain)
  add_chain_context_subst(location, prefix, glyphs, suffix, lookups)
  add_single_subst_chained_(location, prefix, suffix, mapping)
  add_multi_subst_chained_(location, prefix, glyph, suffix, replacements)
  add_ligature_subst_chained_(location, prefix, glyphs, suffix, replacement)
  add_reverse_chain_single_subst(location, old_prefix, old_suffix, mapping)
  add_single_pos(location, prefix, suffix, pos, forceChain)
  add_class_pair_pos(location, glyphclass1, value1, glyphclass2, value2)
  add_specific_pair_pos(location, glyph1, value1, glyph2, value2)
  add_cursive_pos(location, glyphclass, entryAnchor, exitAnchor)
  add_mark_base_pos(location, bases, marks)
  add_mark_lig_pos(location, ligatures, components)
  add_mark_mark_pos(location, baseMarks, marks)
  add_chain_context_pos(location, prefix, glyphs, suffix, lookups)
  add_single_pos_chained_(location, prefix, suffix, pos)
  add_marks_(location, lookupBuilder, marks)

    Helper for add_mark_{base,liga,mark}_pos.

  add_subtable_break(location)
  setGlyphClass_(location, glyph, glyphClass)
  add_glyphClassDef(location, baseGlyphs, ligatureGlyphs, markGlyphs, componentGlyphs)
  add_ligatureCaretByIndex_(location, glyphs, carets)
  makeLigCaret(location, caret)
  add_ligatureCaretByPos_(location, glyphs, carets)
  add_name_record(location, nameID, platformID, platEncID, langID, string)
  add_os2_field(key, value)
  add_hhea_field(key, value)
  add_vhea_field(key, value)
  add_conditionset(location, key, value)
  makeVariablePos(location, varscalar)
  makeAnchorPos(varscalar, deviceTable, location)
  makeOpenTypeAnchor(location, anchor)

    ast.Anchor –> otTables.Anchor

  makeOpenTypeValueRecord(location, v, pairPosContext)

    ast.ValueRecord –> otBase.ValueRecord

## fontTools.feaLib.lookupDebugInfo

class fontTools.feaLib.lookupDebugInfo.LookupDebugInfo(location: str, name: str, feature: list)

  Bases: `NamedTuple`

  Information about where a lookup came from, to be embedded in a font

  location: str

    Alias for field number 0

  name: str

    Alias for field number 1

  feature: list

    Alias for field number 2

## fontTools.feaLib.error

exception fontTools.feaLib.error.FeatureLibError(message, location=None)

  Bases: `Exception`

exception fontTools.feaLib.error.IncludedFeaNotFound(message, location=None)

  Bases: `FeatureLibError`