text.h

   1 #ifndef TEXT_H
   2 #define TEXT_H
   3
   4 #include <stdbool.h>
   5 #include <stdint.h>
   6 #include <time.h>
   7 #include <unistd.h>
   8 #include <stdarg.h>
   9 #include <sys/types.h>
  10 #include <sys/stat.h>
  11
  12 /** A mark. */
  13 typedef uintptr_t Mark;
  14
  15 /** An invalid mark, lookup of which will yield ``EPOS``. */
  16 #define EMARK ((Mark)0)
  17 /** An invalid position. */
  18 #define EPOS ((size_t)-1)
  19
  20 /** A range. */
  21 typedef struct {
  22         size_t start;  /**< Absolute byte position. */
  23         size_t end;    /**< Absolute byte position. */
  24 } Filerange;
  25
  26 /**
  27  * Text object storing the buffer content being edited.
  28  */
  29 typedef struct Text Text;
  30 typedef struct Piece Piece;
  31 typedef struct TextSave TextSave;
  32
  33 /** A contiguous part of the text. */
  34 typedef struct {
  35         const char *data; /**< Content, might not be NUL-terminated. */
  36         size_t len;       /**< Length in bytes. */
  37 } TextString;
  38
  39 /**
  40  * Iterator used to navigate the buffer content.
  41  *
  42  * Captures the position within a Piece.
  43  *
  44  * @rst
  45  * .. warning:: Any change to the Text will invalidate the iterator state.
  46  * .. note:: Should be treated as an opaque type.
  47  * @endrst
  48  */
  49 typedef struct {
  50         const char *start;  /**< Start of the piece data. */
  51         const char *end;    /**< End of piece data. Addressable range is ``[start, end)``. */
  52         const char *text;   /**< Current position within piece. Invariant ``start <= text < end`` holds. */
  53         const Piece *piece; /**< Internal state of current piece. */
  54         size_t pos;         /**< Absolute position in bytes from start of buffer. */
  55 } Iterator;
  56
  57 /**
  58  * @defgroup load
  59  * @{
  60  */
  61 /**
  62  * Method used to load existing file content.
  63  */
  64 enum TextLoadMethod {
  65         /** Automatically chose best option. */
  66         TEXT_LOAD_AUTO,
  67         /**
  68          * Read file content and copy it to an in-memory buffer.
  69          * Subsequent changes to the underlying file will have no
  70          * effect on this text instance.
  71          *
  72          * @rst
  73          * .. note:: Load time is linear in the file size.
  74          * @endrst
  75          */
  76         TEXT_LOAD_READ,
  77         /**
  78          * Memory map the file from disk. Use file system / virtual memory
  79          * subsystem as a caching layer.
  80          * @rst
  81          * .. note:: Load time is (almost) independent of the file size.
  82          * .. warning:: Inplace modifications of the underlying file
  83          *              will be reflected in the current text content.
  84          *              In particular, truncation will raise ``SIGBUS``
  85          *              and result in data loss.
  86          * @endrst
  87          */
  88         TEXT_LOAD_MMAP,
  89 };
  90 /**
  91  * Create a text instance populated with the given file content.
  92  *
  93  * @rst
  94  * .. note:: Equivalent to ``text_load_method(filename, TEXT_LOAD_AUTO)``.
  95  * @endrst
  96  */
  97 Text *text_load(const char *filename);
  98 Text *text_loadat(int dirfd, const char *filename);
  99 /**
 100  * Create a text instance populated with the given file content.
 101  *
 102  * @param filename The name of the file to load, if ``NULL`` an empty text is created.
 103  * @param method How the file content should be loaded.
 104  * @return The new Text object or ``NULL`` in case of an error.
 105  * @rst
 106  * .. note:: When attempting to load a non-regular file, ``errno`` will be set to:
 107  *
 108  *    - ``EISDIR`` for a directory.
 109  *    - ``ENOTSUP`` otherwise.
 110  * @endrst
 111  */
 112 Text *text_load_method(const char *filename, enum TextLoadMethod);
 113 Text *text_loadat_method(int dirfd, const char *filename, enum TextLoadMethod);
 114 /** Release all resources associated with this text instance. */
 115 void text_free(Text*);
 116 /**
 117  * @}
 118  * @defgroup state
 119  * @{
 120  */
 121 /** Return the size in bytes of the whole text. */
 122 size_t text_size(const Text*);
 123 /**
 124  * Get file information at time of load or last save, whichever happened more
 125  * recently.
 126  * @rst
 127  * .. note:: If an empty text instance was created using ``text_load(NULL)``
 128  *           and it has not yet been saved, an all zero ``struct stat`` will
 129  *           be returned.
 130  * @endrst
 131  * @return See ``stat(2)`` for details.
 132  */
 133 struct stat text_stat(const Text*);
 134 /** Query whether the text contains any unsaved modifications. */
 135 bool text_modified(const Text*);
 136 /**
 137  * @}
 138  * @defgroup modify
 139  * @{
 140  */
 141 /**
 142  * Insert data at the given byte position.
 143  *
 144  * @param pos The absolute byte position.
 145  * @param data The data to insert.
 146  * @param len The length of the data in bytes.
 147  * @return Whether the insertion succeeded.
 148  */
 149 bool text_insert(Text*, size_t pos, const char *data, size_t len);
 150 /**
 151  * Delete data at given byte position.
 152  *
 153  * @param pos The absolute byte position.
 154  * @param len The number of bytes to delete, starting from ``pos``.
 155  * @return Whether the deletion succeeded.
 156  */
 157 bool text_delete(Text*, size_t pos, size_t len);
 158 bool text_delete_range(Text*, const Filerange*);
 159 bool text_printf(Text*, size_t pos, const char *format, ...) __attribute__((format(printf, 3, 4)));
 160 bool text_appendf(Text*, const char *format, ...) __attribute__((format(printf, 2, 3)));
 161 /**
 162  * @}
 163  * @defgroup history
 164  * @{
 165  */
 166 /**
 167  * Create a text snapshot, that is a vertex in the history graph.
 168  */
 169 bool text_snapshot(Text*);
 170 /**
 171  * Revert to previous snapshot along the main branch.
 172  * @rst
 173  * .. note:: Takes an implicit snapshot.
 174  * @endrst
 175  * @return The position of the first change or ``EPOS``, if already at the
 176  *         oldest state i.e. there was nothing to undo.
 177  */
 178 size_t text_undo(Text*);
 179 /**
 180  * Reapply an older change along the main brach.
 181  * @rst
 182  * .. note:: Takes an implicit snapshot.
 183  * @endrst
 184  * @return The position of the first change or ``EPOS``, if already at the
 185  *         newest state i.e. there was nothing to redo.
 186  */
 187 size_t text_redo(Text*);
 188 size_t text_earlier(Text*);
 189 size_t text_later(Text*);
 190 /**
 191  * Restore the text to the state closest to the time given
 192  */
 193 size_t text_restore(Text*, time_t);
 194 /**
 195  * Get creation time of current state.
 196  * @rst
 197  * .. note:: TODO: This is currently not the same as the time of the last snapshot.
 198  * @endrst
 199  */
 200 time_t text_state(const Text*);
 201 /**
 202  * @}
 203  * @defgroup lines
 204  * @{
 205  */
 206 size_t text_pos_by_lineno(Text*, size_t lineno);
 207 size_t text_lineno_by_pos(Text*, size_t pos);
 208
 209 /**
 210  * @}
 211  * @defgroup access
 212  * @{
 213  */
 214 /**
 215  * Get byte stored at ``pos``.
 216  * @param pos The absolute position.
 217  * @param byte Destination address to store the byte.
 218  * @return Whether ``pos`` was valid and ``byte`` updated accordingly.
 219  * @rst
 220  * .. note:: Unlike :c:func:`text_iterator_byte_get()` this function does not
 221  *           return an artificial NUL byte at EOF.
 222  * @endrst
 223  */
 224 bool text_byte_get(const Text*, size_t pos, char *byte);
 225 /**
 226  * Store at most ``len`` bytes starting from ``pos`` into ``buf``.
 227  * @param pos The absolute starting position.
 228  * @param len The length in bytes.
 229  * @param buf The destination buffer.
 230  * @return The number of bytes (``<= len``) stored at ``buf``.
 231  * @rst
 232  * .. warning:: ``buf`` will not be NUL terminated.
 233  * @endrst
 234  */
 235 size_t text_bytes_get(const Text*, size_t pos, size_t len, char *buf);
 236 /**
 237  * Fetch text range into newly allocate memory region.
 238  * @param pos The absolute starting position.
 239  * @param len The length in bytes.
 240  * @return A contiguous NUL terminated buffer holding the requested range, or
 241  *         ``NULL`` in error case.
 242  * @rst
 243  * .. warning:: The returned pointer must be freed by the caller.
 244  * @endrst
 245  */
 246 char *text_bytes_alloc0(const Text*, size_t pos, size_t len);
 247 /**
 248  * @}
 249  * @defgroup iterator
 250  * @{
 251  */
 252 Iterator text_iterator_get(const Text*, size_t pos);
 253 bool text_iterator_init(const Text*, Iterator*, size_t pos);
 254 const Text *text_iterator_text(const Iterator*);
 255 bool text_iterator_valid(const Iterator*);
 256 bool text_iterator_has_next(const Iterator*);
 257 bool text_iterator_has_prev(const Iterator*);
 258 bool text_iterator_next(Iterator*);
 259 bool text_iterator_prev(Iterator*);
 260 /**
 261  * @}
 262  * @defgroup iterator_byte
 263  * @{
 264  */
 265 bool text_iterator_byte_get(const Iterator*, char *b);
 266 bool text_iterator_byte_prev(Iterator*, char *b);
 267 bool text_iterator_byte_next(Iterator*, char *b);
 268 bool text_iterator_byte_find_prev(Iterator*, char b);
 269 bool text_iterator_byte_find_next(Iterator*, char b);
 270 /**
 271  * @}
 272  * @defgroup iterator_code
 273  * @{
 274  */
 275 bool text_iterator_codepoint_next(Iterator *it, char *c);
 276 bool text_iterator_codepoint_prev(Iterator *it, char *c);
 277 /**
 278  * @}
 279  * @defgroup iterator_char
 280  * @{
 281  */
 282 bool text_iterator_char_next(Iterator*, char *c);
 283 bool text_iterator_char_prev(Iterator*, char *c);
 284 /**
 285  * @}
 286  * @defgroup mark
 287  * @{
 288  */
 289 /**
 290  * Set a mark.
 291  * @rst
 292  * .. note:: Setting a mark to ``text_size`` will always return the
 293  *           current text size upon lookup.
 294  * @endrst
 295  * @param pos The position at which to store the mark.
 296  * @return The mark or ``EMARK`` if an invalid position was given.
 297  */
 298 Mark text_mark_set(Text*, size_t pos);
 299 /**
 300  * Lookup a mark.
 301  * @param mark The mark to look up.
 302  * @return The byte position or ``EPOS`` for an invalid mark.
 303  */
 304 size_t text_mark_get(const Text*, Mark);
 305 /**
 306  * @}
 307  * @defgroup save
 308  * @{
 309  */
 310 /**
 311  * Method used to save the text.
 312  */
 313 enum TextSaveMethod {
 314         /** Automatically chose best option. */
 315         TEXT_SAVE_AUTO,
 316         /**
 317          * Save file atomically using ``rename(2)``.
 318          *
 319          * Creates a temporary file, restores all important meta data,
 320          * before moving it atomically to its final (possibly already
 321          * existing) destination using ``rename(2)``. For new files,
 322          * permissions are set to ``0666 & ~umask``.
 323          *
 324          * @rst
 325          * .. warning:: This approach does not work if:
 326          *
 327          *   - The file is a symbolic link.
 328          *   - The file is a hard link.
 329          *   - File ownership can not be preserved.
 330          *   - File group can not be preserved.
 331          *   - Directory permissions do not allow creation of a new file.
 332          *   - POSIX ACL can not be preserved (if enabled).
 333          *   - SELinux security context can not be preserved (if enabled).
 334          * @endrst
 335          */
 336         TEXT_SAVE_ATOMIC,
 337         /**
 338          * Overwrite file in place.
 339          * @rst
 340          * .. warning:: I/O failure might cause data loss.
 341          * @endrst
 342          */
 343         TEXT_SAVE_INPLACE,
 344 };
 345
 346 /**
 347  * Save the whole text to the given file name.
 348  *
 349  * @rst
 350  * .. note:: Equivalent to ``text_save_method(filename, TEXT_SAVE_AUTO)``.
 351  * @endrst
 352  */
 353 bool text_save(Text*, const char *filename);
 354 bool text_saveat(Text*, int dirfd, const char *filename);
 355 /**
 356  * Save the whole text to the given file name, using the specified method.
 357  */
 358 bool text_save_method(Text*, const char *filename, enum TextSaveMethod);
 359 bool text_saveat_method(Text*, int dirfd, const char *filename, enum TextSaveMethod);
 360
 361 /**
 362  * Setup a sequence of write operations.
 363  *
 364  * The returned ``TextSave`` pointer can be used to write multiple, possibly
 365  * non-contiguous, file ranges.
 366  * @rst
 367  * .. warning:: For every call to ``text_save_begin`` there must be exactly
 368  *              one matching call to either ``text_save_commit`` or
 369  *              ``text_save_cancel`` to release the underlying resources.
 370  * @endrst
 371  */
 372 TextSave *text_save_begin(Text*, int dirfd, const char *filename, enum TextSaveMethod);
 373 /**
 374  * Write file range.
 375  * @return The number of bytes written or ``-1`` in case of an error.
 376  */
 377 ssize_t text_save_write_range(TextSave*, const Filerange*);
 378 /**
 379  * Commit changes to disk.
 380  * @return Whether changes have been saved.
 381  * @rst
 382  * .. note:: Releases the underlying resources and frees the given ``TextSave``
 383  *           pointer which must no longer be used.
 384  * @endrst
 385  */
 386 bool text_save_commit(TextSave*);
 387 /**
 388  * Abort a save operation.
 389  * @rst
 390  * .. note:: Does not guarantee to undo the previous writes (they might have been
 391  *           performed in-place). However, it releases the underlying resources and
 392  *           frees the given ``TextSave`` pointer which must no longer be used.
 393  * @endrst
 394  */
 395 void text_save_cancel(TextSave*);
 396 /**
 397  * Write whole text content to file descriptor.
 398  * @return The number of bytes written or ``-1`` in case of an error.
 399  */
 400 ssize_t text_write(const Text*, int fd);
 401 /**
 402  * Write file range to file descriptor.
 403  * @return The number of bytes written or ``-1`` in case of an error.
 404  */
 405 ssize_t text_write_range(const Text*, const Filerange*, int fd);
 406 /**
 407  * @}
 408  * @defgroup misc
 409  * @{
 410  */
 411 /**
 412  * Check whether ``ptr`` is part of a memory mapped region associated with
 413  * this text instance.
 414  */
 415 bool text_mmaped(const Text*, const char *ptr);
 416 /** @} */
 417
 418 #endif