code.delx.au - gnu-emacs-elpa/blob - packages/load-relative/README.md

   1 [![Build Status](https://travis-ci.org/rocky/emacs-load-relative.png)](https://travis-ci.org/rocky/emacs-load-relative)
   2
   3 # Emacs multi-file develop/run-from-of-source routines
   4
   5 The rational behind module is to be able to write small Emacs
   6 functions or modules in a larger multi-file Emacs package and
   7 facilitate running from the source tree without having to "install"
   8 the code or fiddle with evil *load-path*'s . See my [NYC Lisp talk](https://github.com/rocky/emacs-load-relative/wiki/NYC-Lisp-talk) for more background on this.
   9
  10
  11 ## Contents ##
  12
  13 * [\__FILE__](https://github.com/rocky/emacs-load-relative#file)
  14 * [load-relative](https://github.com/rocky/emacs-load-relative#load-relative)
  15 * [require-relative](https://github.com/rocky/emacs-load-relative#require-relative-require-relative-list)
  16 * [provide-me](https://github.com/rocky/emacs-load-relative#provide-me)
  17
  18 The latest version is at http://github.com/rocky/emacs-load-relative
  19
  20 ## \__FILE__
  21
  22 \__FILE__ returns the file name that that the calling program is
  23 running.  If you are *eval*'ing a buffer then the file name of that
  24 buffer is used. The name was selected to be analogous to the name used
  25 in C, Perl, and Ruby.
  26
  27 For an common example of using this, see [How to Insert Demo Code into an Emacs Lisp Module](https://github.com/rocky/emacs-load-relative/wiki/How-to-Insert-Demo-Code-into-an-Emacs-Lisp-Module).
  28
  29 ## load-relative
  30
  31 *load-relative* loads an Emacs Lisp file relative to another
  32  (presumably currently running) Emacs Lisp file. For example suppose
  33  you have Emacs Lisp files `foo.el` and `bar.el` in the same directory.
  34  To load Emacs Lisp file `bar.el` from inside Emacs lisp file `foo.el`:
  35
  36 ```lisp
  37     (require 'load-relative)
  38     (load-relative "baz")
  39 ```
  40
  41 That *load-relative* line could above have also been written as:
  42
  43 ```lisp
  44    (load-relative "./baz")
  45 ```
  46
  47 or:
  48
  49 ```lisp
  50    (load-relative "baz.el")  # if you want to exclude any byte-compiled files
  51 ```
  52
  53 ## require-relative, require-relative-list
  54
  55 Use *require-relative* if you want to *require* the file instead of
  56 *load*'ing it:
  57
  58 ```lisp
  59    (require-relative "baz")
  60 ```
  61
  62 or:
  63
  64 ```lisp
  65    (require-relative "./baz")
  66 ```
  67
  68 The above not only does a *require* on `'baz`, but makes sure you get
  69 that from the same file as you would have if you had issued
  70 *load_relative*.
  71
  72 Use *require-relative-list* when you have a list of files you want to
  73 *require*. To *require-relative* them in one shot:
  74
  75 ```lisp
  76    (require-relative-list '("dbgr-init" "dbgr-fringe"))
  77 ```
  78
  79 ## provide-me
  80
  81 The macro *provide-me* saves you the trouble of adding a symbol
  82 after *provide*, by using the file basename (without directory or file
  83 extension) as the name of the thing you want to provide. Using this
  84 forces the *provide* names to be the same as the filename, but I
  85 consider that a good thing.
  86
  87 *provide-me* also takes an optional string which will be prepended to the provide name. This is useful if you have a multi-file package and want the files to bue prefaced with the name of the package.
  88
  89 Assume your package *foo* and contains simply file `foo.el`. Then
  90 adding:
  91
  92 ```lisp
  93    (provide-me)
  94 ```
  95
  96 inside that file is the same thing as writing:
  97
  98 ```lisp
  99    (provide 'foo)
 100 ```
 101
 102 Now suppose `foo.el` is part of a larger package called *bar*. Then if
 103 you write:
 104
 105 ```lisp
 106    (provide-me "bar-")
 107 ```
 108
 109 this is the same as writing:
 110
 111 ```lisp
 112    (provide 'bar-foo)
 113 ```
 114
 115
 116 ## find-file-noselect-relative
 117
 118 The function *find-file-noselect-relative* provides a way of accessing
 119 resources which are located relative to the currently running Emacs lisp file.
 120 This is probably most useful when running Emacs as a scripting engine for
 121 batch processing or with tests cases.
 122
 123 ```lisp
 124    (find-file-noselect-relative "README.md")
 125 ```
 126
 127 ## with-relative-file
 128
 129 The macro *with-relative-file* runs in a buffer with the contents of the given
 130 relative file.
 131
 132 ```lisp
 133    (with-relative-file "README.md"
 134      (buffer-substring))
 135 ```
 136