{"id":13861967,"url":"https://github.com/clemera/objed","last_synced_at":"2025-04-06T22:09:08.292Z","repository":{"id":45695873,"uuid":"155398246","full_name":"clemera/objed","owner":"clemera","description":"Navigate and edit text objects with Emacs. Development on pause.","archived":false,"fork":false,"pushed_at":"2022-07-25T15:54:02.000Z","size":3048,"stargazers_count":333,"open_issues_count":24,"forks_count":21,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-30T20:12:58.613Z","etag":null,"topics":["emacs","text-objects","textedit","texteditor"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clemera.png","metadata":{"files":{"readme":"README.asc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-30T14:21:12.000Z","updated_at":"2025-02-08T21:41:11.000Z","dependencies_parsed_at":"2022-07-18T06:30:29.231Z","dependency_job_id":null,"html_url":"https://github.com/clemera/objed","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clemera%2Fobjed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clemera%2Fobjed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clemera%2Fobjed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clemera%2Fobjed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clemera","download_url":"https://codeload.github.com/clemera/objed/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247557767,"owners_count":20958047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emacs","text-objects","textedit","texteditor"],"created_at":"2024-08-05T06:01:33.916Z","updated_at":"2025-04-06T22:09:08.261Z","avatar_url":"https://github.com/clemera.png","language":"Emacs Lisp","readme":":experimental:\n\n++++\n\u003ca href=\"https://elpa.gnu.org/packages/objed.html\"\u003e\u003cimg alt=\"GNU ELPA\" src=\"https://elpa.gnu.org/favicon.png\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://stable.melpa.org/#/objed\"\u003e\u003cimg alt=\"MELPA Stable\" src=\"https://stable.melpa.org/packages/objed-badge.svg\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://melpa.org/#/objed\"\u003e\u003cimg alt=\"MELPA\" src=\"https://melpa.org/packages/objed-badge.svg\"/\u003e\u003c/a\u003e\n++++\n\n= Objed - The text object editor\n\n*Development is currently paused but I have plans for a complete overhaul of the\n project. Objed is completely usable in its current state but note that its\n public interface is subject to change.*\n\nA global minor-mode to navigate and edit text objects. Objed also enables\nmodal editing and composition of commands. It combines ideas of\nhttp://emacs-versor.sourceforge.net/[versor-mode] and other Editors like Vim\nor Kakoune and tries to align them with regular Emacs conventions.\n\nFor more information you can read my\nhttps://with-emacs.com/posts/objed/[posts] about `objed` and for\nchanges check the https://github.com/clemera/objed/blob/master/News.asc[News]\nfile.\n\n== Introduction\n\nText objects are textual patterns like a line, a top level definition, a word,\na sentence or any other unit of text. When `objed-mode` or `objed-local-mode`\nis enabled, certain editing commands (configurable) will activate `objed` and\nenable its modal editing features. When active, keys which would usually insert\na character are mapped to objed commands. Other keys and commands will continue\nto work as they normally would and exit this editing state again.\n\nBy default important editing keys like kbd:[Space], kbd:[DEL] or kbd:[Return]\nare not bound to modal commands and will execute the regular command and exit\n`objed`. Character movement exits `objed`, as well. This makes it convenient\nto move around and continue by adding/deleting text.\n\nWith activation `objed` shows the current object type in the `mode-line`. The\ntextual content of the object is highlighted visually in the buffer and the\ncursor color is changed, too. The user can now navigate by units of this\nobject, change the object state or switch to other object types.\n\nThe object state is either `inner` or `whole` and is indicated in the modeline\nby `(i)` or `(w)` after the object type. With inner state, anything that would\nbe considered delimiters or padding around an object is excluded.\n\nThe user can apply operations to objects. By marking objects before applying\nan operation, s?he can even operate on multiple objects at once. This works\nsimilar to the way you interact with files in `dired`. When marking an object,\nthe point moves on to the next object of this type.\n\nThe object type used for initialization is determined by the\nentry command (see `objed-cmd-alist`). For example, using `beginning-of-defun`\nwill activate `objed` using the `defun` object as an initial object type. With\nthe command `next-line`, `objed` would initialize with the `line` object. To\nactivate `objed` without movement you can use `objed-activate`, bound to\nkbd:[M-SPC] by default. Objed uses the last command and its mapping in\n`objed-command-alist` to choose the initial object.\n\nObjed's modal state provides basic movement commands which move by line, sexp\nword or character. Those commands automatically activate the corresponding object\ntype. Other commands only activate the part between the initial position and\nthe new position moved to. By repeating commands you can often expand/proceed\nto other objects. This way you can compose movement and editing operations\nvery efficiently.\n\nThe expansion commands distinguish between block objects (objects built out of\nlines of text like paragraphs or text blocks with the same level of\nindentation and also comment blocks) and context objects (programming\nconstructs like strings, brackets, comments or functions). This way you can\nquickly expand to the desired objects.\n\nFor example to move to the end of the paragraph, the user would first move to\nthe end of the line with kbd:[Ctrl - e]. This would activate `objed` using the\nline object with the text moved over. The user can now continue to the end of\nthe paragraph by pressing kbd:[e] again. Now s?he is able to proceed even\nfurther by pressing kbd:[e] again OR to continue by adding new text to the end\nof the paragraph OR to continue by acting on the text moved over, for example\nkilling it by pressing kbd:[k].\n\nAs often with text editing, the explanation sounds more complicated than using\nit. To get a better impression of the editing workflow with `objed` I have\nadded some animated demos below.\n\nTo learn more about available features and commands have a look at the\ndescriptions below, the commentary section or the docstrings and bindings\ndefined in `objed-map`. To define your own operations and text objects see\n`objed-define-op` and `objed-define-object`.\n\n## Examples of usage\n\n*Note* that the key bindings shown in the screencasts below aren't up to date.\n\n.Object navigation\nimage::./images/object_nav.gif[Object navigation]\n\n++++\n\u003cbr\u003e\n++++\n\n.Object expansion\nimage::./images/expand_context.gif[Object expansion]\n\n++++\n\u003cbr\u003e\n++++\n\n.End of block expansion\nimage::./images/end_of_block.gif[End of block expansion]\n\n++++\n\u003cbr\u003e\n++++\n\n.Upto context\nimage::./images/upto.gif[Upto context]\n\n++++\n\u003cbr\u003e\n++++\n\n.Marking objects and act on them\nimage::./images/reorder_lines_by_marking.gif[Marking objects and act on them]\n\n++++\n\u003cbr\u003e\n++++\n\n.Mark objects inside another one\nimage::./images/remove_comments_in_defun.gif[Mark objects inside another one]\n\n++++\n\u003cbr\u003e\n++++\n\n.Select current object type with avy\nimage::./images/senteces_avy.gif[Select current object type with avy]\n\n++++\n\u003cbr\u003e\n++++\n\n.Navigate and search output object\nimage::./images/output_occur.gif[Navigate and search output object]\n\n++++\n\u003cbr\u003e\n++++\n\n## Keys\n\nAlthough some features are still experimental the basic user interface will\nstay the same. The following gives an overview of available keys and commands.\nIf commands allow for numeric arguments you can input them without the use of\nkbd:[Ctrl] or kbd:[Meta]. kbd:[0] can be used as an alternative for the\nuniversal argument (kbd:[C-u]). To add custom commands to the modal state you\ncan use `objed-user-map` which is available under prefix key kbd:['] and\n`objed-other-user-map` bound to kbd:[-]. It's recommended to use one of these\nmap for custom object bindings and the other one for additional operations.\n\nYou can customize the default bindings for object keys using\n`objed-define-global-object-keys` and also define major mode specific bindings\nusing `objed-define-local-object-keys`.\n\nIn addition to the commands configured in `objed-cmd-alist` you can use the\nfollowing commands to enter objed (those bindings are only active if you are\nusing `objed-mode`, if you choose to activate objed always manually you have\nto bind those commands in your `global-map`):\n\n[`objed-mode-map`]\n|===\n|Shortcut |Purpose\n\n|kbd:[M-SPC]\n|Activate objed, choosing initial object based on `last-command` and `objed-cmd-alist`.\n\n|kbd:[M-#]\n|Choose an object and activate with it.\n\n|kbd:[C-,/C-.]\n|Move to previous/next identifier and activate `identifier` object.\n\n|kbd:[M-[]\n|Activate object at point (determined from context) and move to its start.\n\n|kbd:[M-\\]]\n|Activate object at point (determined from context) and move to its end.\n\n|kbd:[M-(]\n|Move to beginning of object at point and active text moved over.\n\n|kbd:[M-)]\n|Move to end of object at point and active text moved over.\n|===\n\nBasic movement commands (switch the object type on movement):\n\n[`objed-map`]\n|===\n|Shortcut |Purpose\n\n|kbd:[l/h]\n|Move forward/backward one char and activate the char object\n\n|kbd:[f/b]\n|Move forward/backward one sexp and activate the sexp object\n\n|kbd:[s/r]\n|Move forward/backward one word and activate the word object.\n\n|kbd:[n/p]\n|Move to the next/previous line and activate the line object.\n|===\n\nCommands for block objects (objects built out of lines of text):\n\n[`objed-map`]\n|===\n|Shortcut |Purpose\n\n|kbd:[v]\n|Activate (line based) object at point and move to its start. On repeat proceed to beginning of the indentation block, comment block, paragraph or other block objects.\n\n|kbd:[a]\n|Move to beginning of line and activate the text moved over. On repeat proceed to beginning of blocks like explained above.\n\n|kbd:[e]\n|Move to end of line and activate the text moved over. On repeat proceed to end of blocks like explained above.\n|===\n\nCommands for context objects. Those objects are common programming constructs\nlike defuns, strings, parentheses but also sentences inside comments for\nexample. Any whitespace after point is skipped before determining the context:\n\n[`objed-map`]\n|===\n|Shortcut |Purpose\n\n|kbd:[o]\n|Activate the inner part of the object at point and move to the start. This is useful to act on the content of the string, brackets and so on. On repeat expand to other objects around current position.\n\n|kbd:[j]\n|Move point to the other side of the current object.\n\n|kbd:[t]\n|Toggle object state. Switches between inner and whole object state.\n\n|kbd:[[/\\]]\n|Move to the start of previous/next instance of current object type.\n\n|kbd:[(/)]\n|Move to inner beginning/end of the object at point and activate the text moved over.\n\n|kbd:[{/}]\n|Move forward/backward paragraph and switch to paragraph object\n\n|kbd:[\u003c/\u003e]\n|Goto first/last instance of current object type (https://with-emacs.com/posts/objed/spotlight-objed-move-to-first-or-last-instance/[blog]).\n|===\n\nCommands to switch objects (and move point to its start, repeating an object\ncommand mark all instances in current defun/buffer):\n\n[`objed-map`]\n|===\n|Shortcut |Purpose\n|kbd:[.]\n|Switch to identifier object or move to next.\n\n|kbd:[,]\n|Switch to identifier object and move to previous.\n\n|kbd:[c]\n|Prefix to switch to other objects, see `objed-object-map` for available objects and `objed-define-object` to add your own (https://with-emacs.com/posts/objed/writing-your-own-text-objects-for-objed/[blog]).\n|===\n\n\nIndent/Move objects around:\n\n[`objed-map`]\n|===\n|Shortcut |Purpose\n\n|kbd:[C-left/C-right]\n|Move/indent all lines in object right/leftward.\n\n|kbd:[M-left/M-right]\n|Move/indent all lines in object to right/leftward to tab stop.\n\n|kbd:[C-M-left/C-M-right]\n|Slurp following sexp into current object/Barf last sexp out of current object.\n\n|kbd:[S-left/S-right/S-up/S-down/F/B]\n|Move current object type forward/backward (https://with-emacs.com/posts/i-like-to-move-it-emacs-version/[blog]).\n\n|kbd:[L/H]\n|Switch to char object and move it forward/backward.\n\n|kbd:[S/R]\n|Switch to word object and move it forward/backward.\n\n|kbd:[N/P]\n|Switch to line object and move it forward/backward.\n|===\n\nCommands to edit objects (applying operations to them). When the region is\nactive the operation acts on the current region. To act on multiple objects at\nonce you can mark them first (see the \"Misc commands\" below):\n\n[`objed-map`]\n|===\n|Shortcut |Purpose\n\n|kbd:[i]\n|Delete current object(s) and switch to insert.\n\n|kbd:[k]\n|Kill current object(s). Continues by selecting the next instance from point.\n\n|kbd:[K]\n|Kill current object. Continues by selecting the previous instance from point.\n\n|kbd:[d]\n|Delete current object(s). Continues by selecting the next instance from point.\n\n|kbd:[D]\n|Delete current object. Continues by selecting the previous instance from point.\n\n|kbd:[w]\n|Copy current object(s). On repeat move to next and append it to `kill-ring`\n\n|kbd:[y]\n|Yank last killed text at point. On repeat, cycle through `kill-ring`\n\n|kbd:[\\ ]\n|Indent object(s).\n\n|kbd:[;]\n|Un/comment object(s).\n\n|kbd:[%]\n|Query replace narrowed to current object.\n\n|kbd:[^]\n|Replace object with inner part (raise).\n\n|kbd:[!]\n|Run object contents as shell commands.\n\n|kbd:[\u0026]\n|Pipe object region through shell command.\n\n|kbd:[\\|]\n|Incrementally construct command chain to replace text (https://with-emacs.com/posts/objed/incremental-construction-of-command-chains-to-replace-text/[blog]).\n\n|kbd:[Ctrl - RET]\n|Evaluate current object in REPL (need `eval-in-repl` to be installed).\n\n|kbd:[M - RET]\n|Duplicate object.\n\n|kbd:[S - RET]\n|Comment and duplicate object.\n\n|kbd:[C - M - RET]\n|Insert new (empty) instance of current object type. This inserts the object boundaries without the inner content.\n\n|kbd:[$]\n|Spell check textual content of object using `flyspell`.\n\n|kbd:[~]\n|Undo in current object region.\n\n|kbd:[\"]\n|Add surroundings to object(s) with any pair using `electric` (built-in).\n\n|kbd:[x]\n|Prefix to access other operations, see `objed-op-map` for available operations and `objed-define-op` to add your own.\n\n|===\n\nMisc commands:\n\n[`objed-map`]\n|===\n|Shortcut |Purpose\n\n|kbd:[q]\n|Quit window or reformat in edit buffer.\n\n|kbd:[u]\n|Pop to last state, which restores the last position and any object data.\n\n|kbd:[z]\n|Choose an instance of current object type on the screen with `avy` (https://with-emacs.com/posts/objed/jump-around-emacs-version/[blog]).\n\n|kbd:[M-g o]\n|Choose an instance of current object, by first lines content.\n\n|kbd:[m]\n|Add/Remove current object to marked objects and move to next.\n\n|kbd:[M]\n|Add/Remove current object to marked objects and move to previous.\n\n|kbd:[@]\n|Activate region with current object (extend current object).\n\n|kbd:[Ctrl - Space]\n|Set mark.\n\n|kbd:[/]\n|Undo last edit command.\n\n|kbd:[C-h b]\n|Get key binding help (uses `which-key` if available).\n\n|kbd:[g/Ctrl - g]\n|Exit and deactivate `objed`.\n|===\n\n\nDispatch keys (dispatch to any object defined in `objed-object-map`).\nYou can add your own prefix bindings using `objed-define-dispatch`.\n\n[`objed-map`]\n|===\n|Shortcut |Purpose\n\n|kbd:[*]\n|Mark more instances of current object inside defun/buffer.\n\n|kbd:[#]\n|Switch to another object using `avy`.\n\n|kbd:[=]\n|Switch to another object inside the current one using `avy`.\n\n|kbd:[`]\n|Activate part from point forward until boundary of some object.\n\n|kbd:[´]\n|Activate part from point backward until boundary of some object.\n\n|kbd:[+]\n|Extend current object by including trailing whitespace.\n|===\n\n\n== Installation\n\n\n`Objed` is on MELPA and GNU ELPA, for installation use:\n\n```emacs\nM-x package-refresh-contents RET\nM-x package-install RET objed RET\n;; activate objed-mode in you init\n(objed-mode)\n```\n\nFor manual installation:\n\n```sh\ngit clone http://github.com/clemera/objed.git\n```\nAdd this to your init file:\n\n```elisp\n(add-to-list 'load-path \"/\u003cpath-to\u003e/objed\")\n(require 'objed)\n(objed-mode)\n;; activating the mode is optional, you can activate objed\n;; always manually using `objed-activate' the other\n;; commands bound in `objed-mode-map`, for example:\n;; (global-set-key (kbd \"M-SPC\") 'objed-activate)\n```\n\nIn case you don't want to enable `objed` globally, use `objed-local-mode`:\n\n```emacs\n(add-hook 'prog-mode-hook #'objed-local-mode)\n```\n\n== Contribute\n\nI'm happy to receive pull requests or ideas to improve this package. Some\nparts suffer from the bottom up approach of developing it, but this also\nallowed me to experiment a lot and try ideas while working on them, something\nthat Emacs is especially good at. Most of the features are tested using\n`emacs-lisp-mode` but hopefully there aren't to many problems using modes for\nother languages. Before submitting a PR please check your code compiles\ncleanly and all tests are passing:\n\n```sh\nmake test\n```\n\n=== Copyright Assignment\n\n\nThis package is subject to the same\nhttps://www.gnu.org/prep/maintain/html_node/Copyright-Papers.html[Copyright Assignment]\npolicy as Emacs itself, org-mode, CEDET and other packages in https://elpa.gnu.org/packages/[GNU ELPA].\n\nAny\nhttps://www.gnu.org/prep/maintain/html_node/Legally-Significant.html#Legally-Significant[legally significant]\ncontributions can only be accepted after the author has completed\ntheir paperwork. Please see\nhttps://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/Copyright/request-assign.future[the request form]\nif you want to proceed with the assignment.\n\n","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclemera%2Fobjed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclemera%2Fobjed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclemera%2Fobjed/lists"}