code.delx.au - gnu-emacs-elpa/blob - packages/nameless/README.org

   1 #+OPTIONS: toc:nil num:nil
   2
   3 * Nameless --- /less is more/
   4 *Hide package namespaces in your emacs-lisp code.*
   5
   6 Simply put, turn on this minor mode, and the namespace prefix of the
   7 package you’re editing will be hidden by a ~:~. Here’s a comparison.
   8 The image to the *left* is what you normally see. The image to
   9 the *right* has ~nameless-mode~ turned on.\\
  10  [[file:example-nameless.png]]
  11
  12 ** Usage
  13
  14 To use this package add the following configuration to your Emacs init file.
  15
  16 #+BEGIN_SRC emacs-lisp
  17 (add-hook 'emacs-lisp-mode-hook #'nameless-mode)
  18 #+END_SRC
  19
  20 You can configure a string to use instead of ~:~ by setting the
  21 ~nameless-prefix~, and the name of the face used is ~nameless-face~.
  22 You can even just hide the prefix completely by setting this variable
  23 to an empty string.
  24
  25 While the mode is active, the =C-c C--= key inserts the
  26 package namespace if appropriate.
  27
  28 * Configuration
  29
  30 ** Quickly typing the namespace
  31 ~nameless-mode~ binds the =C-c C--= key to
  32 ~nameless-insert-name~, which immediately inserts the current name for
  33 you, or even expands aliases to the names they point to.
  34
  35 Let’s say you’re in a file called ~foo-bar.el~.
  36 #+BEGIN_SRC text
  37    C-c C-- → foo-bar-
  38 fl C-c C-- → font-lock-
  39 #+END_SRC
  40
  41 There’s also a command called ~nameless-insert-name-or-self-insert~.
  42 You can bind this to the =_= key and make it even faster to
  43 insert the name.
  44 ** Configuring the namespace name
  45 Nameless guesses the package name with the ~lm-get-package-name~
  46 function, but sometimes this might not match the name you want to use.
  47
  48 In these situations, simply set ~nameless-current-name~ as file-local variable.
  49 To do that, invoke the following command:
  50 #+BEGIN_SRC text
  51 M-x add-file-local-variable RET nameless-current-name RET "package-name"
  52 #+END_SRC
  53 You can also set the same name for all lisp files in a project by
  54 setting dir-local variables with ~M-x add-file-local-variable~.
  55
  56 If you /don’t/ want Nameless to use a namespace name at all (neither
  57 manual nor automatic), you can set ~nameless-discover-current-name~ to
  58 ~nil~. This will disable this functionality, so that Nameless will
  59 /only/ use aliases (see next item).
  60
  61 ** Requiring other packages as aliases
  62 Nameless can also be used to “import” other packages as aliases. For
  63 instance, in the default behaviour, functions in the ~font-lock~
  64 package (e.g., ~font-lock-add-keywords~) will be displayed with the
  65 ~fl:~ prefix (e.g., ~fl:add-keywords~).
  66
  67 You can configure your own aliases globally with ~nameless-global-aliases~.
  68 #+BEGIN_SRC emacs-lisp
  69 (setq nameless-global-aliases '(("fl" . "font-lock")
  70                                 ("s" . "seq")
  71                                 ("me" . "macroexp")
  72                                 ("c" . "cider")
  73                                 ("q" . "queue")))
  74 #+END_SRC
  75
  76 You can also configure aliases per-file by setting ~nameless-aliases~
  77 as a file-local variable.
  78 #+BEGIN_SRC emacs-lisp
  79 ;; Local Variables:
  80 ;; nameless-aliases: (("c" . "cider"))
  81 ;; End:
  82 #+END_SRC
  83 Note that there’s no ~quote~ before ~((c~!\\
  84 You can also configure it for a whole project, by setting it as a dir-local variable.
  85
  86 ** Private symbols
  87
  88 Private symbols in elisp are written with an extra dash after the
  89 prefix (e.g., ~foobar--indent-impl~). With Nameless, these are usually
  90 displayed as ~:-indent-impl~, but you can also make them be displayed
  91 as ~::indent-impl~ by setting
  92
  93 #+BEGIN_SRC emacs-lisp
  94 (setq nameless-private-prefix t)
  95 #+END_SRC
  96
  97 ** Packages that don’t use ~-~ (hyphen) as a separator
  98 You can set ~nameless-separator~ file-locally to whatever separator
  99 you package uses. Most packages use hyphens, by some use ~/~, ~|~, or
 100 ~:~.
 101
 102 You can also set it to ~nil~ globally and the separator will never be
 103 hidden.
 104 ** Indentation and paragraph filling
 105 Hiding parts of symbols could affect the way Emacs indents your code
 106 and fills your paragraphs. Nameless lets you decide whether you want
 107 that to happen or not.
 108
 109 The default behavior is that code is indented according to what you
 110 see (i.e., according to short symbols), but text inside strings is
 111 *not*. So text inside strings will be filled in the same way as if you
 112 didn’t have ~nameless-mode~. Here’s how a docstring might be filled
 113 with ~nameless-mode~ enabled:
 114 #+BEGIN_SRC text
 115 If point is immediately after an alias configured in the name you
 116 had in `:aliases' or `:global-aliases', replace
 117 it with the full name for that alias.
 118 #+END_SRC
 119 Altough it may look strange that the second line is so short, that’s
 120 the correct way. When view on a ~*Help*~ buffer, that docstring will
 121 look like this:
 122 #+BEGIN_SRC text
 123 If point is immediately after an alias configured in the name you
 124 had in `nameless-aliases' or `nameless-global-aliases', replace
 125 it with the full name for that alias.
 126 #+END_SRC
 127
 128 To change this behavior, configure the variable
 129 ~nameless-affect-indentation-and-filling~.