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 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, truncatenation 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 ressources 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(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*, 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 vertice in the history graph.
 168  */
 169 void 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 contigious 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 Text *text_iterator_text(const Iterator*);
 254 bool text_iterator_valid(const Iterator*);
 255 bool text_iterator_has_next(const Iterator*);
 256 bool text_iterator_has_prev(const Iterator*);
 257 bool text_iterator_next(Iterator*);
 258 bool text_iterator_prev(Iterator*);
 259 /**
 260  * @}
 261  * @defgroup iterator_byte
 262  * @{
 263  */
 264 bool text_iterator_byte_get(Iterator*, char *b);
 265 bool text_iterator_byte_prev(Iterator*, char *b);
 266 bool text_iterator_byte_next(Iterator*, char *b);
 267 bool text_iterator_byte_find_prev(Iterator*, char b);
 268 bool text_iterator_byte_find_next(Iterator*, char b);
 269 /**
 270  * @}
 271  * @defgroup iterator_code
 272  * @{
 273  */
 274 bool text_iterator_codepoint_next(Iterator *it, char *c);
 275 bool text_iterator_codepoint_prev(Iterator *it, char *c);
 276 /**
 277  * @}
 278  * @defgroup iterator_char
 279  * @{
 280  */
 281 bool text_iterator_char_next(Iterator*, char *c);
 282 bool text_iterator_char_prev(Iterator*, char *c);
 283 /**
 284  * @}
 285  * @defgroup mark
 286  * @{
 287  */
 288 /**
 289  * Set a mark.
 290  * @rst
 291  * .. note:: Setting a mark to ``text_size`` will always return the
 292  *           current text size upon lookup.
 293  * @endrst
 294  * @param pos The position at which to store the mark.
 295  * @return The mark or ``EMARK`` if an invalid position was given.
 296  */
 297 Mark text_mark_set(Text*, size_t pos);
 298 /**
 299  * Lookup a mark.
 300  * @param mark The mark to look up.
 301  * @return The byte position or ``EPOS`` for an invalid mark.
 302  */
 303 size_t text_mark_get(Text*, Mark);
 304 /**
 305  * @}
 306  * @defgroup save
 307  * @{
 308  */
 309 /**
 310  * Method used to save the text.
 311  */
 312 enum TextSaveMethod {
 313         /** Automatically chose best option. */
 314         TEXT_SAVE_AUTO,
 315         /**
 316          * Save file atomically using ``rename(2)``.
 317          *
 318          * Creates a temporary file, restores all important meta data,
 319          * before moving it atomically to its final (possibly already
 320          * existing) destination using ``rename(2)``. For new files,
 321          * permissions are set to ``0666 & ~umask``.
 322          *
 323          * @rst
 324          * .. warning:: This approach does not work if:
 325          *
 326          *   - The file is a symbolic link.
 327          *   - The file is a hard link.
 328          *   - File ownership can not be preserved.
 329          *   - File group can not be preserved.
 330          *   - Directory permissions do not allow creation of a new file.
 331          *   - POSXI ACL can not be preserved (if enabled).
 332          *   - SELinux security context can not be preserved (if enabled).
 333          * @endrst
 334          */
 335         TEXT_SAVE_ATOMIC,
 336         /**
 337          * Overwrite file in place.
 338          * @rst
 339          * .. warning:: I/O failure might cause data loss.
 340          * @endrst
 341          */
 342         TEXT_SAVE_INPLACE,
 343 };
 344
 345 /**
 346  * Save the whole text to the given file name.
 347  *
 348  * @rst
 349  * .. note:: Equivalent to ``text_save_method(filename, TEXT_SAVE_AUTO)``.
 350  * @endrst
 351  */
 352 bool text_save(Text*, const char *filename);
 353 bool text_saveat(Text*, int dirfd, const char *filename);
 354 /**
 355  * Save the whole text to the given file name, using the specified method.
 356  */
 357 bool text_save_method(Text*, const char *filename, enum TextSaveMethod);
 358 bool text_saveat_method(Text*, int dirfd, const char *filename, enum TextSaveMethod);
 359
 360 /**
 361  * Setup a sequence of write operations.
 362  *
 363  * The returned ``TextSave`` pointer can be used to write multiple, possibly
 364  * non-contigious, file ranges.
 365  * @rst
 366  * .. warning:: For every call to ``text_save_begin`` there must be exactly
 367  *              one matching call to either ``text_save_commit`` or
 368  *              ``text_save_cancel`` to release the underlying resources.
 369  * @endrst
 370  */
 371 TextSave *text_save_begin(Text*, int dirfd, const char *filename, enum TextSaveMethod);
 372 /**
 373  * Write file range.
 374  * @return The number of bytes written or ``-1`` in case of an error.
 375  */
 376 ssize_t text_save_write_range(TextSave*, Filerange*);
 377 /**
 378  * Commit changes to disk.
 379  * @return Whether changes have been saved.
 380  * @rst
 381  * .. note:: Releases the underlying resources and frees the given ``TextSave``
 382  *           pointer which must no longer be used.
 383  * @endrst
 384  */
 385 bool text_save_commit(TextSave*);
 386 /**
 387  * Abort a save operation.
 388  * @rst
 389  * .. note:: Does not guarantee to undo the previous writes (they might have been
 390  *           performed in-place). However, it releases the underlying resources and
 391  *           frees the given ``TextSave`` pointer which must no longer be used.
 392  * @endrst
 393  */
 394 void text_save_cancel(TextSave*);
 395 /**
 396  * Write whole text content to file descriptor.
 397  * @return The number of bytes written or ``-1`` in case of an error.
 398  */
 399 ssize_t text_write(Text*, int fd);
 400 /**
 401  * Write file range to file descriptor.
 402  * @return The number of bytes written or ``-1`` in case of an error.
 403  */
 404 ssize_t text_write_range(Text*, Filerange*, int fd);
 405 /**
 406  * @}
 407  * @defgroup misc
 408  * @{
 409  */
 410 /**
 411  * Check whether ``ptr`` is part of a memory mapped region associated with
 412  * this text instance.
 413  */
 414 bool text_mmaped(Text*, const char *ptr);
 415 /** @} */
 416
 417 #endif