doomemacs/modules/ui/ligatures/README.org

#+title:    :ui ligatures
#+subtitle: Distract folks from your code
#+created:  June 16, 2018
#+since:    21.12.0

* Description :unfold:
This module enables ligatures and arbitrary symbol substitutions with
~mac-auto-operator-composition-mode~ (on supported macOS systems) or composition
tables (harfbuzz on Emacs 28), falling back on ~prettify-symbols-mode~
otherwise.

** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +extra ::
  Enables extra symbol substitutions in certain modes, for example ~lambda~ in
  lisps are replaced with ~λ~.
- +fira ::
  Enable =Fira Code= ligatures. This requires Fira Code Symbol and [[id:a7e7402b-e202-4860-878b-d1933cff1d16][a patched
  version of Fira Code]].
- +hasklig ::
  Enable =Hasklig= ligatures. This requires [[id:a7e7402b-e202-4860-878b-d1933cff1d16][a patched version of the HaskLig
  font]].
- +iosevka ::
  Enable =Iosevka= ligatures. This requires [[id:a7e7402b-e202-4860-878b-d1933cff1d16][a patched version of the Iosevka
  font]].
- +pragmata-pro ::
  Enable =Pragmata Pro= ligatures. This requires the [[https://www.fsd.it/shop/fonts/pragmatapro/][Pragmata Pro font]].

#+begin_quote
 🚧 Font flags are ignored _if_ you're sporting either a) Emacs 28+ with
    Harfbuzz support (which can compose ligatures natively), or b) Mitsuharu's
    =emacs-mac= build on macOS (which uses
    ~mac-auto-operator-composition-mode~).
#+end_quote

** Packages
/This module doesn't install any packages./

** Hacks
/No hacks documented for this module./

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module requires one of three setups for ligatures to work:

- A recent enough version of Emacs which will compose ligatures automatically
  (Emacs 28 with Harfbuzz support), or
- Mitsuharu's =emacs-mac= build on macOS (available on Homebrew), or
- A patched font for Doom's fallback ligature support.

** Mutsuharu's emacs-mac port or Emacs 28+ with Harfbuzz support
Ligatures should be handled without any additional configuration.

** Not Emacs-mac and Emacs <= 27
:PROPERTIES:
:ID:       a7e7402b-e202-4860-878b-d1933cff1d16
:END:
1. Enable one of the four ligature font flags: =+fira=, =+hasklig=, =+iosevka=
   or =+pragmata-pro=.
2. Install the patched version of the associated font with ~M-x
   +ligatures/install-patched-font~. Note: Pragmata Pro cannot be installed this
   way because it is a non-free font and must be purchased and installed
   manually.

* TODO Usage
#+begin_quote
 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** TODO Mathematical symbols replacement

** Coding ligatures
This module includes configuration to compose combinations like =->= or =::=
into prettier glyphs (called a ligature). Depending on the current version of
emacs, this is implemented in two different ways :

- prettify-symbols-mode method :: this is the "legacy" method. It uses a font
  which haves the ligatures as separate unicode symbols, and using
  prettify-symbols-mode, =->=-like combinations are manually listed and replaced
  with the correct symbol. The mapping between =->=-like sequences and unicode
  values in the font are font-specific ; therefore [[doom-module:][+fira]], [[doom-module:][+iosevka]]... files and
  specific fonts are necessary for it to work.
- composition-function-table method :: regexps are used to match all the usual
  sequences which are composed into ligatures. These regexps are passed to emacs
  directly, which asks Harfbuzz to shape it. Ligatures are obtained
  automatically depending on the capabilities of the font, and no font-specific
  configuration is necessary.

Emacs-mac port implements the /composition-function-table/ method in [[https://bitbucket.org/mituharu/emacs-mac/src/26c8fd9920db9d34ae8f78bceaec714230824dac/lisp/term/mac-win.el?at=master#lines-345:805][its code]],
nothing is necessary on Doom side; otherwise, Doom implements the
/composition-function-table/ for emacs 28+ built with Harfbuzz support, and the
/prettify-symbols-mode/ method otherwise.

Even though harfbuzz has been included in emacs 27, there is currently a [[https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-04/msg01121.html][bug
(#40864)]] which prevents a safe usage of /composition-function-table/ method in
emacs 27.

* TODO Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** Setting ligatures
If you want to set ligatures for modules that don't have them by default you can
use the ~set-ligatures!~ macro:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! PACKAGE
  (set-ligatures! 'MAJOR-MODE
    :symbol "keyword"))
#+end_src

E.g.
#+begin_src emacs-lisp
(after! go-mode ; in this case the major mode and package named the same thing
  (set-ligatures! 'go-mode
    :def "func" ; function keyword
    :true "true" :false "false"
    ; this will replace not only definitions
    ; but coresponding functions aswell
    :int "int" :str "string"
    :float "float" :bool "bool"
    :for "for"
    :return "return" :yeild "yeild"))
#+end_src

You can set these symbols out of the box:
#+begin_src emacs-lisp
(set-ligatures! 'MAJOR-MODE
    ;; Functional
    :lambda        "lambda keyword"
    :def           "function keyword"
    :composition   "composition"
    :map           "map/dictionary keyword"
    ;; Types
    :null          "null type"
    :true          "true keyword"
    :false         "false keyword"
    :int           "int keyword"
    :float         "float keyword"
    :str           "string keyword"
    :bool          "boolean keywork"
    :list          "list keyword"
    ;; Flow
    :not           "not operator"
    :in            "in operator"
    :not-in        "not in operator"
    :and           "and keyword"
    :or            "or keyword"
    :for           "for keyword"
    :some          "some keyword"
    :return        "return"
    :yield         "yeild"
    ;; Other
    :union         "Union keyword"
    :intersect     "Intersect keyword"
    :diff          "diff keyword"
    :tuple         "Tuple Keyword "
    :pipe          "Pipe Keyword" ;; FIXME: find a non-private char
    :dot           "Dot operator")
#+end_src

If you have multiple versions of the same keyword you can set the symbol twice:
#+begin_src emacs-lisp
(set-ligatures! scala-mode
  :null "none"
  :null "None")
#+end_src

** Changing ligatures
if you don't like the symbols chosen you can change them by using:
#+begin_src emacs-lisp
;; you don't need to include all of them you can pick and mix
(plist-put! +ligatures-extra-symbols
  ;; org
  :name          "»"
  :src_block     "»"
  :src_block_end "«"
  :quote         "“"
  :quote_end     "”"
  ;; Functional
  :lambda        "λ"
  :def           "ƒ"
  :composition   "∘"
  :map           "↦"
  ;; Types
  :null          "∅"
  :true          "𝕋"
  :false         "𝔽"
  :int           "ℤ"
  :float         "ℝ"
  :str           "𝕊"
  :bool          "𝔹"
  :list          "𝕃"
  ;; Flow
  :not           "￢"
  :in            "∈"
  :not-in        "∉"
  :and           "∧"
  :or            "∨"
  :for           "∀"
  :some          "∃"
  :return        "⟼"
  :yield         "⟻"
  ;; Other
  :union         "⋃"
  :intersect     "∩"
  :diff          "∖"
  :tuple         "⨂"
  :pipe          "" ;; FIXME: find a non-private char
  :dot           "•")  ;; you could also add your own if you want
#+end_src

* Troubleshooting
[[doom-report:][Report an issue?]]

** Some symbols are not rendering correctly
This can usually be fixed by doing one of the following:

- Make sure Symbola (the font) is installed on your system.
- Otherwise, change [[var:][doom-unicode-font]] (set to Symbola by default).
- Disable the [[doom-module:][:ui unicode]] module. It not only overrides [[var:][doom-unicode-font]], but
  should only be used as a last resort.

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote