#+TITLE: Manipulate the Contents of Emacs Buffers
#+AUTHOR: Phillip Lord

#+INFOJS_OPT: view:info toc:nil


* Introduction

m-buffer provides functions for accessing and manipulating the contents of an
Emacs buffer. While Emacs already provides these features, m-buffer provides a
higher-level interaction. It achieves this in several ways: many of the
functions are list-orientated, so avoiding the need for iteration; it avoids
the use of global emacs state whenever it can be avoided, so avoiding
side-effects; and it provides a large library of functions supporting common
operations.

Core usage of buffer m-buffer is simple. For example, the following code
returns a list of all matches to the /regexp/ "m-buffer" in the
`current-buffer`.

#+BEGIN_SRC elisp
  (m-buffer-match
   (current-buffer)
   "m-buffer")
#+END_SRC

m-buffer is also expanding. Other parts of m-buffer provide stateless
interaction with the existing buffer; for example, we can use the following to
fetch the point of any buffer:

#+BEGIN_SRC elisp
  (m-buffer-at-point buffer)
#+END_SRC

These functions can help greatly when writing code which operates on two or
more buffers. It is also possible to check whether the status of a location --
either a buffer and position or a marker. For example, these calls are
equivalent to `eolp`.

#+BEGIN_SRC elisp
 (m-buffer-at-eolp buffer position)
 (m-buffer-at-eolp marker)
#+END_SRC



** Status

`m-buffer' is a work in progress, but much of it is now stable and the
interface should change only in forward-compatible ways for 1.0 release.
The individual files have statements about their stability.



* m-buffer

m-buffer.el provides list-orientated search both for any regexp and standard
regexps, as well as the ability to do things with these matches: replace, add
overlays or text-properties or, most generically of all, call any function on
matches.

#+include: "m-buffer.org" :minlevel 2


* m-buffer-at

m-buffer-at.el provides a set of stateless functions which for accessing data
about buffers, without requiring changing the `current-buffer'.

#+include: "m-buffer-at.org" :minlevel 2


* m-buffer-macro

m-buffer-macro.el provides some general purpose macros for:
 
 - dealing with markers and their cleanup
 - running code at a specific location

#+include: "m-buffer-macro.org" :minlevel 2


* m-buffer-benchmark

m-buffer-benchmark.el provides no functions, but is a set of benchmarks to
give some idea of how much overhead various m-buffer functions entail.

#+include: "m-buffer-benchmark.org" :minlevel 2


* Roadmap

** 0.11

Full lentic documentation using lentic-server


** 0.12

Completion of m-buffer-at with all the core buffer functions.