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:
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
  - [[#maintainers][Maintainers]]
  - [[#module-flags][Module flags]]
  - [[#packages][Packages]]
  - [[#hacks][Hacks]]
  - [[#changelog][Changelog]]
- [[#installation][Installation]]
- [[#usage][Usage]]
  - [[#mathematical-symbols-replacement][Mathematical symbols replacement]]
  - [[#coding-ligatures][Coding ligatures]]
    - [[#details][Details]]
- [[#configuration][Configuration]]
  - [[#symbol-replacements-λ-for-lambda][Symbol replacements (λ for "lambda"...)]]
  - [[#font-ligatures-turning--into-an-arrow][Font ligatures (turning "=>" into an arrow...)]]
    - [[#setting-ligatures-for-specific-font-or-major-mode][Setting ligatures for specific font or major mode]]
    - [[#overwriting-all-default-ligatures][Overwriting all default ligatures]]
- [[#troubleshooting][Troubleshooting]]
  - [[#some-symbols-are-not-rendering-correctly][Some symbols are not rendering correctly]]
- [[#frequently-asked-questions][Frequently asked questions]]
- [[#appendix][Appendix]]

** Maintainers
- [[doom-user:][@gagbo]]

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +extra ::
  Enables extra symbol substitutions in certain modes, for example ~lambda~ in
  lisps are replaced with ~λ~.

** Packages
- [[https://github.com/mickeynp/ligature.el][ligature.el]] (on Emacs 28+ with Harfbuzz)

** 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.

  /This module does not have specific installation instructions/

  ~doom doctor~ will tell you if the module is incompatible with your current
  Emacs version, and what you can do to remediate.

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

** Mathematical symbols replacement
If you want to set symbol replacements for modules that don't have them by
default you can use the ~set-ligatures!~ function in your config.el file
#+BEGIN_SRC emacs-lisp
(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" :yield "yield"))
#+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 keyword"
    :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"
    :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


** Coding ligatures
This module includes configuration to compose combinations like =->= or =::=
into prettier glyphs (called a ligature), specific for your font, or specific
for the major modes that you want to use.

As these ligatures come from the font itself instead of elisp symbols, we use
=set-font-ligatures!=

#+begin_src elisp
(set-font-ligatures! '(haskell-mode clojure-mode) ">>=" ">>-")
#+end_src

*** Details
Ligatures are implemented using a **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 same method natively 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 uses the [[https://github.com/mickeynp/ligature.el][ligature.el]] package that
implements this method for Emacs 28+ built with Harfbuzz support. Therefore, the
module will not work with Emacs 27 or previous.

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 the /composition-function-table/ method in
Emacs 27.

* Configuration
** Symbol replacements (λ for "lambda"...)
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          ""
  :dot           "•")  ;; you could also add your own if you want
#+end_src

** Font ligatures (turning "=>" into an arrow...)
*** Setting ligatures for specific font or major mode
As the [[https://github.com/mickeynp/ligature.el][README]] for ligature.el states, you can manipulate the ligatures that you
want to enable, specific for your font, or specific for the major modes that you
want to use. =set-font-ligatures!= is a thin wrapper around =ligature.el= to control these.

#+begin_src elisp
(set-font-ligatures! '(haskell-mode clojure-mode) ">>=" ">>-")
#+end_src

This call will:
- overwrite all preceding calls to =set-font-ligatures!=
  for =haskell-mode= and =clojure-mode= specifically, but
- keep the inheritance to ligatures set for all modes, or parent modes like =prog-mode=

*** Overwriting all default ligatures
If you want to "start from scratch" and get control over all ligatures that
happen in all modes, you can use

#+begin_src elisp
;; Set all your custom ligatures for all prog-modes here.
;; This section is *out of* the after! block.
;; Example: only get ligatures for "==" and "===" in programming modes by
;; default, and get only "www" in all buffers by default.
(set-font-ligatures! 'prog-mode :append "==" "===")
(set-font-ligatures! 't :append "www")
;; Set any of those variables to nil to wipe all defaults.

;; Set all your additional custom ligatures for other major modes here.
;; Example: enable traditional ligature support in eww-mode, if the
;; `variable-pitch' face supports it
(set-font-ligatures! 'eww-mode "ff" "fi" "ffi")
#+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:

- Set [[var:doom-symbol-font]].
- Disable the [[doom-module::ui unicode]] module. It overrides [[var:doom-symbol-font]]
  and 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