├── .gitignore ├── LICENSE ├── README.org ├── orderless-kwd.el ├── orderless.el └── orderless.texi /.gitignore: -------------------------------------------------------------------------------- 1 | *.elc 2 | *-autoloads.el 3 | *-pkg.el 4 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU General Public License is a free, copyleft license for 11 | software and other kinds of works. 12 | 13 | The licenses for most software and other practical works are designed 14 | to take away your freedom to share and change the works. By contrast, 15 | the GNU General Public License is intended to guarantee your freedom to 16 | share and change all versions of a program--to make sure it remains free 17 | software for all its users. We, the Free Software Foundation, use the 18 | GNU General Public License for most of our software; it applies also to 19 | any other work released this way by its authors. You can apply it to 20 | your programs, too. 21 | 22 | When we speak of free software, we are referring to freedom, not 23 | price. Our General Public Licenses are designed to make sure that you 24 | have the freedom to distribute copies of free software (and charge for 25 | them if you wish), that you receive source code or can get it if you 26 | want it, that you can change the software or use pieces of it in new 27 | free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you 30 | these rights or asking you to surrender the rights. Therefore, you have 31 | certain responsibilities if you distribute copies of the software, or if 32 | you modify it: responsibilities to respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether 35 | gratis or for a fee, you must pass on to the recipients the same 36 | freedoms that you received. You must make sure that they, too, receive 37 | or can get the source code. And you must show them these terms so they 38 | know their rights. 39 | 40 | Developers that use the GNU GPL protect your rights with two steps: 41 | (1) assert copyright on the software, and (2) offer you this License 42 | giving you legal permission to copy, distribute and/or modify it. 43 | 44 | For the developers' and authors' protection, the GPL clearly explains 45 | that there is no warranty for this free software. For both users' and 46 | authors' sake, the GPL requires that modified versions be marked as 47 | changed, so that their problems will not be attributed erroneously to 48 | authors of previous versions. 49 | 50 | Some devices are designed to deny users access to install or run 51 | modified versions of the software inside them, although the manufacturer 52 | can do so. This is fundamentally incompatible with the aim of 53 | protecting users' freedom to change the software. The systematic 54 | pattern of such abuse occurs in the area of products for individuals to 55 | use, which is precisely where it is most unacceptable. Therefore, we 56 | have designed this version of the GPL to prohibit the practice for those 57 | products. If such problems arise substantially in other domains, we 58 | stand ready to extend this provision to those domains in future versions 59 | of the GPL, as needed to protect the freedom of users. 60 | 61 | Finally, every program is threatened constantly by software patents. 62 | States should not allow patents to restrict development and use of 63 | software on general-purpose computers, but in those that do, we wish to 64 | avoid the special danger that patents applied to a free program could 65 | make it effectively proprietary. To prevent this, the GPL assures that 66 | patents cannot be used to render the program non-free. 67 | 68 | The precise terms and conditions for copying, distribution and 69 | modification follow. 70 | 71 | TERMS AND CONDITIONS 72 | 73 | 0. Definitions. 74 | 75 | "This License" refers to version 3 of the GNU General Public License. 76 | 77 | "Copyright" also means copyright-like laws that apply to other kinds of 78 | works, such as semiconductor masks. 79 | 80 | "The Program" refers to any copyrightable work licensed under this 81 | License. Each licensee is addressed as "you". "Licensees" and 82 | "recipients" may be individuals or organizations. 83 | 84 | To "modify" a work means to copy from or adapt all or part of the work 85 | in a fashion requiring copyright permission, other than the making of an 86 | exact copy. The resulting work is called a "modified version" of the 87 | earlier work or a work "based on" the earlier work. 88 | 89 | A "covered work" means either the unmodified Program or a work based 90 | on the Program. 91 | 92 | To "propagate" a work means to do anything with it that, without 93 | permission, would make you directly or secondarily liable for 94 | infringement under applicable copyright law, except executing it on a 95 | computer or modifying a private copy. Propagation includes copying, 96 | distribution (with or without modification), making available to the 97 | public, and in some countries other activities as well. 98 | 99 | To "convey" a work means any kind of propagation that enables other 100 | parties to make or receive copies. Mere interaction with a user through 101 | a computer network, with no transfer of a copy, is not conveying. 102 | 103 | An interactive user interface displays "Appropriate Legal Notices" 104 | to the extent that it includes a convenient and prominently visible 105 | feature that (1) displays an appropriate copyright notice, and (2) 106 | tells the user that there is no warranty for the work (except to the 107 | extent that warranties are provided), that licensees may convey the 108 | work under this License, and how to view a copy of this License. If 109 | the interface presents a list of user commands or options, such as a 110 | menu, a prominent item in the list meets this criterion. 111 | 112 | 1. Source Code. 113 | 114 | The "source code" for a work means the preferred form of the work 115 | for making modifications to it. "Object code" means any non-source 116 | form of a work. 117 | 118 | A "Standard Interface" means an interface that either is an official 119 | standard defined by a recognized standards body, or, in the case of 120 | interfaces specified for a particular programming language, one that 121 | is widely used among developers working in that language. 122 | 123 | The "System Libraries" of an executable work include anything, other 124 | than the work as a whole, that (a) is included in the normal form of 125 | packaging a Major Component, but which is not part of that Major 126 | Component, and (b) serves only to enable use of the work with that 127 | Major Component, or to implement a Standard Interface for which an 128 | implementation is available to the public in source code form. A 129 | "Major Component", in this context, means a major essential component 130 | (kernel, window system, and so on) of the specific operating system 131 | (if any) on which the executable work runs, or a compiler used to 132 | produce the work, or an object code interpreter used to run it. 133 | 134 | The "Corresponding Source" for a work in object code form means all 135 | the source code needed to generate, install, and (for an executable 136 | work) run the object code and to modify the work, including scripts to 137 | control those activities. However, it does not include the work's 138 | System Libraries, or general-purpose tools or generally available free 139 | programs which are used unmodified in performing those activities but 140 | which are not part of the work. For example, Corresponding Source 141 | includes interface definition files associated with source files for 142 | the work, and the source code for shared libraries and dynamically 143 | linked subprograms that the work is specifically designed to require, 144 | such as by intimate data communication or control flow between those 145 | subprograms and other parts of the work. 146 | 147 | The Corresponding Source need not include anything that users 148 | can regenerate automatically from other parts of the Corresponding 149 | Source. 150 | 151 | The Corresponding Source for a work in source code form is that 152 | same work. 153 | 154 | 2. Basic Permissions. 155 | 156 | All rights granted under this License are granted for the term of 157 | copyright on the Program, and are irrevocable provided the stated 158 | conditions are met. This License explicitly affirms your unlimited 159 | permission to run the unmodified Program. The output from running a 160 | covered work is covered by this License only if the output, given its 161 | content, constitutes a covered work. This License acknowledges your 162 | rights of fair use or other equivalent, as provided by copyright law. 163 | 164 | You may make, run and propagate covered works that you do not 165 | convey, without conditions so long as your license otherwise remains 166 | in force. You may convey covered works to others for the sole purpose 167 | of having them make modifications exclusively for you, or provide you 168 | with facilities for running those works, provided that you comply with 169 | the terms of this License in conveying all material for which you do 170 | not control copyright. Those thus making or running the covered works 171 | for you must do so exclusively on your behalf, under your direction 172 | and control, on terms that prohibit them from making any copies of 173 | your copyrighted material outside their relationship with you. 174 | 175 | Conveying under any other circumstances is permitted solely under 176 | the conditions stated below. Sublicensing is not allowed; section 10 177 | makes it unnecessary. 178 | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 180 | 181 | No covered work shall be deemed part of an effective technological 182 | measure under any applicable law fulfilling obligations under article 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 184 | similar laws prohibiting or restricting circumvention of such 185 | measures. 186 | 187 | When you convey a covered work, you waive any legal power to forbid 188 | circumvention of technological measures to the extent such circumvention 189 | is effected by exercising rights under this License with respect to 190 | the covered work, and you disclaim any intention to limit operation or 191 | modification of the work as a means of enforcing, against the work's 192 | users, your or third parties' legal rights to forbid circumvention of 193 | technological measures. 194 | 195 | 4. Conveying Verbatim Copies. 196 | 197 | You may convey verbatim copies of the Program's source code as you 198 | receive it, in any medium, provided that you conspicuously and 199 | appropriately publish on each copy an appropriate copyright notice; 200 | keep intact all notices stating that this License and any 201 | non-permissive terms added in accord with section 7 apply to the code; 202 | keep intact all notices of the absence of any warranty; and give all 203 | recipients a copy of this License along with the Program. 204 | 205 | You may charge any price or no price for each copy that you convey, 206 | and you may offer support or warranty protection for a fee. 207 | 208 | 5. Conveying Modified Source Versions. 209 | 210 | You may convey a work based on the Program, or the modifications to 211 | produce it from the Program, in the form of source code under the 212 | terms of section 4, provided that you also meet all of these conditions: 213 | 214 | a) The work must carry prominent notices stating that you modified 215 | it, and giving a relevant date. 216 | 217 | b) The work must carry prominent notices stating that it is 218 | released under this License and any conditions added under section 219 | 7. This requirement modifies the requirement in section 4 to 220 | "keep intact all notices". 221 | 222 | c) You must license the entire work, as a whole, under this 223 | License to anyone who comes into possession of a copy. This 224 | License will therefore apply, along with any applicable section 7 225 | additional terms, to the whole of the work, and all its parts, 226 | regardless of how they are packaged. This License gives no 227 | permission to license the work in any other way, but it does not 228 | invalidate such permission if you have separately received it. 229 | 230 | d) If the work has interactive user interfaces, each must display 231 | Appropriate Legal Notices; however, if the Program has interactive 232 | interfaces that do not display Appropriate Legal Notices, your 233 | work need not make them do so. 234 | 235 | A compilation of a covered work with other separate and independent 236 | works, which are not by their nature extensions of the covered work, 237 | and which are not combined with it such as to form a larger program, 238 | in or on a volume of a storage or distribution medium, is called an 239 | "aggregate" if the compilation and its resulting copyright are not 240 | used to limit the access or legal rights of the compilation's users 241 | beyond what the individual works permit. Inclusion of a covered work 242 | in an aggregate does not cause this License to apply to the other 243 | parts of the aggregate. 244 | 245 | 6. Conveying Non-Source Forms. 246 | 247 | You may convey a covered work in object code form under the terms 248 | of sections 4 and 5, provided that you also convey the 249 | machine-readable Corresponding Source under the terms of this License, 250 | in one of these ways: 251 | 252 | a) Convey the object code in, or embodied in, a physical product 253 | (including a physical distribution medium), accompanied by the 254 | Corresponding Source fixed on a durable physical medium 255 | customarily used for software interchange. 256 | 257 | b) Convey the object code in, or embodied in, a physical product 258 | (including a physical distribution medium), accompanied by a 259 | written offer, valid for at least three years and valid for as 260 | long as you offer spare parts or customer support for that product 261 | model, to give anyone who possesses the object code either (1) a 262 | copy of the Corresponding Source for all the software in the 263 | product that is covered by this License, on a durable physical 264 | medium customarily used for software interchange, for a price no 265 | more than your reasonable cost of physically performing this 266 | conveying of source, or (2) access to copy the 267 | Corresponding Source from a network server at no charge. 268 | 269 | c) Convey individual copies of the object code with a copy of the 270 | written offer to provide the Corresponding Source. This 271 | alternative is allowed only occasionally and noncommercially, and 272 | only if you received the object code with such an offer, in accord 273 | with subsection 6b. 274 | 275 | d) Convey the object code by offering access from a designated 276 | place (gratis or for a charge), and offer equivalent access to the 277 | Corresponding Source in the same way through the same place at no 278 | further charge. You need not require recipients to copy the 279 | Corresponding Source along with the object code. If the place to 280 | copy the object code is a network server, the Corresponding Source 281 | may be on a different server (operated by you or a third party) 282 | that supports equivalent copying facilities, provided you maintain 283 | clear directions next to the object code saying where to find the 284 | Corresponding Source. Regardless of what server hosts the 285 | Corresponding Source, you remain obligated to ensure that it is 286 | available for as long as needed to satisfy these requirements. 287 | 288 | e) Convey the object code using peer-to-peer transmission, provided 289 | you inform other peers where the object code and Corresponding 290 | Source of the work are being offered to the general public at no 291 | charge under subsection 6d. 292 | 293 | A separable portion of the object code, whose source code is excluded 294 | from the Corresponding Source as a System Library, need not be 295 | included in conveying the object code work. 296 | 297 | A "User Product" is either (1) a "consumer product", which means any 298 | tangible personal property which is normally used for personal, family, 299 | or household purposes, or (2) anything designed or sold for incorporation 300 | into a dwelling. In determining whether a product is a consumer product, 301 | doubtful cases shall be resolved in favor of coverage. For a particular 302 | product received by a particular user, "normally used" refers to a 303 | typical or common use of that class of product, regardless of the status 304 | of the particular user or of the way in which the particular user 305 | actually uses, or expects or is expected to use, the product. A product 306 | is a consumer product regardless of whether the product has substantial 307 | commercial, industrial or non-consumer uses, unless such uses represent 308 | the only significant mode of use of the product. 309 | 310 | "Installation Information" for a User Product means any methods, 311 | procedures, authorization keys, or other information required to install 312 | and execute modified versions of a covered work in that User Product from 313 | a modified version of its Corresponding Source. The information must 314 | suffice to ensure that the continued functioning of the modified object 315 | code is in no case prevented or interfered with solely because 316 | modification has been made. 317 | 318 | If you convey an object code work under this section in, or with, or 319 | specifically for use in, a User Product, and the conveying occurs as 320 | part of a transaction in which the right of possession and use of the 321 | User Product is transferred to the recipient in perpetuity or for a 322 | fixed term (regardless of how the transaction is characterized), the 323 | Corresponding Source conveyed under this section must be accompanied 324 | by the Installation Information. But this requirement does not apply 325 | if neither you nor any third party retains the ability to install 326 | modified object code on the User Product (for example, the work has 327 | been installed in ROM). 328 | 329 | The requirement to provide Installation Information does not include a 330 | requirement to continue to provide support service, warranty, or updates 331 | for a work that has been modified or installed by the recipient, or for 332 | the User Product in which it has been modified or installed. Access to a 333 | network may be denied when the modification itself materially and 334 | adversely affects the operation of the network or violates the rules and 335 | protocols for communication across the network. 336 | 337 | Corresponding Source conveyed, and Installation Information provided, 338 | in accord with this section must be in a format that is publicly 339 | documented (and with an implementation available to the public in 340 | source code form), and must require no special password or key for 341 | unpacking, reading or copying. 342 | 343 | 7. Additional Terms. 344 | 345 | "Additional permissions" are terms that supplement the terms of this 346 | License by making exceptions from one or more of its conditions. 347 | Additional permissions that are applicable to the entire Program shall 348 | be treated as though they were included in this License, to the extent 349 | that they are valid under applicable law. If additional permissions 350 | apply only to part of the Program, that part may be used separately 351 | under those permissions, but the entire Program remains governed by 352 | this License without regard to the additional permissions. 353 | 354 | When you convey a copy of a covered work, you may at your option 355 | remove any additional permissions from that copy, or from any part of 356 | it. (Additional permissions may be written to require their own 357 | removal in certain cases when you modify the work.) You may place 358 | additional permissions on material, added by you to a covered work, 359 | for which you have or can give appropriate copyright permission. 360 | 361 | Notwithstanding any other provision of this License, for material you 362 | add to a covered work, you may (if authorized by the copyright holders of 363 | that material) supplement the terms of this License with terms: 364 | 365 | a) Disclaiming warranty or limiting liability differently from the 366 | terms of sections 15 and 16 of this License; or 367 | 368 | b) Requiring preservation of specified reasonable legal notices or 369 | author attributions in that material or in the Appropriate Legal 370 | Notices displayed by works containing it; or 371 | 372 | c) Prohibiting misrepresentation of the origin of that material, or 373 | requiring that modified versions of such material be marked in 374 | reasonable ways as different from the original version; or 375 | 376 | d) Limiting the use for publicity purposes of names of licensors or 377 | authors of the material; or 378 | 379 | e) Declining to grant rights under trademark law for use of some 380 | trade names, trademarks, or service marks; or 381 | 382 | f) Requiring indemnification of licensors and authors of that 383 | material by anyone who conveys the material (or modified versions of 384 | it) with contractual assumptions of liability to the recipient, for 385 | any liability that these contractual assumptions directly impose on 386 | those licensors and authors. 387 | 388 | All other non-permissive additional terms are considered "further 389 | restrictions" within the meaning of section 10. If the Program as you 390 | received it, or any part of it, contains a notice stating that it is 391 | governed by this License along with a term that is a further 392 | restriction, you may remove that term. If a license document contains 393 | a further restriction but permits relicensing or conveying under this 394 | License, you may add to a covered work material governed by the terms 395 | of that license document, provided that the further restriction does 396 | not survive such relicensing or conveying. 397 | 398 | If you add terms to a covered work in accord with this section, you 399 | must place, in the relevant source files, a statement of the 400 | additional terms that apply to those files, or a notice indicating 401 | where to find the applicable terms. 402 | 403 | Additional terms, permissive or non-permissive, may be stated in the 404 | form of a separately written license, or stated as exceptions; 405 | the above requirements apply either way. 406 | 407 | 8. Termination. 408 | 409 | You may not propagate or modify a covered work except as expressly 410 | provided under this License. Any attempt otherwise to propagate or 411 | modify it is void, and will automatically terminate your rights under 412 | this License (including any patent licenses granted under the third 413 | paragraph of section 11). 414 | 415 | However, if you cease all violation of this License, then your 416 | license from a particular copyright holder is reinstated (a) 417 | provisionally, unless and until the copyright holder explicitly and 418 | finally terminates your license, and (b) permanently, if the copyright 419 | holder fails to notify you of the violation by some reasonable means 420 | prior to 60 days after the cessation. 421 | 422 | Moreover, your license from a particular copyright holder is 423 | reinstated permanently if the copyright holder notifies you of the 424 | violation by some reasonable means, this is the first time you have 425 | received notice of violation of this License (for any work) from that 426 | copyright holder, and you cure the violation prior to 30 days after 427 | your receipt of the notice. 428 | 429 | Termination of your rights under this section does not terminate the 430 | licenses of parties who have received copies or rights from you under 431 | this License. If your rights have been terminated and not permanently 432 | reinstated, you do not qualify to receive new licenses for the same 433 | material under section 10. 434 | 435 | 9. Acceptance Not Required for Having Copies. 436 | 437 | You are not required to accept this License in order to receive or 438 | run a copy of the Program. Ancillary propagation of a covered work 439 | occurring solely as a consequence of using peer-to-peer transmission 440 | to receive a copy likewise does not require acceptance. However, 441 | nothing other than this License grants you permission to propagate or 442 | modify any covered work. These actions infringe copyright if you do 443 | not accept this License. Therefore, by modifying or propagating a 444 | covered work, you indicate your acceptance of this License to do so. 445 | 446 | 10. Automatic Licensing of Downstream Recipients. 447 | 448 | Each time you convey a covered work, the recipient automatically 449 | receives a license from the original licensors, to run, modify and 450 | propagate that work, subject to this License. You are not responsible 451 | for enforcing compliance by third parties with this License. 452 | 453 | An "entity transaction" is a transaction transferring control of an 454 | organization, or substantially all assets of one, or subdividing an 455 | organization, or merging organizations. If propagation of a covered 456 | work results from an entity transaction, each party to that 457 | transaction who receives a copy of the work also receives whatever 458 | licenses to the work the party's predecessor in interest had or could 459 | give under the previous paragraph, plus a right to possession of the 460 | Corresponding Source of the work from the predecessor in interest, if 461 | the predecessor has it or can get it with reasonable efforts. 462 | 463 | You may not impose any further restrictions on the exercise of the 464 | rights granted or affirmed under this License. For example, you may 465 | not impose a license fee, royalty, or other charge for exercise of 466 | rights granted under this License, and you may not initiate litigation 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that 468 | any patent claim is infringed by making, using, selling, offering for 469 | sale, or importing the Program or any portion of it. 470 | 471 | 11. Patents. 472 | 473 | A "contributor" is a copyright holder who authorizes use under this 474 | License of the Program or a work on which the Program is based. The 475 | work thus licensed is called the contributor's "contributor version". 476 | 477 | A contributor's "essential patent claims" are all patent claims 478 | owned or controlled by the contributor, whether already acquired or 479 | hereafter acquired, that would be infringed by some manner, permitted 480 | by this License, of making, using, or selling its contributor version, 481 | but do not include claims that would be infringed only as a 482 | consequence of further modification of the contributor version. For 483 | purposes of this definition, "control" includes the right to grant 484 | patent sublicenses in a manner consistent with the requirements of 485 | this License. 486 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free 488 | patent license under the contributor's essential patent claims, to 489 | make, use, sell, offer for sale, import and otherwise run, modify and 490 | propagate the contents of its contributor version. 491 | 492 | In the following three paragraphs, a "patent license" is any express 493 | agreement or commitment, however denominated, not to enforce a patent 494 | (such as an express permission to practice a patent or covenant not to 495 | sue for patent infringement). To "grant" such a patent license to a 496 | party means to make such an agreement or commitment not to enforce a 497 | patent against the party. 498 | 499 | If you convey a covered work, knowingly relying on a patent license, 500 | and the Corresponding Source of the work is not available for anyone 501 | to copy, free of charge and under the terms of this License, through a 502 | publicly available network server or other readily accessible means, 503 | then you must either (1) cause the Corresponding Source to be so 504 | available, or (2) arrange to deprive yourself of the benefit of the 505 | patent license for this particular work, or (3) arrange, in a manner 506 | consistent with the requirements of this License, to extend the patent 507 | license to downstream recipients. "Knowingly relying" means you have 508 | actual knowledge that, but for the patent license, your conveying the 509 | covered work in a country, or your recipient's use of the covered work 510 | in a country, would infringe one or more identifiable patents in that 511 | country that you have reason to believe are valid. 512 | 513 | If, pursuant to or in connection with a single transaction or 514 | arrangement, you convey, or propagate by procuring conveyance of, a 515 | covered work, and grant a patent license to some of the parties 516 | receiving the covered work authorizing them to use, propagate, modify 517 | or convey a specific copy of the covered work, then the patent license 518 | you grant is automatically extended to all recipients of the covered 519 | work and works based on it. 520 | 521 | A patent license is "discriminatory" if it does not include within 522 | the scope of its coverage, prohibits the exercise of, or is 523 | conditioned on the non-exercise of one or more of the rights that are 524 | specifically granted under this License. You may not convey a covered 525 | work if you are a party to an arrangement with a third party that is 526 | in the business of distributing software, under which you make payment 527 | to the third party based on the extent of your activity of conveying 528 | the work, and under which the third party grants, to any of the 529 | parties who would receive the covered work from you, a discriminatory 530 | patent license (a) in connection with copies of the covered work 531 | conveyed by you (or copies made from those copies), or (b) primarily 532 | for and in connection with specific products or compilations that 533 | contain the covered work, unless you entered into that arrangement, 534 | or that patent license was granted, prior to 28 March 2007. 535 | 536 | Nothing in this License shall be construed as excluding or limiting 537 | any implied license or other defenses to infringement that may 538 | otherwise be available to you under applicable patent law. 539 | 540 | 12. No Surrender of Others' Freedom. 541 | 542 | If conditions are imposed on you (whether by court order, agreement or 543 | otherwise) that contradict the conditions of this License, they do not 544 | excuse you from the conditions of this License. If you cannot convey a 545 | covered work so as to satisfy simultaneously your obligations under this 546 | License and any other pertinent obligations, then as a consequence you may 547 | not convey it at all. For example, if you agree to terms that obligate you 548 | to collect a royalty for further conveying from those to whom you convey 549 | the Program, the only way you could satisfy both those terms and this 550 | License would be to refrain entirely from conveying the Program. 551 | 552 | 13. Use with the GNU Affero General Public License. 553 | 554 | Notwithstanding any other provision of this License, you have 555 | permission to link or combine any covered work with a work licensed 556 | under version 3 of the GNU Affero General Public License into a single 557 | combined work, and to convey the resulting work. The terms of this 558 | License will continue to apply to the part which is the covered work, 559 | but the special requirements of the GNU Affero General Public License, 560 | section 13, concerning interaction through a network will apply to the 561 | combination as such. 562 | 563 | 14. Revised Versions of this License. 564 | 565 | The Free Software Foundation may publish revised and/or new versions of 566 | the GNU General Public License from time to time. Such new versions will 567 | be similar in spirit to the present version, but may differ in detail to 568 | address new problems or concerns. 569 | 570 | Each version is given a distinguishing version number. If the 571 | Program specifies that a certain numbered version of the GNU General 572 | Public License "or any later version" applies to it, you have the 573 | option of following the terms and conditions either of that numbered 574 | version or of any later version published by the Free Software 575 | Foundation. If the Program does not specify a version number of the 576 | GNU General Public License, you may choose any version ever published 577 | by the Free Software Foundation. 578 | 579 | If the Program specifies that a proxy can decide which future 580 | versions of the GNU General Public License can be used, that proxy's 581 | public statement of acceptance of a version permanently authorizes you 582 | to choose that version for the Program. 583 | 584 | Later license versions may give you additional or different 585 | permissions. However, no additional obligations are imposed on any 586 | author or copyright holder as a result of your choosing to follow a 587 | later version. 588 | 589 | 15. Disclaimer of Warranty. 590 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 599 | 600 | 16. Limitation of Liability. 601 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 610 | SUCH DAMAGES. 611 | 612 | 17. Interpretation of Sections 15 and 16. 613 | 614 | If the disclaimer of warranty and limitation of liability provided 615 | above cannot be given local legal effect according to their terms, 616 | reviewing courts shall apply local law that most closely approximates 617 | an absolute waiver of all civil liability in connection with the 618 | Program, unless a warranty or assumption of liability accompanies a 619 | copy of the Program in return for a fee. 620 | 621 | END OF TERMS AND CONDITIONS 622 | 623 | How to Apply These Terms to Your New Programs 624 | 625 | If you develop a new program, and you want it to be of the greatest 626 | possible use to the public, the best way to achieve this is to make it 627 | free software which everyone can redistribute and change under these terms. 628 | 629 | To do so, attach the following notices to the program. It is safest 630 | to attach them to the start of each source file to most effectively 631 | state the exclusion of warranty; and each file should have at least 632 | the "copyright" line and a pointer to where the full notice is found. 633 | 634 | 635 | Copyright (C) 636 | 637 | This program is free software: you can redistribute it and/or modify 638 | it under the terms of the GNU General Public License as published by 639 | the Free Software Foundation, either version 3 of the License, or 640 | (at your option) any later version. 641 | 642 | This program is distributed in the hope that it will be useful, 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 645 | GNU General Public License for more details. 646 | 647 | You should have received a copy of the GNU General Public License 648 | along with this program. If not, see . 649 | 650 | Also add information on how to contact you by electronic and paper mail. 651 | 652 | If the program does terminal interaction, make it output a short 653 | notice like this when it starts in an interactive mode: 654 | 655 | Copyright (C) 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 657 | This is free software, and you are welcome to redistribute it 658 | under certain conditions; type `show c' for details. 659 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate 661 | parts of the General Public License. Of course, your program's commands 662 | might be different; for a GUI interface, you would use an "about box". 663 | 664 | You should also get your employer (if you work as a programmer) or school, 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. 666 | For more information on this, and how to apply and follow the GNU GPL, see 667 | . 668 | 669 | The GNU General Public License does not permit incorporating your program 670 | into proprietary programs. If your program is a subroutine library, you 671 | may consider it more useful to permit linking proprietary applications with 672 | the library. If this is what you want to do, use the GNU Lesser General 673 | Public License instead of this License. But first, please read 674 | . 675 | -------------------------------------------------------------------------------- /README.org: -------------------------------------------------------------------------------- 1 | #+TITLE: Orderless 2 | #+OPTIONS: d:nil 3 | #+EXPORT_FILE_NAME: orderless.texi 4 | #+TEXINFO_DIR_CATEGORY: Emacs misc features 5 | #+TEXINFO_DIR_TITLE: Orderless: (orderless). 6 | #+TEXINFO_DIR_DESC: Completion style for matching regexps in any order 7 | 8 | #+html: GNU ELPA 9 | #+html: GNU-devel ELPA 10 | #+html: MELPA 11 | #+html: MELPA Stable 12 | 13 | * Overview 14 | :PROPERTIES: 15 | :TOC: :include all :ignore this 16 | :END: 17 | 18 | This package provides an =orderless= /completion style/ that divides the 19 | pattern into space-separated components, and matches candidates that 20 | match all of the components in any order. Each component can match in 21 | any one of several ways: literally, as a regexp, as an initialism, in 22 | the flex style, or as multiple word prefixes. By default, regexp and 23 | literal matches are enabled. 24 | 25 | A completion style is a back-end for completion and is used from a 26 | front-end that provides a completion UI. Any completion style can be 27 | used with the default Emacs completion UI (sometimes called minibuffer 28 | tab completion), with the built-in Icomplete package (which is similar 29 | to the more well-known Ido Mode), the icomplete-vertical variant from 30 | Emacs 28 (see the external [[https://github.com/oantolin/icomplete-vertical][icomplete-vertical]] package to get that 31 | functionality on earlier versions of Emacs), or with some third party 32 | minibuffer completion frameworks such as [[https://gitlab.com/protesilaos/mct][Mct]] or [[https://github.com/minad/vertico][Vertico]]. 33 | 34 | All the completion UIs just mentioned are for minibuffer completion, 35 | used when Emacs commands prompt the user in the minibuffer for some 36 | input, but there is also completion at point in normal buffers, 37 | typically used for identifiers in programming languages. Completion 38 | styles can also be used for that purpose by completion at point UIs 39 | such as [[https://github.com/minad/corfu][Corfu]], [[https://company-mode.github.io/][Company]] or the function =consult-completion-in-region= 40 | from [[https://github.com/minad/consult][Consult]]. 41 | 42 | To use a completion style with any of the above mentioned completion 43 | UIs simply add it as an entry in the variables =completion-styles= and 44 | =completion-category-overrides= and =completion-category-defaults= (see 45 | their documentation). 46 | 47 | The =completion-category-defaults= variable serves as a default value 48 | for =completion-category-overrides=. If you want to use =orderless= 49 | exclusively, set both variables to =nil=, but be aware that 50 | =completion-category-defaults= is modified by packages at load time. 51 | 52 | With a bit of effort, it might still be possible to use =orderless= with 53 | other completion UIs, even if those UIs don't support the standard 54 | Emacs completion styles. Currently there is support for [[https://github.com/abo-abo/swiper][Ivy]] (see 55 | below). Also, while Company does support completion styles directly, 56 | pressing =SPC= takes you out of completion, so comfortably using 57 | =orderless= with it takes a bit of configuration (see below). 58 | 59 | If you use ELPA or MELPA, the easiest way to install =orderless= is via 60 | =package-install=. If you use =use-package=, you can use: 61 | 62 | #+begin_src emacs-lisp 63 | (use-package orderless 64 | :ensure t 65 | :custom 66 | (completion-styles '(orderless basic)) 67 | (completion-category-overrides '((file (styles basic partial-completion))))) 68 | #+end_src 69 | 70 | Alternatively, put =orderless.el= somewhere on your =load-path=, and use 71 | the following configuration: 72 | 73 | #+begin_src emacs-lisp 74 | (require 'orderless) 75 | (setq completion-styles '(orderless basic) 76 | completion-category-overrides '((file (styles basic partial-completion)))) 77 | #+end_src 78 | 79 | The =basic= completion style is specified as fallback in addition to 80 | =orderless= in order to ensure that completion commands which rely on 81 | dynamic completion tables, e.g., ~completion-table-dynamic~ or 82 | ~completion-table-in-turn~, work correctly. Furthermore the =basic= 83 | completion style needs to be tried /first/ (not as a fallback) for TRAMP 84 | hostname completion to work. In order to achieve that, we add an entry 85 | for the =file= completion category in the =completion-category-overrides= 86 | variable. In addition, the =partial-completion= style allows you to use 87 | wildcards for file completion and partial paths, e.g., ~/u/s/l~ for 88 | ~/usr/share/local~. 89 | 90 | Bug reports are highly welcome and appreciated! 91 | 92 | :CONTENTS: 93 | - [[#screenshot][Screenshot]] 94 | - [[#customization][Customization]] 95 | - [[#component-matching-styles][Component matching styles]] 96 | - [[#style-dispatchers][Style dispatchers]] 97 | - [[#component-separator-regexp][Component separator regexp]] 98 | - [[#faces-for-component-matches][Faces for component matches]] 99 | - [[#pattern-compiler][Pattern compiler]] 100 | - [[#interactively-changing-the-configuration][Interactively changing the configuration]] 101 | - [[#integration-with-other-completion-uis][Integration with other completion UIs]] 102 | - [[#ivy][Ivy]] 103 | - [[#company][Company]] 104 | - [[#related-packages][Related packages]] 105 | - [[#ivy-and-helm][Ivy and Helm]] 106 | - [[#prescient][Prescient]] 107 | - [[#restricting-to-current-matches-in-icicles-ido-and-ivy][Restricting to current matches: Icicles, Ido and Ivy]] 108 | :END: 109 | 110 | ** Screenshot :noexport: 111 | 112 | This is what it looks like to use =describe-function= (bound by default 113 | to =C-h f=) to match =eis ff=. Notice that in this particular case =eis= 114 | matched as an initialism, and =ff= matched as a regexp. The completion 115 | UI in the screenshot is [[https://github.com/oantolin/icomplete-vertical][icomplete-vertical]] and the theme is 116 | Protesilaos Stavrou's lovely [[https://gitlab.com/protesilaos/modus-themes][modus-operandi]]. 117 | 118 | [[https://github.com/oantolin/orderless/blob/dispatcher/images/describe-function-eis-ff.png?raw=true]] 119 | 120 | * Customization 121 | 122 | ** Component matching styles 123 | 124 | Each component of a pattern can match in any of several matching 125 | styles. A matching style is a function from strings to regexps or 126 | predicates, so it is easy to define new matching styles. The value 127 | returned by a matching style can be either a regexp as a string, an 128 | s-expression in =rx= syntax or a predicate function. The predefined 129 | matching styles are: 130 | 131 | - orderless-regexp :: the component is treated as a regexp that must 132 | match somewhere in the candidate. 133 | 134 | If the component is not a valid regexp, it is ignored. 135 | 136 | - orderless-literal :: the component is treated as a literal string 137 | that must occur in the candidate. 138 | 139 | - orderless-literal-prefix :: the component is treated as a literal 140 | string that must occur as a prefix of a candidate. 141 | 142 | - orderless-prefixes :: the component is split at word endings and 143 | each piece must match at a word boundary in the candidate, occurring 144 | in that order. 145 | 146 | This is similar to the built-in =partial-completion= completion-style. 147 | For example, =re-re= matches =query-replace-regexp=, =recode-region= and 148 | =magit-remote-list-refs=; =f-d.t= matches =final-draft.txt=. 149 | 150 | - orderless-initialism :: each character of the component should appear 151 | as the beginning of a word in the candidate, in order. 152 | 153 | This maps =abc= to =\ 6 | ;; Created: 2024 7 | 8 | ;; This file is part of GNU Emacs. 9 | 10 | ;; This program is free software: you can redistribute it and/or modify 11 | ;; it under the terms of the GNU General Public License as published by 12 | ;; the Free Software Foundation, either version 3 of the License, or 13 | ;; (at your option) any later version. 14 | 15 | ;; This program is distributed in the hope that it will be useful, 16 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 17 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 | ;; GNU General Public License for more details. 19 | 20 | ;; You should have received a copy of the GNU General Public License 21 | ;; along with this program. If not, see . 22 | 23 | ;;; Commentary: 24 | 25 | ;; Provide the `orderless-kwd-dispatch' style dispatcher, which 26 | ;; recognizes input of the form `:mod:org' to filter buffers by mode 27 | ;; in `switch-to-buffer' or `:on' to only display enabled minor modes 28 | ;; in M-x. The list of supported keywords is configured in 29 | ;; `orderless-kwd-alist'. 30 | ;; 31 | ;; The dispatcher can be enabled by adding it to 32 | ;; `orderless-style-dispatchers': 33 | ;; 34 | ;; (add-to-list 'orderless-style-dispatchers #'orderless-kwd-dispatch) 35 | ;; 36 | ;; See the customization variables `orderless-kwd-prefix' and 37 | ;; `orderless-kwd-separator' in order to configure the syntax. 38 | 39 | ;;; Code: 40 | 41 | (require 'orderless) 42 | (eval-when-compile (require 'cl-lib)) 43 | 44 | (defcustom orderless-kwd-prefix ?: 45 | "Keyword dispatcher prefix character." 46 | :type 'character 47 | :group 'orderless) 48 | 49 | (defcustom orderless-kwd-separator ":=" 50 | "Keyword separator characters." 51 | :type 'string 52 | :group 'orderless) 53 | 54 | (defcustom orderless-kwd-alist 55 | `((ann ,#'orderless-annotation) 56 | (pre ,#'orderless-literal-prefix) 57 | (cat ,#'orderless-kwd-category) 58 | (con ,#'orderless-kwd-content) 59 | (dir ,#'orderless-kwd-directory) 60 | (fil ,#'orderless-kwd-file) 61 | (doc ,#'orderless-kwd-documentation) 62 | (grp ,#'orderless-kwd-group) 63 | (mod ,#'orderless-kwd-mode) 64 | (val ,#'orderless-kwd-value) 65 | (dif ,#'orderless-kwd-modified t) 66 | (key ,#'orderless-kwd-key t) 67 | (ro ,#'orderless-kwd-read-only t) 68 | (off ,#'orderless-kwd-off t) 69 | (on ,#'orderless-kwd-on t)) 70 | "Keyword dispatcher alist. 71 | The list associates a keyword with a matcher function and an 72 | optional boolean flag. If the flag is non-nil, the matcher acts 73 | as a flag and does not require input." 74 | :type '(alist :key-type symbol 75 | :value-type (choice (list function) (list function (const t)))) 76 | :group 'orderless) 77 | 78 | (defsubst orderless-kwd--get-buffer (str) 79 | "Return buffer from candidate STR taking `multi-category' into account." 80 | (when-let ((cat (get-text-property 0 'multi-category str))) 81 | (setq str (and (eq (car cat) 'buffer) (cdr cat)))) 82 | (and str (get-buffer str))) 83 | 84 | (defsubst orderless-kwd--orig-buffer () 85 | "Return the original buffer before miniwindow selection." 86 | (or (window-buffer (minibuffer-selected-window)) (current-buffer))) 87 | 88 | (defun orderless-kwd-category (pred regexp) 89 | "Match candidate category against PRED and REGEXP." 90 | (lambda (str) 91 | (when-let ((cat (car (get-text-property 0 'multi-category str)))) 92 | (orderless--match-p pred regexp (symbol-name cat))))) 93 | 94 | (defun orderless-kwd-group (pred regexp) 95 | "Match candidate group title against PRED and REGEXP." 96 | (when-let ((fun (compat-call completion-metadata-get 97 | (orderless--metadata) 'group-function))) 98 | (lambda (str) 99 | (orderless--match-p pred regexp (funcall fun str nil))))) 100 | 101 | (defun orderless-kwd-content (_pred regexp) 102 | "Match buffer content against REGEXP." 103 | (lambda (str) 104 | (when-let ((buf (orderless-kwd--get-buffer str))) 105 | (with-current-buffer buf 106 | (save-excursion 107 | (save-restriction 108 | (widen) 109 | (goto-char (point-min)) 110 | (ignore-errors (re-search-forward regexp nil 'noerror)))))))) 111 | 112 | (defun orderless-kwd-documentation (pred regexp) 113 | "Match documentation against PRED and REGEXP." 114 | (lambda (str) 115 | (when-let ((sym (intern-soft str))) 116 | (orderless--match-p 117 | pred regexp 118 | (or (ignore-errors (documentation sym)) 119 | (cl-loop 120 | for doc in '(variable-documentation 121 | face-documentation 122 | group-documentation) 123 | thereis (ignore-errors (documentation-property sym doc)))))))) 124 | 125 | (defun orderless-kwd-key (pred regexp) 126 | "Match command key binding against PRED and REGEXP." 127 | (let ((buf (orderless-kwd--orig-buffer))) 128 | (lambda (str) 129 | (when-let ((sym (intern-soft str)) 130 | ((fboundp sym)) 131 | (keys (with-current-buffer buf (where-is-internal sym)))) 132 | (cl-loop 133 | for key in keys 134 | thereis (orderless--match-p pred regexp (key-description key))))))) 135 | 136 | (defun orderless-kwd-value (pred regexp) 137 | "Match variable value against PRED and REGEXP." 138 | (let ((buf (orderless-kwd--orig-buffer))) 139 | (lambda (str) 140 | (when-let ((sym (intern-soft str)) 141 | ((boundp sym))) 142 | (let ((print-level 10) 143 | (print-length 1000)) 144 | (orderless--match-p 145 | pred regexp (prin1-to-string (buffer-local-value sym buf)))))))) 146 | 147 | (defun orderless-kwd-off (_) 148 | "Match disabled minor modes." 149 | (let ((buf (orderless-kwd--orig-buffer))) 150 | (lambda (str) 151 | (when-let ((sym (intern-soft str))) 152 | (and (boundp sym) 153 | (memq sym minor-mode-list) 154 | (not (buffer-local-value sym buf))))))) 155 | 156 | (defun orderless-kwd-on (_) 157 | "Match enabled minor modes." 158 | (let ((buf (orderless-kwd--orig-buffer))) 159 | (lambda (str) 160 | (when-let ((sym (intern-soft str))) 161 | (and (boundp sym) 162 | (memq sym minor-mode-list) 163 | (buffer-local-value sym buf)))))) 164 | 165 | (defun orderless-kwd-modified (_) 166 | "Match modified buffers." 167 | (lambda (str) 168 | (when-let ((buf (orderless-kwd--get-buffer str))) 169 | (buffer-modified-p buf)))) 170 | 171 | (defun orderless-kwd-read-only (_) 172 | "Match read-only buffers." 173 | (lambda (str) 174 | (when-let ((buf (orderless-kwd--get-buffer str))) 175 | (buffer-local-value 'buffer-read-only buf)))) 176 | 177 | (defun orderless-kwd-mode (pred regexp) 178 | "Match buffer mode or bookmark type against PRED and REGEXP." 179 | (declare-function bookmark-prop-get "bookmark") 180 | (lambda (str) 181 | (if-let ((buf (orderless-kwd--get-buffer str))) 182 | (when-let ((mode (buffer-local-value 'major-mode buf))) 183 | (or (orderless--match-p pred regexp (symbol-name mode)) 184 | (orderless--match-p pred regexp 185 | (format-mode-line 186 | (buffer-local-value 'mode-name buf))))) 187 | (when-let ((name (if-let ((cat (get-text-property 0 'multi-category str))) 188 | (and (eq (car cat) 'bookmark) (cdr cat)) 189 | str)) 190 | (bm (assoc name (bound-and-true-p bookmark-alist))) 191 | (handler (or (bookmark-prop-get bm 'handler) 192 | 'bookmark-default-handler)) 193 | ((symbolp handler))) 194 | (orderless--match-p pred regexp 195 | (or (get handler 'bookmark-handler-type) 196 | (symbol-name handler))))))) 197 | 198 | (defun orderless-kwd-directory (pred regexp) 199 | "Match `default-directory' against PRED and REGEXP." 200 | (lambda (str) 201 | (when-let ((buf (orderless-kwd--get-buffer str))) 202 | (orderless--match-p pred regexp 203 | (buffer-local-value 'default-directory buf))))) 204 | 205 | (defun orderless-kwd-file (pred regexp) 206 | "Match `buffer-file-truename' against PRED and REGEXP." 207 | (lambda (str) 208 | (when-let ((buf (orderless-kwd--get-buffer str))) 209 | (orderless--match-p pred regexp 210 | (buffer-local-value 'buffer-file-truename buf))))) 211 | 212 | ;;;###autoload 213 | (defun orderless-kwd-dispatch (component _index _total) 214 | "Match COMPONENT against the keywords in `orderless-kwd-alist'." 215 | (when (and (not (equal component "")) 216 | (= (aref component 0) orderless-kwd-prefix)) 217 | (if-let ((len (length component)) 218 | (pos (or (string-match-p 219 | (rx-to-string `(any ,orderless-kwd-separator)) 220 | component 1) 221 | len)) 222 | (sym (intern-soft (substring component 1 pos))) 223 | (style (alist-get sym orderless-kwd-alist)) 224 | ((or (< (1+ pos) len) (cadr style)))) 225 | (cons (car style) (substring component (min (1+ pos) len))) 226 | #'ignore))) 227 | 228 | (provide 'orderless-kwd) 229 | ;;; orderless-kwd.el ends here 230 | -------------------------------------------------------------------------------- /orderless.el: -------------------------------------------------------------------------------- 1 | ;;; orderless.el --- Completion style for matching regexps in any order -*- lexical-binding: t; -*- 2 | 3 | ;; Copyright (C) 2021-2025 Free Software Foundation, Inc. 4 | 5 | ;; Author: Omar Antolín Camarena 6 | ;; Maintainer: Omar Antolín Camarena , Daniel Mendler 7 | ;; Keywords: matching, completion 8 | ;; Version: 1.4 9 | ;; URL: https://github.com/oantolin/orderless 10 | ;; Package-Requires: ((emacs "27.1") (compat "30")) 11 | 12 | ;; This file is part of GNU Emacs. 13 | 14 | ;; This program is free software; you can redistribute it and/or modify 15 | ;; it under the terms of the GNU General Public License as published by 16 | ;; the Free Software Foundation, either version 3 of the License, or 17 | ;; (at your option) any later version. 18 | 19 | ;; This program is distributed in the hope that it will be useful, 20 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 21 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 22 | ;; GNU General Public License for more details. 23 | 24 | ;; You should have received a copy of the GNU General Public License 25 | ;; along with this program. If not, see . 26 | 27 | ;;; Commentary: 28 | 29 | ;; This package provides an `orderless' completion style that divides 30 | ;; the pattern into components (space-separated by default), and 31 | ;; matches candidates that match all of the components in any order. 32 | 33 | ;; Completion styles are used as entries in the variables 34 | ;; `completion-styles' and `completion-category-overrides', see their 35 | ;; documentation. 36 | 37 | ;; To use this completion style you can use the following minimal 38 | ;; configuration: 39 | 40 | ;; (setq completion-styles '(orderless basic)) 41 | 42 | ;; You can customize the `orderless-component-separator' to decide how 43 | ;; the input pattern is split into component regexps. The default 44 | ;; splits on spaces. You might want to add hyphens and slashes, for 45 | ;; example, to ease completion of symbols and file paths, 46 | ;; respectively. 47 | 48 | ;; Each component can match in any one of several matching styles: 49 | ;; literally, as a regexp, as an initialism, in the flex style, or as 50 | ;; word prefixes. It is easy to add new styles: they are functions 51 | ;; from strings to strings that map a component to a regexp to match 52 | ;; against. The variable `orderless-matching-styles' lists the 53 | ;; matching styles to be used for components, by default it allows 54 | ;; literal and regexp matching. 55 | 56 | ;;; Code: 57 | 58 | (require 'compat) 59 | (eval-when-compile (require 'cl-lib)) 60 | 61 | (defgroup orderless nil 62 | "Completion method that matches space-separated regexps in any order." 63 | :link '(info-link :tag "Info Manual" "(orderless)") 64 | :link '(url-link :tag "Website" "https://github.com/oantolin/orderless") 65 | :link '(emacs-library-link :tag "Library Source" "orderless.el") 66 | :group 'minibuffer) 67 | 68 | (defface orderless-match-face-0 69 | '((default :weight bold) 70 | (((class color) (min-colors 88) (background dark)) :foreground "#72a4ff") 71 | (((class color) (min-colors 88) (background light)) :foreground "#223fbf") 72 | (t :foreground "blue")) 73 | "Face for matches of components numbered 0 mod 4.") 74 | 75 | (defface orderless-match-face-1 76 | '((default :weight bold) 77 | (((class color) (min-colors 88) (background dark)) :foreground "#ed92f8") 78 | (((class color) (min-colors 88) (background light)) :foreground "#8f0075") 79 | (t :foreground "magenta")) 80 | "Face for matches of components numbered 1 mod 4.") 81 | 82 | (defface orderless-match-face-2 83 | '((default :weight bold) 84 | (((class color) (min-colors 88) (background dark)) :foreground "#90d800") 85 | (((class color) (min-colors 88) (background light)) :foreground "#145a00") 86 | (t :foreground "green")) 87 | "Face for matches of components numbered 2 mod 4.") 88 | 89 | (defface orderless-match-face-3 90 | '((default :weight bold) 91 | (((class color) (min-colors 88) (background dark)) :foreground "#f0ce43") 92 | (((class color) (min-colors 88) (background light)) :foreground "#804000") 93 | (t :foreground "yellow")) 94 | "Face for matches of components numbered 3 mod 4.") 95 | 96 | (defcustom orderless-component-separator #'orderless-escapable-split-on-space 97 | "Component separators for orderless completion. 98 | This can either be a string, which is passed to `split-string', 99 | or a function of a single string argument." 100 | :type `(choice (const :tag "Spaces" " +") 101 | (const :tag "Spaces, hyphen or slash" " +\\|[-/]") 102 | (const :tag "Escapable space" 103 | ,#'orderless-escapable-split-on-space) 104 | (const :tag "Quotable spaces" ,#'split-string-and-unquote) 105 | (regexp :tag "Custom regexp") 106 | (function :tag "Custom function"))) 107 | 108 | (defcustom orderless-match-faces 109 | [orderless-match-face-0 110 | orderless-match-face-1 111 | orderless-match-face-2 112 | orderless-match-face-3] 113 | "Vector of faces used (cyclically) for component matches." 114 | :type '(vector face)) 115 | 116 | (defcustom orderless-matching-styles 117 | (list #'orderless-literal #'orderless-regexp) 118 | "List of component matching styles. 119 | If this variable is nil, regexp matching is assumed. 120 | 121 | A matching style is simply a function from strings to regexps. 122 | The returned regexps can be either strings or s-expressions in 123 | `rx' syntax. If the resulting regexp has no capturing groups, 124 | the entire match is highlighted, otherwise just the captured 125 | groups are. Several are provided with this package: try 126 | customizing this variable to see a list of them." 127 | :type 'hook 128 | :options (list #'orderless-regexp 129 | #'orderless-literal 130 | #'orderless-initialism 131 | #'orderless-prefixes 132 | #'orderless-flex)) 133 | 134 | (defcustom orderless-affix-dispatch-alist 135 | `((?% . ,#'char-fold-to-regexp) 136 | (?! . ,#'orderless-not) 137 | (?& . ,#'orderless-annotation) 138 | (?, . ,#'orderless-initialism) 139 | (?= . ,#'orderless-literal) 140 | (?^ . ,#'orderless-literal-prefix) 141 | (?~ . ,#'orderless-flex)) 142 | "Alist associating characters to matching styles. 143 | The function `orderless-affix-dispatch' uses this list to 144 | determine how to match a pattern component: if the component 145 | either starts or ends with a character used as a key in this 146 | alist, the character is removed from the component and the rest is 147 | matched according the style associated to it." 148 | :type `(alist 149 | :key-type character 150 | :value-type (choice 151 | (const :tag "Annotation" ,#'orderless-annotation) 152 | (const :tag "Literal" ,#'orderless-literal) 153 | (const :tag "Without literal" ,#'orderless-without-literal) 154 | (const :tag "Literal prefix" ,#'orderless-literal-prefix) 155 | (const :tag "Regexp" ,#'orderless-regexp) 156 | (const :tag "Not" ,#'orderless-not) 157 | (const :tag "Flex" ,#'orderless-flex) 158 | (const :tag "Initialism" ,#'orderless-initialism) 159 | (const :tag "Prefixes" ,#'orderless-prefixes) 160 | (const :tag "Ignore diacritics" ,#'char-fold-to-regexp) 161 | (function :tag "Custom matching style")))) 162 | 163 | (defun orderless-affix-dispatch (component _index _total) 164 | "Match COMPONENT according to the styles in `orderless-affix-dispatch-alist'. 165 | If the COMPONENT starts or ends with one of the characters used 166 | as a key in `orderless-affix-dispatch-alist', then that character 167 | is removed and the remainder of the COMPONENT is matched in the 168 | style associated to the character." 169 | (let ((len (length component)) 170 | (alist orderless-affix-dispatch-alist)) 171 | (when (> len 0) 172 | (cond 173 | ;; Ignore single dispatcher character 174 | ((and (= len 1) (alist-get (aref component 0) alist)) #'ignore) 175 | ;; Prefix 176 | ((when-let ((style (alist-get (aref component 0) alist))) 177 | (cons style (substring component 1)))) 178 | ;; Suffix 179 | ((when-let ((style (alist-get (aref component (1- len)) alist))) 180 | (cons style (substring component 0 -1)))))))) 181 | 182 | (defcustom orderless-style-dispatchers (list #'orderless-affix-dispatch) 183 | "List of style dispatchers. 184 | Style dispatchers are used to override the matching styles 185 | based on the actual component and its place in the list of 186 | components. A style dispatcher is a function that takes a string 187 | and two integers as arguments, it gets called with a component, 188 | the 0-based index of the component and the total number of 189 | components. It can decide what matching styles to use for the 190 | component and optionally replace the component with a different 191 | string, or it can decline to handle the component leaving it for 192 | future dispatchers. For details see `orderless--dispatch'. 193 | 194 | For example, a style dispatcher could arrange for the first 195 | component to match as an initialism and subsequent components to 196 | match as literals. As another example, a style dispatcher could 197 | arrange for a component starting with `~' to match the rest of 198 | the component in the `orderless-flex' style. See 199 | `orderless-affix-dispatch' and `orderless-affix-dispatch-alist' 200 | for such a configuration. For more information on how this 201 | variable is used, see `orderless-compile'." 202 | :type 'hook) 203 | 204 | (defcustom orderless-smart-case t 205 | "Whether to use smart case. 206 | If this variable is t, then case-sensitivity is decided as 207 | follows: if any component contains upper case letters, the 208 | matches are case sensitive; otherwise case-insensitive. This 209 | is like the behavior of `isearch' when `search-upper-case' is 210 | non-nil. 211 | 212 | On the other hand, if this variable is nil, then case-sensitivity 213 | is determined by the values of `completion-ignore-case', 214 | `read-file-name-completion-ignore-case' and 215 | `read-buffer-completion-ignore-case', as usual for completion." 216 | :type 'boolean) 217 | 218 | (defcustom orderless-expand-substring 'prefix 219 | "Whether to perform literal substring expansion. 220 | This configuration option affects the behavior of some completion 221 | interfaces when pressing TAB. If enabled `orderless-try-completion' 222 | will first attempt literal substring expansion. If disabled, 223 | expansion is only performed for single unique matches. For 224 | performance reasons only `prefix' expansion is enabled by default. 225 | Set the variable to `substring' for full substring expansion." 226 | :type '(choice (const :tag "No expansion" nil) 227 | (const :tag "Substring" substring) 228 | (const :tag "Prefix (efficient)" prefix))) 229 | 230 | ;;; Matching styles 231 | 232 | (defun orderless-regexp (component) 233 | "Match COMPONENT as a regexp." 234 | (condition-case nil 235 | (progn (string-match-p component "") component) 236 | (invalid-regexp nil))) 237 | 238 | (defun orderless-literal (component) 239 | "Match COMPONENT as a literal string." 240 | ;; Do not use (literal component) here, such that `delete-dups' in 241 | ;; `orderless--compile-component' has a chance to delete duplicates for 242 | ;; literal input. The default configuration of `orderless-matching-styles' 243 | ;; with `orderless-regexp' and `orderless-literal' leads to duplicates. 244 | (regexp-quote component)) 245 | 246 | (defun orderless-literal-prefix (component) 247 | "Match COMPONENT as a literal prefix string." 248 | `(seq bos (literal ,component))) 249 | 250 | (defun orderless--separated-by (sep rxs &optional before after) 251 | "Return a regexp to match the rx-regexps RXS with SEP in between. 252 | If BEFORE is specified, add it to the beginning of the rx 253 | sequence. If AFTER is specified, add it to the end of the rx 254 | sequence." 255 | (declare (indent 1)) 256 | `(seq 257 | ,(or before "") 258 | ,@(cl-loop for (sexp . more) on rxs 259 | collect `(group ,sexp) 260 | when more collect sep) 261 | ,(or after ""))) 262 | 263 | (defun orderless-flex (component) 264 | "Match a component in flex style. 265 | This means the characters in COMPONENT must occur in the 266 | candidate in that order, but not necessarily consecutively." 267 | `(seq 268 | ,@(cdr (cl-loop for char across component 269 | append `((zero-or-more (not ,char)) (group ,char)))))) 270 | 271 | (defun orderless-initialism (component) 272 | "Match a component as an initialism. 273 | This means the characters in COMPONENT must occur in the 274 | candidate, in that order, at the beginning of words." 275 | (orderless--separated-by '(zero-or-more nonl) 276 | (cl-loop for char across component collect `(seq word-start ,char)))) 277 | 278 | (defun orderless-prefixes (component) 279 | "Match a component as multiple word prefixes. 280 | The COMPONENT is split at word endings, and each piece must match 281 | at a word boundary in the candidate. This is similar to the 282 | `partial-completion' completion style." 283 | (orderless--separated-by '(zero-or-more nonl) 284 | (cl-loop for prefix in (split-string component "\\>") 285 | collect `(seq word-boundary ,prefix)))) 286 | 287 | (defun orderless-without-literal (component) 288 | "Match strings that do *not* contain COMPONENT as a literal match. 289 | You may prefer to use the more general `orderless-not' instead 290 | which can invert any predicate or regexp." 291 | `(seq 292 | (group string-start) ; highlight nothing! 293 | (zero-or-more 294 | (or ,@(cl-loop for i below (length component) 295 | collect `(seq ,(substring component 0 i) 296 | (or (not (any ,(aref component i))) 297 | string-end))))) 298 | string-end)) 299 | 300 | (defsubst orderless--match-p (pred regexp str) 301 | "Return t if STR matches PRED and REGEXP." 302 | (and str 303 | (or (not pred) (funcall pred str)) 304 | (or (not regexp) 305 | (let ((case-fold-search completion-ignore-case)) 306 | (string-match-p regexp str))))) 307 | 308 | (defun orderless-not (pred regexp) 309 | "Match strings that do *not* match PRED and REGEXP." 310 | (lambda (str) 311 | (not (orderless--match-p pred regexp str)))) 312 | 313 | (defun orderless--metadata () 314 | "Return completion metadata iff inside minibuffer." 315 | (when-let (((minibufferp)) 316 | (table minibuffer-completion-table)) 317 | ;; Return non-nil metadata iff inside minibuffer 318 | (or (completion-metadata (buffer-substring-no-properties 319 | (minibuffer-prompt-end) (point)) 320 | table minibuffer-completion-predicate) 321 | '((nil . nil))))) 322 | 323 | (defun orderless-annotation (pred regexp) 324 | "Match candidates where the annotation matches PRED and REGEXP." 325 | (let ((md (orderless--metadata))) 326 | (if-let ((fun (compat-call completion-metadata-get md 'affixation-function))) 327 | (lambda (str) 328 | (cl-loop for s in (cdar (funcall fun (list str))) 329 | thereis (orderless--match-p pred regexp s))) 330 | (when-let ((fun (compat-call completion-metadata-get md 'annotation-function))) 331 | (lambda (str) (orderless--match-p pred regexp (funcall fun str))))))) 332 | 333 | ;;; Highlighting matches 334 | 335 | (defun orderless--highlight (regexps ignore-case string) 336 | "Destructively propertize STRING to highlight a match of each of the REGEXPS. 337 | The search is case insensitive if IGNORE-CASE is non-nil." 338 | (cl-loop with case-fold-search = ignore-case 339 | with n = (length orderless-match-faces) 340 | for regexp in regexps and i from 0 341 | when (string-match regexp string) do 342 | (cl-loop 343 | for (x y) on (let ((m (match-data))) (or (cddr m) m)) by #'cddr 344 | when x do 345 | (add-face-text-property 346 | x y 347 | (aref orderless-match-faces (mod i n)) 348 | nil string))) 349 | string) 350 | 351 | (defun orderless-highlight-matches (regexps strings) 352 | "Highlight a match of each of the REGEXPS in each of the STRINGS. 353 | Warning: only use this if you know all REGEXPs match all STRINGS! 354 | For the user's convenience, if REGEXPS is a string, it is 355 | converted to a list of regexps according to the value of 356 | `orderless-matching-styles'." 357 | (when (stringp regexps) 358 | (setq regexps (cdr (orderless-compile regexps)))) 359 | (cl-loop with ignore-case = (orderless--ignore-case-p regexps) 360 | for str in strings 361 | collect (orderless--highlight regexps ignore-case (substring str)))) 362 | 363 | ;;; Compiling patterns to lists of regexps 364 | 365 | (defun orderless-escapable-split-on-space (string) 366 | "Split STRING on spaces, which can be escaped with backslash." 367 | (mapcar 368 | (lambda (piece) (replace-regexp-in-string (string 0) " " piece)) 369 | (split-string (replace-regexp-in-string 370 | "\\\\\\\\\\|\\\\ " 371 | (lambda (x) (if (equal x "\\ ") (string 0) x)) 372 | string 'fixedcase 'literal) 373 | " +" t))) 374 | 375 | (defun orderless--dispatch (dispatchers default string index total) 376 | "Run DISPATCHERS to compute matching styles for STRING. 377 | 378 | A style dispatcher is a function that takes a STRING, component 379 | INDEX and the TOTAL number of components. It should either 380 | return (a) nil to indicate the dispatcher will not handle the 381 | string, (b) a new string to replace the current string and 382 | continue dispatch, or (c) the matching styles to use and, if 383 | needed, a new string to use in place of the current one (for 384 | example, a dispatcher can decide which style to use based on a 385 | suffix of the string and then it must also return the component 386 | stripped of the suffix). 387 | 388 | More precisely, the return value of a style dispatcher can be of 389 | one of the following forms: 390 | 391 | - nil (to continue dispatching) 392 | 393 | - a string (to replace the component and continue dispatching), 394 | 395 | - a matching style or non-empty list of matching styles to 396 | return, 397 | 398 | - a `cons' whose `car' is either as in the previous case or 399 | nil (to request returning the DEFAULT matching styles), and 400 | whose `cdr' is a string (to replace the current one). 401 | 402 | This function tries all DISPATCHERS in sequence until one returns 403 | a list of styles. When that happens it returns a `cons' of the 404 | list of styles and the possibly updated STRING. If none of the 405 | DISPATCHERS returns a list of styles, the return value will use 406 | DEFAULT as the list of styles." 407 | (cl-loop for dispatcher in dispatchers 408 | for result = (funcall dispatcher string index total) 409 | if (stringp result) 410 | do (setq string result result nil) 411 | else if (and (consp result) (null (car result))) 412 | do (setf (car result) default) 413 | else if (and (consp result) (stringp (cdr result))) 414 | do (setq string (cdr result) result (car result)) 415 | when result return (cons result string) 416 | finally (return (cons default string)))) 417 | 418 | (defun orderless--compile-component (component index total styles dispatchers) 419 | "Compile COMPONENT at INDEX of TOTAL components with STYLES and DISPATCHERS." 420 | (cl-loop 421 | with pred = nil 422 | with (newsty . newcomp) = (orderless--dispatch dispatchers styles 423 | component index total) 424 | for style in (if (functionp newsty) (list newsty) newsty) 425 | for res = (condition-case nil 426 | (funcall style newcomp) 427 | (wrong-number-of-arguments 428 | (when-let ((res (orderless--compile-component 429 | newcomp index total styles dispatchers))) 430 | (funcall style (car res) (cdr res))))) 431 | if (functionp res) do (cl-callf orderless--predicate-and pred res) 432 | else if res collect (if (stringp res) `(regexp ,res) res) into regexps 433 | finally return 434 | (when (or pred regexps) 435 | (cons pred (and regexps (rx-to-string `(or ,@(delete-dups regexps)) t)))))) 436 | 437 | (defun orderless-compile (pattern &optional styles dispatchers) 438 | "Build regexps to match the components of PATTERN. 439 | Split PATTERN on `orderless-component-separator' and compute 440 | matching styles for each component. For each component the style 441 | DISPATCHERS are run to determine the matching styles to be used; 442 | they are called with arguments the component, the 0-based index 443 | of the component and the total number of components. If the 444 | DISPATCHERS decline to handle the component, then the list of 445 | matching STYLES is used. See `orderless--dispatch' for details 446 | on dispatchers. 447 | 448 | The STYLES default to `orderless-matching-styles', and the 449 | DISPATCHERS default to `orderless-dipatchers'. Since nil gets 450 | you the default, if you want no dispatchers to be run, use 451 | \\='(ignore) as the value of DISPATCHERS. 452 | 453 | The return value is a pair of a predicate function and a list of 454 | regexps. The predicate function can also be nil. It takes a 455 | string as argument." 456 | (unless styles (setq styles orderless-matching-styles)) 457 | (unless dispatchers (setq dispatchers orderless-style-dispatchers)) 458 | (cl-loop 459 | with predicate = nil 460 | with components = (if (functionp orderless-component-separator) 461 | (funcall orderless-component-separator pattern) 462 | (split-string pattern orderless-component-separator t)) 463 | with total = (length components) 464 | for comp in components and index from 0 465 | for (pred . regexp) = (orderless--compile-component 466 | comp index total styles dispatchers) 467 | when regexp collect regexp into regexps 468 | when pred do (cl-callf orderless--predicate-and predicate pred) 469 | finally return (cons predicate regexps))) 470 | 471 | ;;; Completion style implementation 472 | 473 | (defun orderless--predicate-normalized-and (p q) 474 | "Combine two predicate functions P and Q with `and'. 475 | The first function P is a completion predicate which can receive 476 | up to two arguments. The second function Q always receives a 477 | normalized string as argument." 478 | (cond 479 | ((and p q) 480 | (lambda (k &rest v) ;; v for hash table 481 | (when (if v (funcall p k (car v)) (funcall p k)) 482 | (setq k (if (consp k) (car k) k)) ;; alist 483 | (funcall q (if (symbolp k) (symbol-name k) k))))) 484 | (q 485 | (lambda (k &optional _) ;; _ for hash table 486 | (setq k (if (consp k) (car k) k)) ;; alist 487 | (funcall q (if (symbolp k) (symbol-name k) k)))) 488 | (p))) 489 | 490 | (defun orderless--predicate-and (p q) 491 | "Combine two predicate functions P and Q with `and'." 492 | (or (and p q (lambda (x) (and (funcall p x) (funcall q x)))) p q)) 493 | 494 | (defun orderless--compile (string table pred) 495 | "Compile STRING to a prefix and a list of regular expressions. 496 | The predicate PRED is used to constrain the entries in TABLE." 497 | (pcase-let* ((limit (car (completion-boundaries string table pred ""))) 498 | (prefix (substring string 0 limit)) 499 | (pattern (substring string limit)) 500 | (`(,fun . ,regexps) (orderless-compile pattern))) 501 | (list prefix regexps (orderless--ignore-case-p pattern) 502 | (orderless--predicate-normalized-and pred fun)))) 503 | 504 | ;; Thanks to @jakanakaevangeli for writing a version of this function: 505 | ;; https://github.com/oantolin/orderless/issues/79#issuecomment-916073526 506 | (defun orderless--literal-prefix-p (regexp) 507 | "Determine if REGEXP is a quoted regexp anchored at the beginning. 508 | If REGEXP is of the form \"\\`q\" for q = (regexp-quote u), 509 | then return (cons REGEXP u); else return nil." 510 | (when (and (string-prefix-p "\\`" regexp) 511 | (not (string-match-p "[$*+.?[\\^]" 512 | (replace-regexp-in-string 513 | "\\\\[$*+.?[\\^]" "" regexp 514 | 'fixedcase 'literal nil 2)))) 515 | (cons regexp 516 | (replace-regexp-in-string "\\\\\\([$*+.?[\\^]\\)" "\\1" 517 | regexp 'fixedcase nil nil 2)))) 518 | 519 | (defun orderless--ignore-case-p (regexps) 520 | "Return non-nil if case should be ignored for REGEXPS." 521 | (if orderless-smart-case 522 | (cl-loop for regexp in (ensure-list regexps) 523 | always (isearch-no-upper-case-p regexp t)) 524 | completion-ignore-case)) 525 | 526 | (defun orderless--filter (prefix regexps ignore-case table pred) 527 | "Filter TABLE by PREFIX, REGEXPS and PRED. 528 | The matching should be case-insensitive if IGNORE-CASE is non-nil." 529 | ;; If there is a regexp of the form \`quoted-regexp then 530 | ;; remove the first such and add the unquoted form to the prefix. 531 | (pcase (cl-loop for r in regexps 532 | thereis (orderless--literal-prefix-p r)) 533 | (`(,regexp . ,literal) 534 | (setq prefix (concat prefix literal) 535 | regexps (remove regexp regexps)))) 536 | (let ((completion-regexp-list regexps) 537 | (completion-ignore-case ignore-case)) 538 | (all-completions prefix table pred))) 539 | 540 | (defun orderless-filter (string table &optional pred) 541 | "Split STRING into components and find entries TABLE matching all. 542 | The predicate PRED is used to constrain the entries in TABLE." 543 | (pcase-let ((`(,prefix ,regexps ,ignore-case ,pred) 544 | (orderless--compile string table pred))) 545 | (orderless--filter prefix regexps ignore-case table pred))) 546 | 547 | ;;;###autoload 548 | (defun orderless-all-completions (string table pred _point) 549 | "Split STRING into components and find entries TABLE matching all. 550 | The predicate PRED is used to constrain the entries in TABLE. The 551 | matching portions of each candidate are highlighted. 552 | This function is part of the `orderless' completion style." 553 | (pcase-let ((`(,prefix ,regexps ,ignore-case ,pred) 554 | (orderless--compile string table pred))) 555 | (when-let ((completions (orderless--filter prefix regexps ignore-case table pred))) 556 | (if completion-lazy-hilit 557 | (setq completion-lazy-hilit-fn 558 | (apply-partially #'orderless--highlight regexps ignore-case)) 559 | (cl-loop for str in-ref completions do 560 | (setf str (orderless--highlight regexps ignore-case (substring str))))) 561 | (nconc completions (length prefix))))) 562 | 563 | ;;;###autoload 564 | (defun orderless-try-completion (string table pred point) 565 | "Complete STRING to unique matching entry in TABLE. 566 | This uses `orderless-all-completions' to find matches for STRING 567 | in TABLE among entries satisfying PRED. If there is only one 568 | match, it completes to that match. If there are no matches, it 569 | returns nil. In any other case it \"completes\" STRING to 570 | itself, without moving POINT. 571 | This function is part of the `orderless' completion style." 572 | (or 573 | (pcase orderless-expand-substring 574 | ('nil nil) 575 | ('prefix (completion-emacs21-try-completion string table pred point)) 576 | (_ (completion-substring-try-completion string table pred point))) 577 | (catch 'orderless--many 578 | (pcase-let ((`(,prefix ,regexps ,ignore-case ,pred) 579 | (orderless--compile string table pred)) 580 | (one nil)) 581 | ;; Abuse all-completions/orderless--filter as a fast search loop. 582 | ;; Should be almost allocation-free since our "predicate" is not 583 | ;; called more than two times. 584 | (orderless--filter 585 | prefix regexps ignore-case table 586 | (orderless--predicate-normalized-and 587 | pred 588 | (lambda (arg) 589 | ;; Check if there is more than a single match (= many). 590 | (when (and one (not (equal one arg))) 591 | (throw 'orderless--many (cons string point))) 592 | (setq one arg) 593 | t))) 594 | (when one 595 | ;; Prepend prefix if the candidate does not already have the same 596 | ;; prefix. This workaround is needed since the predicate may either 597 | ;; receive an unprefixed or a prefixed candidate as argument. Most 598 | ;; completion tables consistently call the predicate with unprefixed 599 | ;; candidates, for example `completion-file-name-table'. In contrast, 600 | ;; `completion-table-with-context' calls the predicate with prefixed 601 | ;; candidates. This could be an unintended bug or oversight in 602 | ;; `completion-table-with-context'. 603 | (unless (or (equal prefix "") 604 | (and (string-prefix-p prefix one) 605 | (test-completion one table pred))) 606 | (setq one (concat prefix one))) 607 | (or (equal string one) ;; Return t for unique exact match 608 | (cons one (length one)))))))) 609 | 610 | ;;;###autoload 611 | (add-to-list 'completion-styles-alist 612 | '(orderless 613 | orderless-try-completion orderless-all-completions 614 | "Completion of multiple components, in any order.")) 615 | 616 | (defmacro orderless-define-completion-style 617 | (name &optional docstring &rest configuration) 618 | "Define an orderless completion style with given CONFIGURATION. 619 | The CONFIGURATION should be a list of bindings that you could use 620 | with `let' to configure orderless. You can include bindings for 621 | `orderless-matching-styles' and `orderless-style-dispatchers', 622 | for example. 623 | 624 | The completion style consists of two functions that this macro 625 | defines for you, NAME-try-completion and NAME-all-completions. 626 | This macro registers those in `completion-styles-alist' as 627 | forming the completion style NAME. 628 | 629 | The optional DOCSTRING argument is used as the documentation 630 | string for the completion style." 631 | (declare (doc-string 2) (indent 1)) 632 | (unless (stringp docstring) 633 | (push docstring configuration) 634 | (setq docstring nil)) 635 | (let* ((fn-name (lambda (string) (intern (concat (symbol-name name) string)))) 636 | (try-completion (funcall fn-name "-try-completion")) 637 | (all-completions (funcall fn-name "-all-completions")) 638 | (doc-fmt "`%s' function for the %s style. 639 | This function delegates to `orderless-%s'. 640 | The orderless configuration is locally modified 641 | specifically for the %s style.") 642 | (fn-doc (lambda (fn) (format doc-fmt fn name fn name name)))) 643 | `(progn 644 | (defun ,try-completion (string table pred point) 645 | ,(funcall fn-doc "try-completion") 646 | (let ,configuration 647 | (orderless-try-completion string table pred point))) 648 | (defun ,all-completions (string table pred point) 649 | ,(funcall fn-doc "all-completions") 650 | (let ,configuration 651 | (orderless-all-completions string table pred point))) 652 | (add-to-list 'completion-styles-alist 653 | '(,name ,try-completion ,all-completions ,docstring))))) 654 | 655 | ;;; Ivy integration 656 | 657 | ;;;###autoload 658 | (defun orderless-ivy-re-builder (str) 659 | "Convert STR into regexps for use with ivy. 660 | This function is for integration of orderless with ivy, use it as 661 | a value in `ivy-re-builders-alist'." 662 | (or (mapcar (lambda (x) (cons x t)) (cdr (orderless-compile str))) "")) 663 | 664 | (defvar ivy-regex) 665 | (defun orderless-ivy-highlight (str) 666 | "Highlight a match in STR of each regexp in `ivy-regex'. 667 | This function is for integration of orderless with ivy." 668 | (orderless--highlight (mapcar #'car ivy-regex) t str) str) 669 | 670 | (provide 'orderless) 671 | ;;; orderless.el ends here 672 | -------------------------------------------------------------------------------- /orderless.texi: -------------------------------------------------------------------------------- 1 | \input texinfo @c -*- texinfo -*- 2 | @c %**start of header 3 | @setfilename orderless.info 4 | @settitle Orderless 5 | @documentencoding UTF-8 6 | @documentlanguage en 7 | @c %**end of header 8 | 9 | @dircategory Emacs misc features 10 | @direntry 11 | * Orderless: (orderless). Completion style for matching regexps in any order. 12 | @end direntry 13 | 14 | @finalout 15 | @titlepage 16 | @title Orderless 17 | @author Omar Antolín Camarena 18 | @end titlepage 19 | 20 | @contents 21 | 22 | @ifnottex 23 | @node Top 24 | @top Orderless 25 | @end ifnottex 26 | 27 | @menu 28 | * Overview:: 29 | * Customization:: 30 | * Integration with other completion UIs:: 31 | * Related packages:: 32 | 33 | @detailmenu 34 | --- The Detailed Node Listing --- 35 | 36 | Customization 37 | 38 | * Component matching styles:: 39 | * Component separator regexp:: 40 | * Defining custom orderless styles:: 41 | * Faces for component matches:: 42 | * Pattern compiler:: 43 | * Interactively changing the configuration:: 44 | 45 | Component matching styles 46 | 47 | * Style modifiers:: 48 | * Style dispatchers:: 49 | 50 | Integration with other completion UIs 51 | 52 | * Ivy:: 53 | * Helm:: 54 | * Company:: 55 | 56 | Related packages 57 | 58 | * Ivy and Helm:: 59 | * Prescient:: 60 | * Restricting to current matches in Icicles, Ido and Ivy: Restricting to current matches in Icicles Ido and Ivy. 61 | 62 | @end detailmenu 63 | @end menu 64 | 65 | @node Overview 66 | @chapter Overview 67 | 68 | This package provides an @samp{orderless} @emph{completion style} that divides the 69 | pattern into space-separated components, and matches candidates that 70 | match all of the components in any order. Each component can match in 71 | any one of several ways: literally, as a regexp, as an initialism, in 72 | the flex style, or as multiple word prefixes. By default, regexp and 73 | literal matches are enabled. 74 | 75 | A completion style is a back-end for completion and is used from a 76 | front-end that provides a completion UI@. Any completion style can be 77 | used with the default Emacs completion UI (sometimes called minibuffer 78 | tab completion), with the built-in Icomplete package (which is similar 79 | to the more well-known Ido Mode), the icomplete-vertical variant from 80 | Emacs 28 (see the external @uref{https://github.com/oantolin/icomplete-vertical, icomplete-vertical} package to get that 81 | functionality on earlier versions of Emacs), or with some third party 82 | minibuffer completion frameworks such as @uref{https://gitlab.com/protesilaos/mct, Mct} or @uref{https://github.com/minad/vertico, Vertico}. 83 | 84 | All the completion UIs just mentioned are for minibuffer completion, 85 | used when Emacs commands prompt the user in the minibuffer for some 86 | input, but there is also completion at point in normal buffers, 87 | typically used for identifiers in programming languages. Completion 88 | styles can also be used for that purpose by completion at point UIs 89 | such as @uref{https://github.com/minad/corfu, Corfu}, @uref{https://company-mode.github.io/, Company} or the function @samp{consult-completion-in-region} 90 | from @uref{https://github.com/minad/consult, Consult}. 91 | 92 | To use a completion style with any of the above mentioned completion 93 | UIs simply add it as an entry in the variables @samp{completion-styles} and 94 | @samp{completion-category-overrides} and @samp{completion-category-defaults} (see 95 | their documentation). 96 | 97 | The @samp{completion-category-defaults} variable serves as a default value 98 | for @samp{completion-category-overrides}. If you want to use @samp{orderless} 99 | exclusively, set both variables to @samp{nil}, but be aware that 100 | @samp{completion-category-defaults} is modified by packages at load time. 101 | 102 | With a bit of effort, it might still be possible to use @samp{orderless} with 103 | other completion UIs, even if those UIs don't support the standard 104 | Emacs completion styles. Currently there is support for @uref{https://github.com/abo-abo/swiper, Ivy} (see 105 | below). Also, while Company does support completion styles directly, 106 | pressing @samp{SPC} takes you out of completion, so comfortably using 107 | @samp{orderless} with it takes a bit of configuration (see below). 108 | 109 | If you use ELPA or MELPA, the easiest way to install @samp{orderless} is via 110 | @samp{package-install}. If you use @samp{use-package}, you can use: 111 | 112 | @lisp 113 | (use-package orderless 114 | :ensure t 115 | :custom 116 | (completion-styles '(orderless basic)) 117 | (completion-category-overrides '((file (styles basic partial-completion))))) 118 | @end lisp 119 | 120 | Alternatively, put @samp{orderless.el} somewhere on your @samp{load-path}, and use 121 | the following configuration: 122 | 123 | @lisp 124 | (require 'orderless) 125 | (setq completion-styles '(orderless basic) 126 | completion-category-overrides '((file (styles basic partial-completion)))) 127 | @end lisp 128 | 129 | The @samp{basic} completion style is specified as fallback in addition to 130 | @samp{orderless} in order to ensure that completion commands which rely on 131 | dynamic completion tables, e.g., @code{completion-table-dynamic} or 132 | @code{completion-table-in-turn}, work correctly. Furthermore the @samp{basic} 133 | completion style needs to be tried @emph{first} (not as a fallback) for TRAMP 134 | hostname completion to work. In order to achieve that, we add an entry 135 | for the @samp{file} completion category in the @samp{completion-category-overrides} 136 | variable. In addition, the @samp{partial-completion} style allows you to use 137 | wildcards for file completion and partial paths, e.g., @code{/u/s/l} for 138 | @code{/usr/share/local}. 139 | 140 | Bug reports are highly welcome and appreciated! 141 | 142 | @node Customization 143 | @chapter Customization 144 | 145 | @menu 146 | * Component matching styles:: 147 | * Component separator regexp:: 148 | * Defining custom orderless styles:: 149 | * Faces for component matches:: 150 | * Pattern compiler:: 151 | * Interactively changing the configuration:: 152 | @end menu 153 | 154 | @node Component matching styles 155 | @section Component matching styles 156 | 157 | Each component of a pattern can match in any of several matching 158 | styles. A matching style is a function from strings to regexps or 159 | predicates, so it is easy to define new matching styles. The value 160 | returned by a matching style can be either a regexp as a string, an 161 | s-expression in @samp{rx} syntax or a predicate function. The predefined 162 | matching styles are: 163 | 164 | @table @asis 165 | @item orderless-regexp 166 | the component is treated as a regexp that must 167 | match somewhere in the candidate. 168 | 169 | If the component is not a valid regexp, it is ignored. 170 | 171 | @item orderless-literal 172 | the component is treated as a literal string 173 | that must occur in the candidate. 174 | 175 | @item orderless-literal-prefix 176 | the component is treated as a literal 177 | string that must occur as a prefix of a candidate. 178 | 179 | @item orderless-prefixes 180 | the component is split at word endings and 181 | each piece must match at a word boundary in the candidate, occurring 182 | in that order. 183 | 184 | This is similar to the built-in @samp{partial-completion} completion-style. 185 | For example, @samp{re-re} matches @samp{query-replace-regexp}, @samp{recode-region} and 186 | @samp{magit-remote-list-refs}; @samp{f-d.t} matches @samp{final-draft.txt}. 187 | 188 | @item orderless-initialism 189 | each character of the component should appear 190 | as the beginning of a word in the candidate, in order. 191 | 192 | This maps @samp{abc} to @samp{\