├── .elpaignore ├── .gitignore ├── .travis.yml ├── LICENSE ├── Makefile ├── README.org ├── macrostep-c.el ├── macrostep-test.el └── macrostep.el /.elpaignore: -------------------------------------------------------------------------------- 1 | .travis.yml 2 | LICENSE 3 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.elc 2 | *~ 3 | 4 | # ELPA-generated files 5 | /macrostep-autoloads.el 6 | /macrostep-pkg.el 7 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: emacs 2 | 3 | env: 4 | - EMACS=emacs23 5 | - EMACS=emacs24 6 | - EMACS=emacs-snapshot 7 | 8 | matrix: 9 | allow_failures: 10 | - env: EMACS=emacs-snapshot 11 | 12 | install: 13 | - if [ "$EMACS" = "emacs23" ]; then 14 | sudo apt-get -qq update && 15 | sudo apt-get -qq -f install && 16 | sudo apt-get -qq install emacs23-nox; 17 | fi 18 | - if [ "$EMACS" = "emacs24" ]; then 19 | sudo add-apt-repository -y ppa:cassou/emacs && 20 | sudo apt-get -qq update && 21 | sudo apt-get -qq -f install && 22 | sudo apt-get -qq install emacs24-nox; 23 | fi 24 | - if [ "$EMACS" = 'emacs-snapshot' ]; then 25 | sudo add-apt-repository -y ppa:ubuntu-elisp/ppa && 26 | sudo apt-get -qq update && 27 | sudo apt-get -qq -f install && 28 | sudo apt-get -qq install emacs-snapshot && 29 | sudo apt-get -qq install emacs-snapshot-el; 30 | fi 31 | 32 | script: 33 | - make test EMACS=$EMACS 34 | 35 | notifications: 36 | email: false 37 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | EMACS ?= emacs 2 | 3 | all: macrostep.elc macrostep-c.elc 4 | 5 | clean: 6 | rm -f *.elc 7 | 8 | test: clean all 9 | $(EMACS) --batch -L . --load macrostep-test.el 10 | 11 | sandbox: all 12 | $(EMACS) -Q -L . --load macrostep --load macrostep-c 13 | 14 | %.elc: %.el 15 | $(EMACS) --batch -L . --funcall batch-byte-compile "$<" 16 | 17 | .PHONY: test all clean 18 | -------------------------------------------------------------------------------- /README.org: -------------------------------------------------------------------------------- 1 | * macrostep: interactive macro-expander 2 | 3 | =macrostep= is an Emacs minor mode for interactively stepping 4 | through the expansion of macros in Emacs Lisp source code. It lets 5 | you see exactly what happens at each step of the expansion process 6 | by pretty-printing the expanded forms inline in the source buffer, 7 | which is temporarily read-only while macro expansions are visible. 8 | You can expand and collapse macro forms one step at a time, and 9 | evaluate or instrument the expansions for debugging with Edebug as 10 | normal (but see "Bugs and known limitations", below). 11 | Single-stepping through the expansion is particularly useful for 12 | debugging macros that expand into another macro form. These can be 13 | difficult to debug with Emacs' built-in =macroexpand=, which 14 | continues expansion until the top-level form is no longer a macro 15 | call. 16 | 17 | Both globally-visible macros as defined by =defmacro= and local 18 | macros bound by =(cl-)macrolet= or another macro-defining form can 19 | be expanded. Within macro expansions, calls to macros and compiler 20 | macros are fontified specially: macro forms using 21 | =macrostep-macro-face=, and functions with compiler macros using 22 | =macrostep-compiler-macro-face=. Uninterned symbols (gensyms) are 23 | fontified based on which step in the expansion created them, to 24 | distinguish them both from normal symbols and from other gensyms 25 | with the same print name. 26 | 27 | As of version 0.9, it is also possible to extend =macrostep= to 28 | work with other languages with macro systems in addition to Emacs 29 | Lisp. An extension for Common Lisp (via SLIME) is in the works; 30 | contributions for other languages are welcome. See "Extending 31 | macrostep" below for details. 32 | 33 | ** Installation 34 | 35 | Install =macrostep= from Emacs with =M-x package-install macrostep=. 36 | 37 | =macrostep= is available on [[https://elpa.nongnu.org/][ NonGNU ELPA.]] 38 | For further details, see [[https://elpa.nongnu.org/nongnu/macrostep.html][the macrostep page.]] 39 | 40 | ** Key-bindings and usage 41 | The standard keybindings in =macrostep-mode= are the following: 42 | 43 | - e, =, RET :: expand the macro form following point one step 44 | - c, u, DEL :: collapse the form following point 45 | - q, C-c C-c :: collapse all expanded forms and exit macrostep-mode 46 | - n, TAB :: jump to the next macro form in the expansion 47 | - p, M-TAB :: jump to the previous macro form in the expansion 48 | 49 | It's not very useful to enable and disable macrostep-mode 50 | directly. Instead, bind =macrostep-expand= to a key in 51 | =emacs-lisp-mode-map=, for example C-c e: 52 | 53 | #+BEGIN_SRC emacs-lisp 54 | (define-key emacs-lisp-mode-map (kbd "C-c e") 'macrostep-expand) 55 | #+END_SRC 56 | 57 | You can then enter macrostep-mode and expand a macro form 58 | completely by typing =C-c e e e ...= as many times as necessary. 59 | 60 | Exit macrostep-mode by typing =q= or =C-c C-c=, or by successively 61 | typing =c= to collapse all surrounding expansions. 62 | 63 | ** Customization options 64 | Type =M-x customize-group RET macrostep RET= to customize options 65 | and faces. 66 | 67 | To display macro expansions in a separate window, instead of inline 68 | in the source buffer, customize 69 | =macrostep-expand-in-separate-buffer= to =t=. The default is 70 | =nil=. Whichever default behavior is selected, the alternative 71 | behavior can be obtained temporarily by giving a prefix argument to 72 | =macrostep-expand=. 73 | 74 | To have =macrostep= ignore compiler macros, customize 75 | =macrostep-expand-compiler-macros= to =nil=. The default is =t=. 76 | 77 | Customize the faces =macrostep-macro-face=, 78 | =macrostep-compiler-macro-face=, and =macrostep-gensym-1= through 79 | =macrostep-gensym-5= to alter the appearance of macro expansions. 80 | 81 | ** Locally-bound macros 82 | As of version 0.9, =macrostep= can expand calls to a locally-bound 83 | macro, whether defined by a surrounding =(cl-)macrolet= form, or by 84 | another macro-defining macro. In other words, it is possible to 85 | expand the inner =local-macro= forms in both the following 86 | examples, whether =local-macro= is defined by an enclosing 87 | =cl-macrolet= -- 88 | 89 | #+BEGIN_SRC emacs-lisp 90 | (cl-macrolet ((local-macro (&rest args) 91 | `(expansion of ,args))) 92 | (local-macro (do-something))) 93 | #+END_SRC 94 | 95 | -- or by a macro which expands into =cl-macrolet=, provided that 96 | its definition of macro is evaluated prior to calling 97 | =macrostep-expand=: 98 | 99 | #+BEGIN_SRC emacs-lisp 100 | (defmacro with-local-macro (&rest body) 101 | `(cl-macrolet ((local-macro (&rest args) 102 | `(expansion of ,args))) 103 | ,@body)) 104 | 105 | (with-local-macro 106 | (local-macro (do something (else))) 107 | #+END_SRC 108 | 109 | See the =with-js= macro in Emacs's =js.el= for a real example of 110 | the latter kind of macro. 111 | 112 | Expansion of locally-bound macros is implemented by instrumenting 113 | Emacs Lisp's macro-expander to capture the environment at point. A 114 | similar trick is used to detect macro- and compiler-macro calls 115 | within expanded text so that they can be fontified accurately. 116 | 117 | ** Expanding sub-forms 118 | By moving point around in the macro expansion using 119 | =macrostep-next-macro= and =macrostep-prev-macro= (bound to the =n= 120 | and =p= keys), it is possible to expand other macro calls within 121 | the expansion before expanding the outermost form. This can 122 | sometimes be useful, although it does not correspond to the real 123 | order of macro expansion in Emacs Lisp, which proceeds by fully 124 | expanding the outer form to a non-macro form before expanding 125 | sub-forms. 126 | 127 | The main reason to expand sub-forms out of order is to help with 128 | debugging macros which programmatically expand their arguments in 129 | order to rewrite them. Expanding the arguments of such a macro 130 | lets you visualise what the macro definition would compute via 131 | =macroexpand-all=. 132 | 133 | ** Extending macrostep for other languages 134 | Since version 0.9, it is possible to extend macrostep to work with 135 | other languages besides Emacs Lisp. In typical Emacs fashion, this 136 | is implemented by setting buffer-local variables to different 137 | function values. Six buffer-local variables define the 138 | language-specific part of the implementation: 139 | 140 | - =macrostep-sexp-bounds-function= 141 | - =macrostep-sexp-at-point-function= 142 | - =macrostep-environment-at-point-function= 143 | - =macrostep-expand-1-function= 144 | - =macrostep-print-function= 145 | - =macrostep-macro-form-p-function= 146 | 147 | Typically, an implementation for another language would set these 148 | variables in a major-mode hook. See the docstrings of each 149 | variable for details on how each one is called and what it should 150 | return. At a minimum, another language implementation needs to 151 | provide =macrostep-sexp-at-point-function=, 152 | =macrostep-expand-1-function=, and =macrostep-print-function=. 153 | Lisp-like languages may be able to reuse the default 154 | =macrostep-sexp-bounds-function= if they provide another 155 | implementation of =macrostep-macro-form-p-function=. Languages 156 | which do not implement locally-defined macros can set 157 | =macrostep-environment-at-point-function= to =ignore=. 158 | 159 | Note that the core =macrostep= machinery only interprets the return 160 | value of =macrostep-sexp-bounds-function=, so implementations for 161 | other languages can use any internal representations of code and 162 | environments which is convenient. Although the terminology is 163 | Lisp-specific, there is no reason that implementations could not be 164 | provided for non-Lisp languages with macro systems, provided there 165 | is some way of identifying macro calls and calling the compiler / 166 | preprocessor to obtain their expansions. 167 | 168 | ** Bugs and known limitations 169 | You can evaluate and edebug macro-expanded forms and step through 170 | the macro-expanded version, but the form that =eval-defun= and 171 | friends read from the buffer won't have the uninterned symbols of 172 | the real macro expansion. This will probably work OK with CL-style 173 | gensyms, but may cause problems with =make-symbol= symbols if they 174 | have the same print name as another symbol in the expansion. It's 175 | possible that using =print-circle= and =print-gensym= could get 176 | around this. 177 | 178 | Please send other bug reports and feature requests to the author. 179 | 180 | ** Acknowledgements 181 | Thanks to: 182 | - John Wiegley for fixing a bug with the face definitions under 183 | Emacs 24 & for plugging macrostep in his [[http://youtu.be/RvPFZL6NJNQ][EmacsConf presentation]]! 184 | - George Kettleborough for bug reports, and patches to highlight 185 | the expanded region and properly handle backquotes. 186 | - Nic Ferrier for suggesting support for local definitions within 187 | macrolet forms 188 | - Luís Oliveira for suggesting and implementing SLIME support 189 | 190 | =macrostep= was originally inspired by J. V. Toups's 'Deep Emacs 191 | Lisp' articles ([[http://dorophone.blogspot.co.uk/2011/04/deep-emacs-part-1.html][part 1]], [[http://dorophone.blogspot.co.uk/2011/04/deep-emacs-lisp-part-2.html][part 2]], [[http://dorophone.blogspot.co.uk/2011/05/monadic-parser-combinators-in-elisp.html][screencast]]). 192 | 193 | ** Changelog 194 | - v0.9.5, 2024-02-01: 195 | - documentation improvements 196 | - v0.9.4, 2024-05-09: 197 | - add compat dependency for defvar-keymap 198 | - v0.9.3, 2024-04-30: 199 | - code simplifications, checkdoc fixes. 200 | - v0.9.2, 2023-05-12: 201 | - name the keymap macrostep-mode-map, fixing a regression in v0.9.1 202 | - v0.9.1, 2023-03-12: 203 | - bug fixes, cleanup and modernization 204 | - v0.9, 2015-10-01: 205 | - separate into Elisp-specific and generic components 206 | - highlight and expand compiler macros 207 | - improve local macro expansion and macro form identification by 208 | instrumenting =macroexpand(-all)= 209 | - v0.8, 2014-05-29: fix a bug with printing the first element of 210 | lists 211 | - v0.7, 2014-05-11: expand locally-defined macros within 212 | =(cl-)macrolet= forms 213 | - v0.6, 2013-05-04: better handling of quote and backquote 214 | - v0.5, 2013-04-16: highlight region, maintain cleaner buffer state 215 | - v0.4, 2013-04-07: only enter macrostep-mode on successful 216 | macro-expansion 217 | - v0.3, 2012-10-30: print dotted lists correctly. autoload 218 | definitions. 219 | 220 | * Contributions 221 | 222 | Please note that as this package is intended to be part of Emacs soon, 223 | non-trivial code contributions require FSF copyright assignment prior 224 | to acceptance. 225 | 226 | The copyright assignment policy is at 227 | https://www.fsf.org/licensing/contributor-faq 228 | 229 | Any legally significant contributions can only be merged after the 230 | author has completed their paperwork. 231 | https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html#Legally-Significant 232 | #+OPTIONS: author:nil email:nil toc:nil timestamp:nil 233 | -------------------------------------------------------------------------------- /macrostep-c.el: -------------------------------------------------------------------------------- 1 | ;;; macrostep-c.el --- macrostep interface to C preprocessor -*- lexical-binding: t; -*- 2 | 3 | ;; Copyright (C) 2015 Jon Oddie 4 | ;; Copyright (C) 2020-2025 Free Software Foundation, Inc. 5 | 6 | ;; Author: Jon Oddie 7 | ;; Maintainer: Jeremy Bryant 8 | ;; Url: https://github.com/emacsorphanage/macrostep 9 | ;; Keywords: c, languages, macro, debugging 10 | 11 | ;; SPDX-License-Identifier: GPL-3.0-or-later 12 | 13 | ;; This file is free software: you can redistribute it and/or modify 14 | ;; it under the terms of the GNU General Public License as published 15 | ;; by the Free Software Foundation, either version 3 of the License, 16 | ;; or (at your option) any later version. 17 | ;; 18 | ;; This file is distributed in the hope that it will be useful, 19 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 20 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 21 | ;; GNU General Public License for more details. 22 | ;; 23 | ;; You should have received a copy of the GNU General Public License 24 | ;; along with this file. If not, see . 25 | 26 | ;;; Commentary: 27 | 28 | ;; A thin wrapper around Emacs's built-in `cmacexp' library to provide 29 | ;; basic support for expanding C macros using the `macrostep' user 30 | ;; interface. To use, position point on a macro use in a C buffer and 31 | ;; type `M-x macrostep-expand'. The variables `c-macro-preprocessor' 32 | ;; and especially `c-macro-cppflags' may need to be set correctly for 33 | ;; accurate expansion. 34 | 35 | ;; This is fairly basic compared to the Emacs Lisp `macrostep'. In 36 | ;; particular, there is no step-by-step expansion, since C macros are 37 | ;; expanded in a single "cpp" pass, and no pretty-printing. 38 | 39 | ;; To hide the buffer containing "cpp" warnings (not recommended), you 40 | ;; could do something like: 41 | ;; 42 | ;; (push `(,(regexp-quote macrostep-c-warning-buffer) 43 | ;; (display-buffer-no-window)) 44 | ;; display-buffer-alist) 45 | 46 | ;;; Code: 47 | 48 | (require 'macrostep) 49 | (require 'cmacexp) 50 | (require 'cl-lib) 51 | 52 | (require 'subr-x nil t) 53 | (defalias 'macrostep-c-string-trim 54 | (if (fboundp 'string-trim) 55 | #'string-trim 56 | (lambda (string) 57 | (when (string-match "\\`[ \t\n\r]+" string) 58 | (setq string (replace-match "" t t string))) 59 | (when (string-match "[ \t\n\r]+\\'" string) 60 | (setq string (replace-match "" t t string))) 61 | string))) 62 | 63 | (put 'macrostep-c-non-macro 'error-conditions 64 | '(macrostep-c-non-macro error)) 65 | (put 'macrostep-c-non-macro 'error-message 66 | "Text around point is not a macro call.") 67 | 68 | (put 'macrostep-c-expansion-failed 'error-conditions 69 | '(macrostep-c-expansion-failed error)) 70 | (put 'macrostep-c-expansion-failed 'error-message 71 | "Macro-expansion failed.") 72 | 73 | (defvar macrostep-c-warning-buffer "*Macroexpansion Warnings*") 74 | 75 | ;;;###autoload 76 | (defun macrostep-c-mode-hook () 77 | (setq macrostep-sexp-bounds-function 78 | #'macrostep-c-sexp-bounds) 79 | (setq macrostep-sexp-at-point-function 80 | #'macrostep-c-sexp-at-point) 81 | (setq macrostep-environment-at-point-function 82 | #'ignore) 83 | (setq macrostep-expand-1-function 84 | #'macrostep-c-expand-1) 85 | (setq macrostep-print-function 86 | #'macrostep-c-print-function) 87 | (add-hook 'macrostep-mode-off-hook 88 | #'macrostep-c-mode-off nil t)) 89 | 90 | (defun macrostep-c-mode-off (&rest _ignore) 91 | (when (derived-mode-p 'c-mode) 92 | (let ((warning-window 93 | (get-buffer-window macrostep-c-warning-buffer))) 94 | (when warning-window 95 | (quit-window nil warning-window))))) 96 | 97 | ;;;###autoload 98 | (add-hook 'c-mode-hook #'macrostep-c-mode-hook) 99 | 100 | (defun macrostep-c-sexp-bounds () 101 | (save-excursion 102 | (cl-loop 103 | (let ((region (macrostep-c-sexp-bounds-1))) 104 | (cond 105 | ((null region) 106 | (signal 'macrostep-c-non-macro nil)) 107 | ((macrostep-c-expandable-p region) 108 | (cl-return region)) 109 | (t 110 | (condition-case nil 111 | (progn 112 | (backward-up-list) 113 | (skip-syntax-backward "-")) 114 | (scan-error 115 | (signal 'macrostep-c-non-macro nil))))))))) 116 | 117 | (defun macrostep-c-sexp-bounds-1 () 118 | (let ((region (bounds-of-thing-at-point 'symbol))) 119 | (when region 120 | (cl-destructuring-bind (symbol-start . symbol-end) region 121 | (save-excursion 122 | (goto-char symbol-end) 123 | (if (looking-at "[[:space:]]*(") 124 | (cons symbol-start (scan-sexps symbol-end 1)) 125 | region)))))) 126 | 127 | (defun macrostep-c-expandable-p (region) 128 | (cl-destructuring-bind (start . end) region 129 | (condition-case nil 130 | (cl-destructuring-bind (expansion _warnings) 131 | (macrostep-c-expand-region start end) 132 | (and (cl-plusp (length expansion)) 133 | (not (string= expansion (buffer-substring start end))))) 134 | (macrostep-c-expansion-failed nil)))) 135 | 136 | (defun macrostep-c-sexp-at-point (start end) 137 | (cons start end)) 138 | 139 | (defun macrostep-c-expand-1 (region _ignore) 140 | (cl-destructuring-bind (start . end) region 141 | (cl-destructuring-bind (expansion warnings) 142 | (macrostep-c-expand-region start end) 143 | (when (cl-plusp (length warnings)) 144 | (with-current-buffer 145 | (get-buffer-create macrostep-c-warning-buffer) 146 | (let ((inhibit-read-only t)) 147 | (erase-buffer) 148 | (insert warnings) 149 | (goto-char (point-min))) 150 | (special-mode) 151 | (display-buffer (current-buffer) 152 | '(display-buffer-pop-up-window 153 | (inhibit-same-window . t) 154 | (allow-no-window . t))))) 155 | expansion))) 156 | 157 | (defun macrostep-c-expand-region (start end) 158 | (let ((expansion 159 | (condition-case nil 160 | (c-macro-expansion start end 161 | (concat c-macro-preprocessor " " 162 | c-macro-cppflags)) 163 | (search-failed 164 | (signal 'macrostep-c-expansion-failed nil))))) 165 | (with-temp-buffer 166 | (save-excursion 167 | (insert expansion)) 168 | (when (looking-at (regexp-quote "/*")) 169 | (search-forward "*/")) 170 | (let ((warnings (buffer-substring (point-min) (point))) 171 | (expansion (buffer-substring (point) (point-max)))) 172 | (mapcar #'macrostep-c-string-trim (list expansion warnings)))))) 173 | 174 | (defun macrostep-c-print-function (expansion &rest _ignore) 175 | (with-temp-buffer 176 | (insert expansion) 177 | (let ((exit-code 178 | (shell-command-on-region (point-min) (point-max) "indent" nil t))) 179 | (when (zerop exit-code) 180 | (setq expansion (macrostep-c-string-trim (buffer-string)))))) 181 | (insert expansion)) 182 | 183 | (provide 'macrostep-c) 184 | 185 | ;;; macrostep-c.el ends here 186 | -------------------------------------------------------------------------------- /macrostep-test.el: -------------------------------------------------------------------------------- 1 | ;;; macrostep-test.el --- tests for macrostep.el -*- lexical-binding: t; -*- 2 | 3 | ;; Copyright (C) 2014-2015 Jon Oddie 4 | ;; Copyright (C) 2022-2025 Free Software Foundation, Inc. 5 | 6 | ;; Author: Jon Oddie 7 | ;; Maintainer: Jeremy Bryant 8 | ;; Url: https://github.com/emacsorphanage/macrostep 9 | 10 | ;; SPDX-License-Identifier: GPL-3.0-or-later 11 | 12 | ;; This file is free software: you can redistribute it and/or modify 13 | ;; it under the terms of the GNU General Public License as published 14 | ;; by the Free Software Foundation, either version 3 of the License, 15 | ;; or (at your option) any later version. 16 | ;; 17 | ;; This file is distributed in the hope that it will be useful, 18 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 19 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 20 | ;; GNU General Public License for more details. 21 | ;; 22 | ;; You should have received a copy of the GNU General Public License 23 | ;; along with this file. If not, see . 24 | 25 | ;;; Code: 26 | 27 | (require 'ert) 28 | (require 'rx) 29 | (require 'macrostep) 30 | (require 'macrostep-c) 31 | 32 | 33 | ;;;; Conveniences for defining tests 34 | 35 | (defmacro macrostep-with-text (object &rest forms) 36 | (declare (indent 1) 37 | (debug (&rest form))) 38 | `(with-temp-buffer 39 | (emacs-lisp-mode) 40 | (let ((print-level nil) 41 | (print-length nil) 42 | (standard-output (current-buffer))) 43 | (save-excursion 44 | (print ,object)) 45 | ,@forms))) 46 | 47 | (defun macrostep-goto (text &optional from-point-min) 48 | (when from-point-min (goto-char (point-min))) 49 | (let ((search-spaces-regexp "[[:space:]\n]+")) 50 | (re-search-forward (regexp-quote text)) 51 | (goto-char (match-beginning 0)))) 52 | 53 | (defmacro macrostep-should-expand (form expansion &optional leave-expanded-p) 54 | `(save-excursion 55 | (goto-char (point-min)) 56 | (let ((print-level nil) 57 | (print-length nil)) 58 | (search-forward (prin1-to-string ,form)) 59 | (goto-char (match-beginning 0)) 60 | (unwind-protect 61 | (progn 62 | (macrostep-expand) 63 | (should 64 | (equal (read (current-buffer)) 65 | ,expansion))) 66 | (unless ,leave-expanded-p 67 | (macrostep-collapse-all)))))) 68 | 69 | 70 | ;;;; Tests 71 | (ert-deftest macrostep-expand-defmacro () 72 | (defmacro macrostep-dummy-macro (&rest args) 73 | `(expansion of ,@args)) 74 | (macrostep-with-text 75 | '(progn 76 | (first body form) 77 | (second body form) 78 | (macrostep-dummy-macro (first (argument)) second (third argument)) 79 | (remaining body forms)) 80 | (macrostep-should-expand 81 | '(macrostep-dummy-macro (first (argument)) second (third argument)) 82 | '(expansion of (first (argument)) second (third argument))))) 83 | 84 | (ert-deftest macrostep-expand-and-collapse () 85 | (dolist (expander 86 | (list 87 | (lambda (sexp _env) sexp) 88 | (lambda (sexp _env) `(progn ,sexp ,sexp)) 89 | (lambda (sexp _env) `(long 90 | (complicated 91 | (expansion of ,sexp () ()) 92 | (with trailing forms)))))) 93 | (let ((macrostep-expand-1-function expander) 94 | (macrostep-macro-form-p-function 95 | (lambda (&rest _) t))) 96 | (macrostep-with-text 97 | '(progn 98 | (first form) 99 | (second form) 100 | (third (nested form))) 101 | (macrostep-goto "(first ") 102 | (let ((original-text (buffer-string))) 103 | (dotimes (i 10) 104 | (dotimes (_ i) 105 | (macrostep-expand)) 106 | (dotimes (_ i) 107 | (macrostep-collapse)) 108 | (should (null macrostep-overlays)) 109 | (should (string= (buffer-string) 110 | original-text)))))))) 111 | 112 | (ert-deftest macrostep-expand-macrolet () 113 | (macrostep-with-text 114 | '(cl-macrolet 115 | ((test (&rest args) `(expansion of ,@args))) 116 | (first body form) 117 | (second body form) 118 | (test (strawberry pie) and (apple pie)) 119 | (final body form)) 120 | (macrostep-should-expand 121 | '(test (strawberry pie) and (apple pie)) 122 | '(expansion of (strawberry pie) and (apple pie))))) 123 | 124 | (ert-deftest macrostep-expand-macrolet-2 () 125 | (macrostep-with-text 126 | ;; Taken from org-notify.el. 127 | '(cl-macrolet ((get (k) `(plist-get list ,k)) 128 | (pr (k v) `(setq result (plist-put result ,k ,v)))) 129 | (let* ((list (nth 1 heading)) (notify (or (get :notify) "default")) 130 | (deadline (org-notify-convert-deadline (get :deadline))) 131 | (heading (get :raw-value)) 132 | result) 133 | (when (and (eq (get :todo-type) 'todo) heading deadline) 134 | (pr :heading heading) (pr :notify (intern notify)) 135 | (pr :begin (get :begin)) 136 | (pr :file (nth org-notify-parse-file (org-agenda-files 'unrestricted))) 137 | (pr :timestamp deadline) (pr :uid (md5 (concat heading deadline))) 138 | (pr :deadline (- (org-time-string-to-seconds deadline) 139 | (org-float-time)))) 140 | result)) 141 | (macrostep-should-expand 142 | '(pr :heading heading) 143 | '(setq result (plist-put result :heading heading))) 144 | (macrostep-should-expand 145 | '(pr :notify (intern notify)) 146 | '(setq result (plist-put result :notify (intern notify)))) 147 | (macrostep-should-expand 148 | '(pr :begin (get :begin)) 149 | '(setq result (plist-put result :begin (get :begin)))) 150 | (macrostep-should-expand 151 | '(get :begin) 152 | '(plist-get list :begin)))) 153 | 154 | (ert-deftest macrostep-expand-cl-macrolet () 155 | (macrostep-with-text 156 | ;; Taken from slime.el. 157 | '(cl-macrolet ((fontify (face string) 158 | `(slime-inspector-fontify ,face ,string))) 159 | (slime-propertize-region 160 | (list 'slime-part-number id 161 | 'mouse-face 'highlight 162 | 'face 'slime-inspector-value-face) 163 | (insert title)) 164 | (while (eq (char-before) ?\n) 165 | (backward-delete-char 1)) 166 | (insert "\n" (fontify label "--------------------") "\n") 167 | (save-excursion 168 | (slime-inspector-insert-content content)) 169 | (when point 170 | (cl-check-type point cons) 171 | (ignore-errors 172 | (goto-char (point-min)) 173 | (forward-line (1- (car point))) 174 | (move-to-column (cdr point))))) 175 | (macrostep-should-expand 176 | '(fontify label "--------------------") 177 | '(slime-inspector-fontify label "--------------------")))) 178 | 179 | (ert-deftest macrostep-expand-shadowed-macrolet () 180 | (macrostep-with-text 181 | '(cl-macrolet 182 | ((test-macro (&rest forms) (cons 'shadowed forms)) 183 | (test-macro (&rest forms) (cons 'outer-definition forms))) 184 | (test-macro first (call)) 185 | (cl-macrolet 186 | ((test-macro (&rest forms) (cons 'inner-definition forms))) 187 | (test-macro (second (call))))) 188 | (macrostep-should-expand 189 | '(test-macro first (call)) 190 | '(outer-definition first (call))) 191 | (macrostep-should-expand 192 | '(test-macro (second (call))) 193 | '(inner-definition (second (call)))))) 194 | 195 | (ert-deftest macrostep-environment-at-point () 196 | (macrostep-with-text 197 | ;; Taken from org-notify.el. 198 | '(cl-macrolet ((get (k) `(plist-get list ,k)) 199 | (pr (k v) `(setq result (plist-put result ,k ,v)))) 200 | (body forms)) 201 | (search-forward "(body") 202 | (let ((env (macrostep-environment-at-point))) 203 | (should (assq 'get env)) 204 | (should (assq 'pr env)) 205 | (should (functionp (cdr (assq 'get env)))) 206 | (should (functionp (cdr (assq 'pr env)))) 207 | (should 208 | (equal 209 | (apply (cdr (assq 'pr env)) '(:heading heading)) 210 | '(setq result (plist-put result :heading heading)))) 211 | (should 212 | (equal 213 | (apply (cdr (assq 'get env)) '(:begin)) 214 | '(plist-get list :begin)))))) 215 | 216 | (ert-deftest macrostep-environment-at-point-2 () 217 | (defmacro macrostep-with-dummy (&rest body) 218 | `(cl-macrolet ((dummy (&rest forms) `(expansion of ,@forms))) 219 | ,@body)) 220 | (macrostep-with-text 221 | '(macrostep-with-dummy 222 | (body) 223 | (forms) 224 | (cl-loop for i from 6 to 10 225 | do (something))) 226 | (macrostep-goto "(macrostep-with-dummy" t) 227 | (should (null (macrostep-environment-at-point))) 228 | 229 | (dolist (place (list "(body)" "dy)" "(forms)" "rms)" 230 | "(something)")) 231 | (macrostep-goto place) 232 | (let* ((env (macrostep-environment-at-point)) 233 | (dummy-defn (cdr (assq 'dummy env)))) 234 | (should dummy-defn) 235 | (should (functionp dummy-defn)) 236 | (should (equal 237 | (funcall dummy-defn 'lorem 'ipsum) 238 | `(expansion of lorem ipsum))))))) 239 | 240 | (ert-deftest macrostep-print-sexp () 241 | (cl-macrolet ((should-print (form string) 242 | `(should (equal 243 | (with-temp-buffer 244 | (macrostep-print-sexp ,form) 245 | (buffer-string)) 246 | ,string)))) 247 | (should-print nil "nil") 248 | (should-print 'symbol "symbol") 249 | (should-print '(single-element-list) "(single-element-list)") 250 | (should-print '(two-element list) "(two-element list)") 251 | (should-print '(three element list) "(three element list)") 252 | (should-print '(dotted . list) "(dotted . list)") 253 | (should-print '(four element dotted . list) "(four element dotted . list)") 254 | (should-print '(nested (list (elements))) "(nested (list (elements)))") 255 | (should-print '((deeply (nested)) (list (elements))) 256 | "((deeply (nested)) (list (elements)))") 257 | (should-print '(quote fishes) "'fishes") 258 | (should-print '`(backquoted form) "`(backquoted form)") 259 | (should-print '`(backquoted (form) ,with ,@splices) 260 | "`(backquoted (form) ,with ,@splices)"))) 261 | 262 | (ert-deftest macrostep-pp-macrolet-environment () 263 | (with-temp-buffer 264 | (emacs-lisp-mode) 265 | (macrostep-pp 266 | '(cl-macrolet ((some-macro (&rest forms) (cons 'progn forms))) 267 | (some-macro with (arguments)) 268 | (intervening body forms) 269 | (some-macro with (more) (arguments))) 270 | nil) 271 | (cl-labels ((search (text) 272 | (macrostep-goto text t) 273 | ;; Leave point on the head of the form 274 | (forward-char))) 275 | ;; The occurrence of "(some-macro" in the binding list should 276 | ;; not be fontified as a macro form 277 | (search "(some-macro (&rest") 278 | (should-not 279 | (eq (get-char-property (point) 'font-lock-face) 280 | 'macrostep-macro-face)) 281 | 282 | ;; However, the two occurrences in the body of the macrolet should be. 283 | (search "(some-macro with (arguments)") 284 | (should 285 | (eq (get-char-property (point) 'font-lock-face) 286 | 'macrostep-macro-face)) 287 | 288 | (search "(some-macro with (more)") 289 | (should 290 | (eq (get-char-property (point) 'font-lock-face) 291 | 'macrostep-macro-face))))) 292 | 293 | (ert-deftest macrostep-expand-macro-defined-macros () 294 | (defmacro with-local-dummy-macro (&rest body) 295 | `(cl-macrolet ((dummy (&rest args) `(expansion (of) ,@args))) 296 | ,@body)) 297 | (macrostep-with-text 298 | '(with-local-dummy-macro 299 | (dummy form (one)) 300 | (dummy (form two))) 301 | (macrostep-should-expand 302 | '(dummy form (one)) 303 | '(expansion (of) form (one))) 304 | (macrostep-should-expand 305 | '(dummy (form two)) 306 | '(expansion (of) (form two))))) 307 | 308 | (ert-deftest macrostep-expand-in-separate-buffer () 309 | (defmacro macrostep-dummy-macro (&rest args) 310 | `(expansion of ,@args)) 311 | (let ((macrostep-expand-in-separate-buffer t)) 312 | (macrostep-with-text 313 | '(progn 314 | (first form) 315 | (second form) 316 | (macrostep-dummy-macro (some (arguments))) 317 | (final form)) 318 | (let ((original-buffer (current-buffer))) 319 | (search-forward "(macrostep-dummy-macro") 320 | (macrostep-expand) 321 | (should (not (equal (current-buffer) original-buffer))) 322 | (should macrostep-expansion-buffer) 323 | (should (equal (read (copy-marker (point))) 324 | '(expansion of (some (arguments))))))))) 325 | 326 | (ert-deftest macrostep-expand-macrolet-in-separate-buffer () 327 | (let ((macrostep-expand-in-separate-buffer t)) 328 | (macrostep-with-text 329 | '(cl-macrolet 330 | ((dummy-macro-1 (&rest args) 331 | `(dummy-macro-2 ,@args)) 332 | (dummy-macro-2 (&rest args) 333 | `(expansion of ,@args))) 334 | (dummy-macro-1 (some (arguments)))) 335 | (let ((original-buffer (current-buffer))) 336 | (macrostep-goto "(dummy-macro-1 (some") 337 | 338 | (macrostep-expand) 339 | (should (not (equal (current-buffer) original-buffer))) 340 | (should macrostep-expansion-buffer) 341 | (should (equal (read (copy-marker (point))) 342 | '(dummy-macro-2 (some (arguments))))) 343 | 344 | (macrostep-expand) 345 | (should (equal (read (copy-marker (point))) 346 | '(expansion of (some (arguments))))) 347 | 348 | (macrostep-collapse) 349 | (should (equal (read (copy-marker (point))) 350 | '(dummy-macro-2 (some (arguments))))))))) 351 | 352 | (ert-deftest macrostep-expand-compiler-macros () 353 | "Test that compiler-macros are expanded" 354 | ;; definitions 355 | (defun macrostep-dummy-function (&rest args) 356 | args) 357 | (cl-define-compiler-macro macrostep-dummy-function (&rest args) 358 | `(compile-time expansion of ,@args)) 359 | 360 | (macrostep-with-text 361 | '(progn 362 | (first body form) 363 | (macrostep-dummy-function first second third) 364 | (remaining body forms)) 365 | (macrostep-should-expand 366 | '(macrostep-dummy-function first second third) 367 | '(compile-time expansion of first second third)))) 368 | 369 | (ert-deftest macrostep-fontify-compiler-macros () 370 | "Test that compiler-macros are fontified in macro-expansions" 371 | ;; definitions 372 | (defmacro macrostep-dummy-macro (&rest args) 373 | `(expansion including (macrostep-dummy-function ,@args))) 374 | (defun macrostep-dummy-function (&rest args) 375 | args) 376 | (cl-define-compiler-macro macrostep-dummy-4 (&rest args) 377 | `(compile-time expansion of ,@args)) 378 | 379 | (macrostep-with-text 380 | '(progn 381 | (first body form) 382 | (second body form) 383 | (macrostep-dummy-macro first second third) 384 | (remaining body forms)) 385 | (macrostep-should-expand 386 | '(macrostep-dummy-macro first second third) 387 | '(expansion including (macrostep-dummy-function first second third)) 388 | t) 389 | (macrostep-goto "(macrostep-dummy-function") 390 | (should 391 | (eq (get-char-property (1+ (point)) 'font-lock-face) 392 | 'macrostep-compiler-macro-face)) 393 | 394 | (macrostep-should-expand 395 | '(macrostep-dummy-function first second third) 396 | '(compile-time expansion of first second third)))) 397 | 398 | 399 | ;;;; Tests for C macro expansion 400 | 401 | (defun macrostep-lax-looking-at (string) 402 | (let* ((string-sans-whitespace 403 | (replace-regexp-in-string (rx (one-or-more whitespace)) "" string)) 404 | (regexp 405 | (cl-loop 406 | for char across string-sans-whitespace 407 | concat (rx-to-string char t) 408 | concat "[[:space:]]*"))) 409 | (looking-at regexp))) 410 | 411 | (defmacro macrostep-lax-should-expand (string) 412 | `(progn 413 | (macrostep-expand) 414 | (should (macrostep-lax-looking-at ,string)) 415 | (macrostep-collapse))) 416 | 417 | (ert-deftest macrostep-expand-c-macros () 418 | (with-temp-buffer 419 | (insert 420 | ;; A random example adapted from Emacs's src/lisp.h. 421 | " 422 | #define eassert(cond) ((void) (false && (cond))) /* Check COND compiles. */ 423 | #define lisp_h_XLI(o) (o) 424 | #define lisp_h_XUNTAG(a, type) ((void *) (intptr_t) (XLI (a) - (type))) 425 | #define XLI(o) lisp_h_XLI (o) 426 | #define XUNTAG(a, type) lisp_h_XUNTAG (a, type) 427 | 428 | INLINE struct Lisp_String * 429 | XSTRING (Lisp_Object a) 430 | { 431 | eassert (STRINGP (a)); 432 | return XUNTAG (a, Lisp_String); 433 | }") 434 | (c-mode) 435 | 436 | ;; Test macro-expansion with point at the beginning of the macro 437 | (macrostep-goto "eassert (STRINGP (a))" t) 438 | (macrostep-lax-should-expand 439 | "((void) (false && (STRINGP (a))))") 440 | 441 | ;; Test with point inside a nested macro call: result should be 442 | ;; the same, since point will move up before the outermost macro 443 | (macrostep-goto "STRINGP") 444 | (macrostep-lax-should-expand 445 | "((void) (false && (STRINGP (a))))") 446 | 447 | ;; Test with point in the middle of a symbol 448 | (macrostep-goto "XUNTAG (a, Lisp_String)" t) 449 | (forward-char 3) 450 | (macrostep-lax-should-expand 451 | "((void *) (intptr_t) ((a) - ( Lisp_String)))") 452 | 453 | ;; Test with point at symbol-end 454 | (macrostep-goto "XUNTAG (a, Lisp_String)" t) 455 | (forward-sexp) 456 | (macrostep-lax-should-expand 457 | "((void *) (intptr_t) ((a) - ( Lisp_String)))"))) 458 | 459 | 460 | 461 | (when noninteractive 462 | (load-file (expand-file-name "macrostep.el" 463 | (file-name-directory load-file-name))) 464 | (let ((stats (ert-run-tests-batch "^macrostep"))) 465 | (if noninteractive 466 | (kill-emacs (ert-stats-completed-unexpected stats))))) 467 | -------------------------------------------------------------------------------- /macrostep.el: -------------------------------------------------------------------------------- 1 | ;;; macrostep.el --- Interactive macro expander -*- lexical-binding: t; -*- 2 | 3 | ;; Copyright (C) 2012-2015 Jon Oddie 4 | ;; Copyright (C) 2020-2025 Free Software Foundation, Inc. 5 | 6 | ;; Author: Jon Oddie 7 | ;; Maintainer: Jeremy Bryant 8 | ;; Url: https://github.com/emacsorphanage/macrostep 9 | ;; Keywords: lisp, languages, macro, debugging 10 | 11 | ;; Package-Version: 0.9.5 12 | ;; Package-Requires: ((cl-lib "0.5") (compat "29")) 13 | 14 | ;; SPDX-License-Identifier: GPL-3.0-or-later 15 | 16 | ;; This file is free software: you can redistribute it and/or modify 17 | ;; it under the terms of the GNU General Public License as published 18 | ;; by the Free Software Foundation, either version 3 of the License, 19 | ;; or (at your option) any later version. 20 | ;; 21 | ;; This file is distributed in the hope that it will be useful, 22 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 23 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 24 | ;; GNU General Public License for more details. 25 | ;; 26 | ;; You should have received a copy of the GNU General Public License 27 | ;; along with this file. If not, see . 28 | 29 | ;;; Commentary: 30 | 31 | ;; `macrostep' is an Emacs minor mode for interactively stepping through 32 | ;; the expansion of macros in Emacs Lisp source code. It lets you see 33 | ;; exactly what happens at each step of the expansion process by 34 | ;; pretty-printing the expanded forms inline in the source buffer, which is 35 | ;; temporarily read-only while macro expansions are visible. You can 36 | ;; expand and collapse macro forms one step at a time, and evaluate or 37 | ;; instrument the expansions for debugging with Edebug as normal (but see 38 | ;; "Bugs and known limitations", below). Single-stepping through the 39 | ;; expansion is particularly useful for debugging macros that expand into 40 | ;; another macro form. These can be difficult to debug with Emacs' 41 | ;; built-in `macroexpand', which continues expansion until the top-level 42 | ;; form is no longer a macro call. 43 | 44 | ;; Both globally-visible macros as defined by `defmacro' and local macros 45 | ;; bound by `(cl-)macrolet' or another macro-defining form can be expanded. 46 | ;; Within macro expansions, calls to macros and compiler macros are 47 | ;; fontified specially: macro forms using `macrostep-macro-face', and 48 | ;; functions with compiler macros using `macrostep-compiler-macro-face'. 49 | ;; Uninterned symbols (gensyms) are fontified based on which step in the 50 | ;; expansion created them, to distinguish them both from normal symbols and 51 | ;; from other gensyms with the same print name. 52 | 53 | ;; As of version 0.9, it is also possible to extend `macrostep' to work 54 | ;; with other languages with macro systems in addition to Emacs Lisp. An 55 | ;; extension for Common Lisp (via SLIME) is in the works; contributions for 56 | ;; other languages are welcome. See "Extending macrostep" below for 57 | ;; details. 58 | 59 | 60 | ;; 1 Key-bindings and usage 61 | ;; ======================== 62 | 63 | ;; The standard keybindings in `macrostep-mode' are the following: 64 | 65 | ;; e, =, RET : expand the macro form following point one step 66 | ;; c, u, DEL : collapse the form following point 67 | ;; q, C-c C-c: collapse all expanded forms and exit macrostep-mode 68 | ;; n, TAB : jump to the next macro form in the expansion 69 | ;; p, M-TAB : jump to the previous macro form in the expansion 70 | 71 | ;; It's not very useful to enable and disable macrostep-mode directly. 72 | ;; Instead, bind `macrostep-expand' to a key in `emacs-lisp-mode-map', 73 | ;; for example C-c e: 74 | 75 | ;; ,---- 76 | ;; | (define-key emacs-lisp-mode-map (kbd "C-c e") 'macrostep-expand) 77 | ;; `---- 78 | 79 | ;; You can then enter macrostep-mode and expand a macro form completely 80 | ;; by typing `C-c e e e ...' as many times as necessary. 81 | 82 | ;; Exit macrostep-mode by typing `q' or `C-c C-c', or by successively 83 | ;; typing `c' to collapse all surrounding expansions. 84 | 85 | 86 | ;; 2 Customization options 87 | ;; ======================= 88 | 89 | ;; Type `M-x customize-group RET macrostep RET' to customize options and 90 | ;; faces. 91 | 92 | ;; To display macro expansions in a separate window, instead of inline in 93 | ;; the source buffer, customize `macrostep-expand-in-separate-buffer' to 94 | ;; `t'. The default is `nil'. Whichever default behavior is selected, 95 | ;; the alternative behavior can be obtained temporarily by giving a 96 | ;; prefix argument to `macrostep-expand'. 97 | 98 | ;; To have `macrostep' ignore compiler macros, customize 99 | ;; `macrostep-expand-compiler-macros' to `nil'. The default is `t'. 100 | 101 | ;; Customize the faces `macrostep-macro-face', 102 | ;; `macrostep-compiler-macro-face', and `macrostep-gensym-1' through 103 | ;; `macrostep-gensym-5' to alter the appearance of macro expansions. 104 | 105 | 106 | ;; 3 Locally-bound macros 107 | ;; ====================== 108 | 109 | ;; As of version 0.9, `macrostep' can expand calls to a locally-bound 110 | ;; macro, whether defined by a surrounding `(cl-)macrolet' form, or by 111 | ;; another macro-defining macro. In other words, it is possible to 112 | ;; expand the inner `local-macro' forms in both the following examples, 113 | ;; whether `local-macro' is defined by an enclosing `cl-macrolet' -- 114 | 115 | ;; ,---- 116 | ;; | (cl-macrolet ((local-macro (&rest args) 117 | ;; | `(expansion of ,args))) 118 | ;; | (local-macro (do-something))) 119 | ;; `---- 120 | 121 | ;; -- or by a macro which expands into `cl-macrolet', provided that its 122 | ;; definition of macro is evaluated prior to calling `macrostep-expand': 123 | 124 | ;; ,---- 125 | ;; | (defmacro with-local-macro (&rest body) 126 | ;; | `(cl-macrolet ((local-macro (&rest args) 127 | ;; | `(expansion of ,args))) 128 | ;; | ,@body)) 129 | ;; | 130 | ;; | (with-local-macro 131 | ;; | (local-macro (do something (else))) 132 | ;; `---- 133 | 134 | ;; See the `with-js' macro in Emacs's `js.el' for a real example of the 135 | ;; latter kind of macro. 136 | 137 | ;; Expansion of locally-bound macros is implemented by instrumenting 138 | ;; Emacs Lisp's macro-expander to capture the environment at point. A 139 | ;; similar trick is used to detect macro- and compiler-macro calls within 140 | ;; expanded text so that they can be fontified accurately. 141 | 142 | 143 | ;; 4 Expanding sub-forms 144 | ;; ===================== 145 | 146 | ;; By moving point around in the macro expansion using 147 | ;; `macrostep-next-macro' and `macrostep-prev-macro' (bound to the `n' 148 | ;; and `p' keys), it is possible to expand other macro calls within the 149 | ;; expansion before expanding the outermost form. This can sometimes be 150 | ;; useful, although it does not correspond to the real order of macro 151 | ;; expansion in Emacs Lisp, which proceeds by fully expanding the outer 152 | ;; form to a non-macro form before expanding sub-forms. 153 | 154 | ;; The main reason to expand sub-forms out of order is to help with 155 | ;; debugging macros which programmatically expand their arguments in 156 | ;; order to rewrite them. Expanding the arguments of such a macro lets 157 | ;; you visualise what the macro definition would compute via 158 | ;; `macroexpand-all'. 159 | 160 | 161 | ;; 5 Extending macrostep for other languages 162 | ;; ========================================= 163 | 164 | ;; Since version 0.9, it is possible to extend macrostep to work with 165 | ;; other languages besides Emacs Lisp. In typical Emacs fashion, this is 166 | ;; implemented by setting buffer-local variables to different function 167 | ;; values. Six buffer-local variables define the language-specific part 168 | ;; of the implementation: 169 | 170 | ;; - `macrostep-sexp-bounds-function' 171 | ;; - `macrostep-sexp-at-point-function' 172 | ;; - `macrostep-environment-at-point-function' 173 | ;; - `macrostep-expand-1-function' 174 | ;; - `macrostep-print-function' 175 | ;; - `macrostep-macro-form-p-function' 176 | 177 | ;; Typically, an implementation for another language would set these 178 | ;; variables in a major-mode hook. See the docstrings of each variable 179 | ;; for details on how each one is called and what it should return. At a 180 | ;; minimum, another language implementation needs to provide 181 | ;; `macrostep-sexp-at-point-function', `macrostep-expand-1-function', and 182 | ;; `macrostep-print-function'. Lisp-like languages may be able to reuse 183 | ;; the default `macrostep-sexp-bounds-function' if they provide another 184 | ;; implementation of `macrostep-macro-form-p-function'. Languages which 185 | ;; do not implement locally-defined macros can set 186 | ;; `macrostep-environment-at-point-function' to `ignore'. 187 | 188 | ;; Note that the core `macrostep' machinery only interprets the return 189 | ;; value of `macrostep-sexp-bounds-function', so implementations for 190 | ;; other languages can use any internal representations of code and 191 | ;; environments which is convenient. Although the terminology is 192 | ;; Lisp-specific, there is no reason that implementations could not be 193 | ;; provided for non-Lisp languages with macro systems, provided there is 194 | ;; some way of identifying macro calls and calling the compiler / 195 | ;; preprocessor to obtain their expansions. 196 | 197 | 198 | ;; 6 Bugs and known limitations 199 | ;; ============================ 200 | 201 | ;; You can evaluate and edebug macro-expanded forms and step through the 202 | ;; macro-expanded version, but the form that `eval-defun' and friends 203 | ;; read from the buffer won't have the uninterned symbols of the real 204 | ;; macro expansion. This will probably work OK with CL-style gensyms, 205 | ;; but may cause problems with `make-symbol' symbols if they have the 206 | ;; same print name as another symbol in the expansion. It's possible that 207 | ;; using `print-circle' and `print-gensym' could get around this. 208 | 209 | ;; Please send other bug reports and feature requests to the author. 210 | 211 | 212 | ;; 7 Acknowledgements 213 | ;; ================== 214 | 215 | ;; Thanks to: 216 | ;; - John Wiegley for fixing a bug with the face definitions under Emacs 217 | ;; 24 & for plugging macrostep in his [EmacsConf presentation]! 218 | ;; - George Kettleborough for bug reports, and patches to highlight the 219 | ;; expanded region and properly handle backquotes. 220 | ;; - Nic Ferrier for suggesting support for local definitions within 221 | ;; macrolet forms 222 | ;; - Luís Oliveira for suggesting and implementing SLIME support 223 | 224 | ;; `macrostep' was originally inspired by J. V. Toups's 'Deep Emacs Lisp' 225 | ;; articles ([part 1], [part 2], [screencast]). 226 | 227 | ;; [EmacsConf presentation] http://youtu.be/RvPFZL6NJNQ 228 | 229 | ;; [part 1] 230 | ;; http://dorophone.blogspot.co.uk/2011/04/deep-emacs-part-1.html 231 | 232 | ;; [part 2] 233 | ;; http://dorophone.blogspot.co.uk/2011/04/deep-emacs-lisp-part-2.html 234 | 235 | ;; [screencast] 236 | ;; http://dorophone.blogspot.co.uk/2011/05/monadic-parser-combinators-in-elisp.html 237 | 238 | 239 | ;;; News: 240 | 241 | ;; - v0.9.5, 2024-02-01: 242 | ;; - documentation improvements 243 | ;; - v0.9.4, 2024-05-09: 244 | ;; - add compat dependency for defvar-keymap 245 | ;; - v0.9.3, 2024-04-30: 246 | ;; - code simplifications, checkdoc fixes. 247 | ;; - v0.9.2, 2023-05-12: 248 | ;; - name the keymap macrostep-mode-map, fixing a regression in v0.9.1 249 | ;; - v0.9.1, 2023-03-12: 250 | ;; - bug fixes, cleanup and modernization 251 | ;; - v0.9, 2015-10-01: 252 | ;; - separate into Elisp-specific and generic components 253 | ;; - highlight and expand compiler macros 254 | ;; - improve local macro expansion and macro form identification by 255 | ;; instrumenting `macroexpand(-all)' 256 | ;; - v0.8, 2014-05-29: fix a bug with printing the first element of lists 257 | ;; - v0.7, 2014-05-11: expand locally-defined macros within 258 | ;; `(cl-)macrolet' forms 259 | ;; - v0.6, 2013-05-04: better handling of quote and backquote 260 | ;; - v0.5, 2013-04-16: highlight region, maintain cleaner buffer state 261 | ;; - v0.4, 2013-04-07: only enter macrostep-mode on successful 262 | ;; macro-expansion 263 | ;; - v0.3, 2012-10-30: print dotted lists correctly. autoload 264 | ;; definitions. 265 | 266 | ;;; Code: 267 | 268 | (require 'compat) 269 | 270 | (require 'pp) 271 | (require 'ring) 272 | (require 'cl-lib) 273 | 274 | 275 | ;;; Constants and dynamically bound variables 276 | (defvar-local macrostep-overlays nil 277 | "List of all macro stepper overlays in the current buffer.") 278 | 279 | (defvar-local macrostep-gensym-depth nil 280 | "Number of macro expansion levels that have introduced gensyms so far.") 281 | 282 | (defvar-local macrostep-gensyms-this-level nil 283 | "Non-nil if gensyms were encountered during current level of macro expansion.") 284 | 285 | (defvar-local macrostep-saved-undo-list nil 286 | "Saved value of `buffer-undo-list' upon entering macrostep mode.") 287 | 288 | (defvar-local macrostep-saved-read-only nil 289 | "Saved value of `buffer-read-only' upon entering macrostep mode.") 290 | 291 | (defvar-local macrostep-expansion-buffer nil 292 | "Non-nil if the current buffer is a macro-expansion buffer.") 293 | 294 | (defvar-local macrostep-outer-environment nil 295 | "Outermost macro-expansion environment to use in macro-expansion buffers. 296 | 297 | This variable is used to save information about any enclosing 298 | `cl-macrolet' context when a macro form is expanded in a separate 299 | buffer.") 300 | 301 | ;;; Customization options and faces 302 | (defgroup macrostep nil 303 | "Interactive macro stepper for Emacs Lisp." 304 | :group 'lisp 305 | :link '(emacs-commentary-link :tag "commentary" "macrostep.el") 306 | :link '(emacs-library-link :tag "lisp file" "macrostep.el") 307 | :link '(url-link :tag "web page" "https://github.com/emacsorphanage/macrostep")) 308 | 309 | (defface macrostep-gensym-1 310 | '((((min-colors 16581375)) :foreground "#8080c0" :box t :bold t) 311 | (((min-colors 8)) :background "cyan") 312 | (t :inverse-video t)) 313 | "Face for gensyms created in the first level of macro expansion." 314 | :version "1.0") 315 | 316 | (defface macrostep-gensym-2 317 | '((((min-colors 16581375)) :foreground "#8fbc8f" :box t :bold t) 318 | (((min-colors 8)) :background "#00cd00") 319 | (t :inverse-video t)) 320 | "Face for gensyms created in the second level of macro expansion." 321 | :version "1.0") 322 | 323 | (defface macrostep-gensym-3 324 | '((((min-colors 16581375)) :foreground "#daa520" :box t :bold t) 325 | (((min-colors 8)) :background "yellow") 326 | (t :inverse-video t)) 327 | "Face for gensyms created in the third level of macro expansion." 328 | :version "1.0") 329 | 330 | (defface macrostep-gensym-4 331 | '((((min-colors 16581375)) :foreground "#cd5c5c" :box t :bold t) 332 | (((min-colors 8)) :background "red") 333 | (t :inverse-video t)) 334 | "Face for gensyms created in the fourth level of macro expansion." 335 | :version "1.0") 336 | 337 | (defface macrostep-gensym-5 338 | '((((min-colors 16581375)) :foreground "#da70d6" :box t :bold t) 339 | (((min-colors 8)) :background "magenta") 340 | (t :inverse-video t)) 341 | "Face for gensyms created in the fifth level of macro expansion." 342 | :version "1.0") 343 | 344 | (defface macrostep-expansion-highlight-face 345 | `((((min-colors 16581375) (background light)) 346 | ,@(and (>= emacs-major-version 27) '(:extend t)) 347 | :background "#eee8d5") 348 | (((min-colors 16581375) (background dark)) 349 | ,@(and (>= emacs-major-version 27) '(:extend t)) 350 | :background "#222222")) 351 | "Face for macro-expansion highlight." 352 | :version "1.0") 353 | 354 | (defface macrostep-macro-face 355 | '((t :underline t)) 356 | "Face for macros in macro-expanded code." 357 | :version "1.0") 358 | 359 | (defface macrostep-compiler-macro-face 360 | '((t :slant italic)) 361 | "Face for compiler macros in macro-expanded code." 362 | :version "1.0") 363 | 364 | (defcustom macrostep-expand-in-separate-buffer nil 365 | "When non-nil, show expansions in a separate buffer instead of inline." 366 | :type 'boolean 367 | :version "1.0") 368 | 369 | (defcustom macrostep-expand-compiler-macros t 370 | "When non-nil, also expand compiler macros." 371 | :type 'boolean 372 | :version "1.0") 373 | 374 | (defvar macrostep-gensym-faces 375 | (ring-convert-sequence-to-ring 376 | (list 'macrostep-gensym-1 'macrostep-gensym-2 'macrostep-gensym-3 377 | 'macrostep-gensym-4 'macrostep-gensym-5)) 378 | "Ring of all macrostepper faces for fontifying gensyms.") 379 | 380 | ;; Other modes can enable macrostep by redefining these functions to 381 | ;; language-specific versions. 382 | (defvar macrostep-sexp-bounds-function 383 | #'macrostep-sexp-bounds 384 | "Function to return the bounds of the macro form nearest point. 385 | 386 | It will be called with no arguments and should return a cons of 387 | buffer positions, (START . END). It should use `save-excursion' 388 | to avoid changing the position of point. 389 | 390 | The default value, `macrostep-sexp-bounds', implements this for 391 | Emacs Lisp, and may be suitable for other Lisp-like languages.") 392 | (make-variable-buffer-local 'macrostep-sexp-bounds-function) 393 | 394 | (defvar macrostep-sexp-at-point-function 395 | #'macrostep-sexp-at-point 396 | "Function to return the macro form at point for expansion. 397 | 398 | It will be called with two arguments, the values of START and END 399 | returned by `macrostep-sexp-bounds-function', and with point 400 | positioned at START. It should return a value suitable for 401 | passing as the first argument to `macrostep-expand-1-function'. 402 | 403 | The default value, `macrostep-sexp-at-point', implements this for 404 | Emacs Lisp, and may be suitable for other Lisp-like languages.") 405 | (make-variable-buffer-local 'macrostep-sexp-at-point-function) 406 | 407 | (defvar macrostep-environment-at-point-function 408 | #'macrostep-environment-at-point 409 | "Function to return the local macro-expansion environment at point. 410 | 411 | It will be called with no arguments, and should return a value 412 | suitable for passing as the second argument to 413 | `macrostep-expand-1-function'. 414 | 415 | The default value, `macrostep-environment-at-point', is specific 416 | to Emacs Lisp. For languages which do not implement local 417 | macro-expansion environments, this should be set to `ignore' 418 | or `(lambda () nil)'.") 419 | (make-variable-buffer-local 'macrostep-environment-at-point-function) 420 | 421 | (defvar macrostep-expand-1-function 422 | #'macrostep-expand-1 423 | "Function to perform one step of macro-expansion. 424 | 425 | It will be called with two arguments, FORM and ENVIRONMENT, the 426 | return values of `macrostep-sexp-at-point-function' and 427 | `macrostep-environment-at-point-function' respectively. It 428 | should return the result of expanding FORM by one step as a value 429 | which is suitable for passing as the argument to 430 | `macrostep-print-function'. 431 | 432 | The default value, `macrostep-expand-1', is specific to Emacs Lisp.") 433 | (make-variable-buffer-local 'macrostep-expand-1-function) 434 | 435 | (defvar macrostep-print-function 436 | #'macrostep-pp 437 | "Function to pretty-print macro expansions. 438 | 439 | It will be called with two arguments, FORM and ENVIRONMENT, the 440 | return values of `macrostep-sexp-at-point-function' and 441 | `macrostep-environment-at-point-function' respectively. It 442 | should insert a pretty-printed representation at point in the 443 | current buffer, leaving point just after the inserted 444 | representation, without altering any other text in the current 445 | buffer. 446 | 447 | The default value, `macrostep-pp', is specific to Emacs Lisp.") 448 | (make-variable-buffer-local 'macrostep-print-function) 449 | 450 | (defvar macrostep-macro-form-p-function 451 | #'macrostep-macro-form-p 452 | "Function to check whether a form is a macro call. 453 | 454 | It will be called with two arguments, FORM and ENVIRONMENT -- the 455 | return values of `macrostep-sexp-at-point-function' and 456 | `macrostep-environment-at-point-function' respectively -- and 457 | should return non-nil if FORM would undergo macro-expansion in 458 | ENVIRONMENT. 459 | 460 | This is called only from `macrostep-sexp-bounds', so it need not 461 | be provided if a different value is used for 462 | `macrostep-sexp-bounds-function'. 463 | 464 | The default value, `macrostep-macro-form-p', is specific to Emacs Lisp.") 465 | (make-variable-buffer-local 'macrostep-macro-form-p-function) 466 | 467 | 468 | ;;; Define keymap and minor mode 469 | (define-obsolete-variable-alias 'macrostep-mode-keymap 'macrostep-mode-map "2023") 470 | (define-obsolete-variable-alias 'macrostep-keymap 'macrostep-mode-map "2022") 471 | (defvar-keymap macrostep-mode-map 472 | :doc "Keymap for `macrostep-mode'." 473 | "RET" #'macrostep-expand 474 | "=" #'macrostep-expand 475 | "e" #'macrostep-expand 476 | 477 | "DEL" #'macrostep-collapse 478 | "u" #'macrostep-collapse 479 | "c" #'macrostep-collapse 480 | 481 | "TAB" #'macrostep-next-macro 482 | "n" #'macrostep-next-macro 483 | "M-TAB" #'macrostep-prev-macro 484 | "p" #'macrostep-prev-macro 485 | 486 | "q" #'macrostep-collapse-all 487 | "C-c C-c" #'macrostep-collapse-all) 488 | 489 | ;;;###autoload 490 | (define-minor-mode macrostep-mode 491 | "Minor mode for inline expansion of macros in Emacs Lisp source buffers. 492 | 493 | \\Progressively expand macro forms with \ 494 | \\[macrostep-expand], collapse them with \\[macrostep-collapse], 495 | and move back and forth with \\[macrostep-next-macro] and \ 496 | \\[macrostep-prev-macro]. Use \\[macrostep-collapse-all] or collapse all 497 | visible expansions to quit and return to normal editing. 498 | 499 | \\{macrostep-mode-map}" 500 | :lighter " Macro-Stepper" 501 | :group 'macrostep 502 | (if macrostep-mode 503 | (progn 504 | ;; Disable recording of undo information 505 | (setq macrostep-saved-undo-list buffer-undo-list 506 | buffer-undo-list t) 507 | ;; Remember whether buffer was read-only 508 | (setq macrostep-saved-read-only buffer-read-only 509 | buffer-read-only t) 510 | ;; Set up post-command hook to bail out on leaving read-only 511 | (add-hook 'post-command-hook #'macrostep-command-hook nil t) 512 | (message (substitute-command-keys "\ 513 | \\Entering macro stepper mode. \ 514 | Use \\[macrostep-expand] to expand, \\[macrostep-collapse] to collapse, \ 515 | \\[macrostep-collapse-all] to exit."))) 516 | 517 | ;; Exiting mode 518 | (if macrostep-expansion-buffer 519 | ;; Kill dedicated expansion buffers 520 | (quit-window t) 521 | ;; Collapse any remaining overlays 522 | (when macrostep-overlays (macrostep-collapse-all)) 523 | ;; Restore undo info & read-only state 524 | (setq buffer-undo-list macrostep-saved-undo-list 525 | buffer-read-only macrostep-saved-read-only 526 | macrostep-saved-undo-list nil) 527 | ;; Remove our post-command hook 528 | (remove-hook 'post-command-hook #'macrostep-command-hook t)))) 529 | 530 | (defun macrostep-command-hook () 531 | "Hook function for use by `post-command hook'. 532 | Bail out of `macrostep-mode' if the user types 533 | `\\[read-only-mode]' to make the buffer writable again." 534 | (if (not buffer-read-only) 535 | (macrostep-mode 0))) 536 | 537 | 538 | ;;; Interactive functions 539 | ;;;###autoload 540 | (defun macrostep-expand (&optional toggle-separate-buffer) 541 | "Expand the macro form following point by one step. 542 | 543 | Enters `macrostep-mode' if it is not already active, making the 544 | buffer temporarily read-only. If `macrostep-mode' is active and 545 | the form following point is not a macro form, search forward in 546 | the buffer and expand the next macro form found, if any. 547 | 548 | If optional argument TOGGLE-SEPARATE-BUFFER is non-nil (or set 549 | with a prefix argument), the expansion is displayed in a 550 | separate buffer instead of inline in the current buffer. 551 | Setting `macrostep-expand-in-separate-buffer' to non-nil swaps 552 | these two behaviors." 553 | (interactive "P") 554 | (cl-destructuring-bind (start . end) 555 | (funcall macrostep-sexp-bounds-function) 556 | (goto-char start) 557 | (let* ((sexp (funcall macrostep-sexp-at-point-function start end)) 558 | (end (copy-marker end)) 559 | (text (buffer-substring start end)) 560 | (env (funcall macrostep-environment-at-point-function)) 561 | (expansion (funcall macrostep-expand-1-function sexp env))) 562 | 563 | ;; Create a dedicated macro-expansion buffer and copy the text to 564 | ;; be expanded into it, if required 565 | (let ((separate-buffer-p 566 | (if toggle-separate-buffer 567 | (not macrostep-expand-in-separate-buffer) 568 | macrostep-expand-in-separate-buffer))) 569 | (when (and separate-buffer-p (not macrostep-expansion-buffer)) 570 | (let ((mode major-mode) 571 | (buffer 572 | (get-buffer-create (generate-new-buffer-name "*macro expansion*")))) 573 | (set-buffer buffer) 574 | (funcall mode) 575 | (setq macrostep-expansion-buffer t) 576 | (setq macrostep-outer-environment env) 577 | (save-excursion 578 | (setq start (point)) 579 | (insert text) 580 | (setq end (point-marker))) 581 | (pop-to-buffer buffer)))) 582 | 583 | (unless macrostep-mode (macrostep-mode t)) 584 | (let ((existing-overlay (macrostep-overlay-at-point)) 585 | (macrostep-gensym-depth macrostep-gensym-depth) 586 | (macrostep-gensyms-this-level nil) 587 | priority) 588 | (if existing-overlay ; Expanding part of a previous macro-expansion 589 | (setq priority (1+ (overlay-get existing-overlay 'priority)) 590 | macrostep-gensym-depth 591 | (overlay-get existing-overlay 'macrostep-gensym-depth)) 592 | ;; Expanding source buffer text 593 | (setq priority 1 594 | macrostep-gensym-depth -1)) 595 | 596 | (with-silent-modifications 597 | (atomic-change-group 598 | (let ((inhibit-read-only t)) 599 | (save-excursion 600 | ;; Insert expansion 601 | (funcall macrostep-print-function expansion env) 602 | ;; Delete the original form 603 | (macrostep-collapse-overlays-in (point) end) 604 | (delete-region (point) end) 605 | ;; Create a new overlay 606 | (let* ((overlay 607 | (make-overlay start 608 | (if (looking-at "\n") 609 | (1+ (point)) 610 | (point)))) 611 | (highlight-overlay (unless macrostep-expansion-buffer 612 | (copy-overlay overlay)))) 613 | (unless macrostep-expansion-buffer 614 | ;; Highlight the overlay in original source buffers only 615 | (overlay-put highlight-overlay 'face 'macrostep-expansion-highlight-face) 616 | (overlay-put highlight-overlay 'priority -1) 617 | (overlay-put overlay 'macrostep-highlight-overlay highlight-overlay)) 618 | (overlay-put overlay 'priority priority) 619 | (overlay-put overlay 'macrostep-original-text text) 620 | (overlay-put overlay 'macrostep-gensym-depth macrostep-gensym-depth) 621 | (push overlay macrostep-overlays)))))))))) 622 | 623 | (defun macrostep-collapse () 624 | "Collapse the innermost macro expansion near point to its source text. 625 | 626 | If no more macro expansions are visible after this, exit 627 | `macrostep-mode'." 628 | (interactive) 629 | (let ((overlay (macrostep-overlay-at-point))) 630 | (when (not overlay) (error "No macro expansion at point")) 631 | (let ((inhibit-read-only t)) 632 | (with-silent-modifications 633 | (atomic-change-group 634 | (macrostep-collapse-overlay overlay))))) 635 | (unless macrostep-overlays 636 | (macrostep-mode 0))) 637 | 638 | (defun macrostep-collapse-all () 639 | "Collapse all visible macro expansions and exit `macrostep-mode'." 640 | (interactive) 641 | (let ((inhibit-read-only t)) 642 | (with-silent-modifications 643 | (dolist (overlay macrostep-overlays) 644 | (let ((outermost (= (overlay-get overlay 'priority) 1))) 645 | ;; We only need restore the original text for the outermost 646 | ;; overlays 647 | (macrostep-collapse-overlay overlay (not outermost)))))) 648 | (setq macrostep-overlays nil) 649 | (macrostep-mode 0)) 650 | 651 | (defun macrostep-next-macro () 652 | "Move point forward to the next macro form in macro-expanded text." 653 | (interactive) 654 | (let* ((start (if (get-text-property (point) 'macrostep-macro-start) 655 | (1+ (point)) 656 | (point))) 657 | (next (next-single-property-change start 'macrostep-macro-start))) 658 | (if next 659 | (goto-char next) 660 | (error "No more macro forms found")))) 661 | 662 | (defun macrostep-prev-macro () 663 | "Move point back to the previous macro form in macro-expanded text." 664 | (interactive) 665 | (let (prev) 666 | (save-excursion 667 | (while 668 | (progn 669 | (setq prev (previous-single-property-change 670 | (point) 'macrostep-macro-start)) 671 | (if (or (not prev) 672 | (get-text-property (1- prev) 'macrostep-macro-start)) 673 | nil 674 | (prog1 t (goto-char prev)))))) 675 | (if prev 676 | (goto-char (1- prev)) 677 | (error "No previous macro form found")))) 678 | 679 | 680 | ;;; Utility functions (not language-specific) 681 | 682 | (defun macrostep-overlay-at-point () 683 | "Return the innermost macro stepper overlay at point." 684 | (cdr (get-char-property-and-overlay (point) 'macrostep-original-text))) 685 | 686 | (defun macrostep-collapse-overlay (overlay &optional no-restore-p) 687 | "Collapse macro-expansion buffer OVERLAY and restore the unexpanded source text. 688 | 689 | As a minor optimization, does not restore the original source 690 | text if NO-RESTORE-P is non-nil. This is safe to do when 691 | collapsing all the sub-expansions of an outer overlay, since the 692 | outer overlay will restore the original source itself. 693 | 694 | Also removes the overlay from `macrostep-overlays'." 695 | (with-current-buffer (overlay-buffer overlay) 696 | ;; If we're cleaning up we don't need to bother restoring text 697 | ;; or checking for inner overlays to delete 698 | (unless no-restore-p 699 | (let* ((start (overlay-start overlay)) 700 | (end (overlay-end overlay)) 701 | (text (overlay-get overlay 'macrostep-original-text)) 702 | (sexp-end 703 | (copy-marker 704 | (if (equal (char-before end) ?\n) (1- end) end)))) 705 | (macrostep-collapse-overlays-in start end) 706 | (goto-char (overlay-start overlay)) 707 | (save-excursion 708 | (insert text) 709 | (delete-region (point) sexp-end)))) 710 | ;; Remove overlay from the list and delete it 711 | (setq macrostep-overlays 712 | (delq overlay macrostep-overlays)) 713 | (let ((highlight-overlay (overlay-get overlay 'macrostep-highlight-overlay))) 714 | (when highlight-overlay (delete-overlay highlight-overlay))) 715 | (delete-overlay overlay))) 716 | 717 | (defun macrostep-collapse-overlays-in (start end) 718 | "Collapse all macrostepper overlays that are strictly between START and END. 719 | 720 | Will not collapse overlays that begin at START and end at END." 721 | (dolist (ol (overlays-in start end)) 722 | (when (and (overlay-buffer ol) ; collapsing may delete other overlays 723 | (> (overlay-start ol) start) 724 | (< (overlay-end ol) end) 725 | (overlay-get ol 'macrostep-original-text)) 726 | (macrostep-collapse-overlay ol t)))) 727 | 728 | 729 | ;;; Emacs Lisp implementation 730 | 731 | (defun macrostep-sexp-bounds () 732 | "Find the bounds of the macro form nearest point. 733 | 734 | If point is not before an open-paren, moves up to the nearest 735 | enclosing list. If the form at point is not a macro call, 736 | attempts to move forward to the next macro form as determined by 737 | `macrostep-macro-form-p-function'. 738 | 739 | Returns a cons of buffer positions, (START . END)." 740 | (save-excursion 741 | (if (not (looking-at "[(`]")) 742 | (backward-up-list 1)) 743 | (if (equal (char-before) ?`) 744 | (backward-char)) 745 | (let ((sexp (funcall macrostep-sexp-at-point-function)) 746 | (env (funcall macrostep-environment-at-point-function))) 747 | ;; If this isn't a macro form, try to find the next one in the buffer 748 | (unless (funcall macrostep-macro-form-p-function sexp env) 749 | (condition-case nil 750 | (macrostep-next-macro) 751 | (error 752 | (if (consp sexp) 753 | (error "(%s ...) is not a macro form" (car sexp)) 754 | (error "Text at point is not a macro form")))))) 755 | (cons (point) (scan-sexps (point) 1)))) 756 | 757 | (defun macrostep-sexp-at-point (&rest _ignore) 758 | "Return the sexp near point for purposes of macro-stepper expansion. 759 | 760 | If the sexp near point is part of a macro expansion, returns the 761 | saved text of the macro expansion, and does not read from the 762 | buffer. This preserves uninterned symbols in the macro 763 | expansion, so that they can be fontified consistently. (See 764 | `macrostep-print-sexp'.)" 765 | (or (get-text-property (point) 'macrostep-expanded-text) 766 | (sexp-at-point))) 767 | 768 | (defun macrostep-macro-form-p (form environment) 769 | "Return non-nil if FORM would be evaluated via macro expansion. 770 | This is considered within ENVIRONMENT. 771 | 772 | If FORM is an invocation of a macro defined by `defmacro' or an 773 | enclosing `cl-macrolet' form, return the symbol `macro'. 774 | 775 | If `macrostep-expand-compiler-macros' is non-nil and FORM is a 776 | call to a function with a compiler macro, return the symbol 777 | `compiler-macro'. 778 | 779 | Otherwise, return nil." 780 | (car (macrostep--macro-form-info form environment t))) 781 | 782 | (defun macrostep--macro-form-info (form environment &optional inhibit-autoload) 783 | "Return information about macro definitions that apply to FORM. 784 | 785 | If no macros are involved in the evaluation of FORM within 786 | ENVIRONMENT, returns nil. Otherwise, returns a cons (TYPE 787 | . DEFINITION). 788 | 789 | If FORM would be evaluated by a macro defined by `defmacro', 790 | `cl-macrolet', etc., TYPE is the symbol `macro' and DEFINITION is 791 | the macro definition, as a function. 792 | 793 | If `macrostep-expand-compiler-macros' is non-nil and FORM would 794 | be compiled using a compiler macro, TYPE is the symbol 795 | `compiler-macro' and DEFINITION is the function that implements 796 | the compiler macro. 797 | 798 | If FORM is an invocation of an autoloaded macro, the behavior 799 | depends on the value of INHIBIT-AUTOLOAD. If INHIBIT-AUTOLOAD is 800 | nil, the file containing the macro definition will be loaded 801 | using `load-library' and the macro definition returned as normal. 802 | If INHIBIT-AUTOLOAD is non-nil, no files will be loaded, and the 803 | value of DEFINITION in the result will be nil." 804 | (if (not (and (consp form) 805 | (symbolp (car form)))) 806 | `(nil . nil) 807 | (let* ((head (car form)) 808 | (local-definition (assoc-default head environment #'eq))) 809 | (if local-definition 810 | `(macro . ,local-definition) 811 | (let ((compiler-macro-definition 812 | (and macrostep-expand-compiler-macros 813 | (or (get head 'compiler-macro) 814 | (get head 'cl-compiler-macro))))) 815 | (if (and compiler-macro-definition 816 | (not (eq form 817 | (apply compiler-macro-definition form (cdr form))))) 818 | `(compiler-macro . ,compiler-macro-definition) 819 | (condition-case nil 820 | (let ((fun (indirect-function head))) 821 | (cl-case (car-safe fun) 822 | ((macro) 823 | `(macro . ,(cdr fun))) 824 | ((autoload) 825 | (when (memq (nth 4 fun) '(macro t)) 826 | (if inhibit-autoload 827 | `(macro . nil) 828 | (load-library (nth 1 fun)) 829 | (macrostep--macro-form-info form nil)))) 830 | (t 831 | `(nil . nil)))) 832 | (void-function nil)))))))) 833 | 834 | (defun macrostep-expand-1 (form environment) 835 | "Return result of macro-expanding by exactly one step the top level of FORM. 836 | This is done within ENVIRONMENT. 837 | 838 | Unlike `macroexpand', this function does not continue macro 839 | expansion until a non-macro-call results." 840 | (cl-destructuring-bind (type . definition) 841 | (macrostep--macro-form-info form environment) 842 | (cl-ecase type 843 | ((nil) 844 | form) 845 | ((macro) 846 | (apply definition (cdr form))) 847 | ((compiler-macro) 848 | (let ((expansion (apply definition form (cdr form)))) 849 | (if (equal form expansion) 850 | (error "Form left unchanged by compiler macro") 851 | expansion)))))) 852 | 853 | (put 'macrostep-grab-environment-failed 'error-conditions 854 | '(macrostep-grab-environment-failed error)) 855 | 856 | (defun macrostep-environment-at-point () 857 | "Return the local macro-expansion environment at point, if any. 858 | 859 | The local environment includes macros declared by any `macrolet' 860 | or `cl-macrolet' forms surrounding point, as well as by any macro 861 | forms which expand into a `macrolet'. 862 | 863 | The return value is an alist of elements (NAME . FUNCTION), where 864 | NAME is the symbol locally bound to the macro and FUNCTION is the 865 | lambda expression that returns its expansion." 866 | ;; If point is on a macro form within an expansion inserted by 867 | ;; `macrostep-print-sexp', a local environment may have been 868 | ;; previously saved as a text property. 869 | (let ((saved-environment 870 | (get-text-property (point) 'macrostep-environment))) 871 | (if saved-environment 872 | saved-environment 873 | ;; Otherwise, we (ab)use the macro-expander to return the 874 | ;; environment at point. If point is not at an evaluated 875 | ;; position in the containing form, 876 | ;; `macrostep-environment-at-point-1' will raise an error, and 877 | ;; we back up progressively through the containing forms until 878 | ;; it succeeds. 879 | (save-excursion 880 | (catch 'done 881 | (while t 882 | (condition-case nil 883 | (throw 'done (macrostep-environment-at-point-1)) 884 | (macrostep-grab-environment-failed 885 | (condition-case nil 886 | (backward-sexp) 887 | (scan-error (backward-up-list))))))))))) 888 | 889 | (defun macrostep-environment-at-point-1 () 890 | "Attempt to extract the macro environment that would be active at point. 891 | 892 | If point is not at an evaluated position within the containing 893 | form, raise an error." 894 | ;; Macro environments are extracted using Emacs Lisp's builtin 895 | ;; macro-expansion machinery. The form containing point is copied 896 | ;; to a temporary buffer, and a call to 897 | ;; `--macrostep-grab-environment--' is inserted at point. This 898 | ;; altered form is then fully macro-expanded, in an environment 899 | ;; where `--macrostep-grab-environment--' is defined as a macro 900 | ;; which throws the environment to a uniquely-generated tag. 901 | (let* ((point-at-top-level 902 | (save-excursion 903 | (while (ignore-errors (backward-up-list) t)) 904 | (point))) 905 | (enclosing-form 906 | (buffer-substring point-at-top-level 907 | (scan-sexps point-at-top-level 1))) 908 | (position (- (point) point-at-top-level)) 909 | (tag (make-symbol "macrostep-grab-environment-tag")) 910 | (grab-environment '--macrostep-grab-environment--)) 911 | (if (= position 0) 912 | nil 913 | (with-temp-buffer 914 | (emacs-lisp-mode) 915 | (insert enclosing-form) 916 | (goto-char (+ (point-min) position)) 917 | (prin1 `(,grab-environment) (current-buffer)) 918 | (let ((form (read (copy-marker (point-min))))) 919 | (catch tag 920 | (cl-letf (((symbol-function #'message) (symbol-function #'format))) 921 | (with-no-warnings 922 | (ignore-errors 923 | (macroexpand-all 924 | `(cl-macrolet ((,grab-environment (&environment env) 925 | (throw ',tag env))) 926 | ,form))))) 927 | (signal 'macrostep-grab-environment-failed nil))))))) 928 | 929 | (defun macrostep-collect-macro-forms (form &optional environment) 930 | "Identify sub-forms of FORM which undergo macro-expansion. 931 | 932 | FORM is an Emacs Lisp form. ENVIRONMENT is a local environment of 933 | macro definitions. 934 | 935 | The return value is a list of two elements, (MACRO-FORM-ALIST 936 | COMPILER-MACRO-FORMS). 937 | 938 | MACRO-FORM-ALIST is an alist of elements of the form (SUBFORM 939 | . ENVIRONMENT), where SUBFORM is a form which undergoes 940 | macro-expansion in the course of expanding FORM, and ENVIRONMENT 941 | is the local macro environment in force when it is expanded. 942 | 943 | COMPILER-MACRO-FORMS is a list of subforms which would be 944 | compiled using a compiler macro. Since there is no standard way 945 | to provide a local compiler-macro definition in Emacs Lisp, no 946 | corresponding local environments are collected for these. 947 | 948 | Forms and environments are extracted from FORM by instrumenting 949 | Emacs's builtin `macroexpand' function and calling 950 | `macroexpand-all'." 951 | (let* ((macro-form-alist '()) 952 | (compiler-macro-forms '()) 953 | (override (lambda (real-macroexpand form environment &rest args) 954 | (let ((expansion 955 | (apply real-macroexpand form environment args))) 956 | (cond ((not (eq expansion form)) 957 | (setq macro-form-alist 958 | (cons (cons form environment) 959 | macro-form-alist))) 960 | ((and (consp form) 961 | (symbolp (car form)) 962 | macrostep-expand-compiler-macros 963 | (not (eq form 964 | (cl-compiler-macroexpand form)))) 965 | (setq compiler-macro-forms 966 | (cons form compiler-macro-forms)))) 967 | expansion)))) 968 | (cl-macrolet ((with-override (fn &rest body) 969 | `(cl-letf (((symbol-function ,fn) 970 | (apply-partially override (indirect-function ,fn)))) 971 | ,@body)) 972 | (with-macroexpand-1 (&rest body) 973 | (if (< emacs-major-version 30) 974 | `(progn ,@body) `(with-override #'macroexpand-1 ,@body))) 975 | (with-macroexpand (&rest body) 976 | `(with-override #'macroexpand ,@body))) 977 | (with-macroexpand-1 978 | (with-macroexpand 979 | (ignore-errors 980 | (macroexpand-all form environment))))) 981 | (list macro-form-alist compiler-macro-forms))) 982 | 983 | (defvar macrostep-collected-macro-form-alist nil 984 | "An alist of macro forms and environments. 985 | Controls the printing of sub-forms in `macrostep-print-sexp'.") 986 | 987 | (defvar macrostep-collected-compiler-macro-forms nil 988 | "A list of compiler-macro forms to be highlighted in `macrostep-print-sexp'.") 989 | 990 | (defun macrostep-pp (sexp environment) 991 | "Pretty-print SEXP, fontifying macro forms and uninterned symbols. 992 | This is done within ENVIRONMENT." 993 | (cl-destructuring-bind 994 | (macrostep-collected-macro-form-alist 995 | macrostep-collected-compiler-macro-forms) 996 | (macrostep-collect-macro-forms sexp environment) 997 | (let ((print-quoted t)) 998 | (macrostep-print-sexp sexp) 999 | ;; Point is now after the expanded form; pretty-print it 1000 | (save-restriction 1001 | (narrow-to-region (scan-sexps (point) -1) (point)) 1002 | (save-excursion 1003 | (pp-buffer) 1004 | ;; Remove the extra newline inserted by pp-buffer 1005 | (goto-char (point-max)) 1006 | (delete-region 1007 | (point) 1008 | (save-excursion (skip-chars-backward " \t\n") (point)))) 1009 | ;; Indent the newly-inserted form in context 1010 | (widen) 1011 | (save-excursion 1012 | (backward-sexp) 1013 | (indent-sexp)))))) 1014 | 1015 | ;; This must be defined before `macrostep-print-sexp': 1016 | (defmacro macrostep-propertize (form &rest plist) 1017 | "Evaluate FORM, applying syntax properties in PLIST to any inserted text." 1018 | (declare (indent 1) 1019 | (debug (&rest form))) 1020 | (let ((start (make-symbol "start"))) 1021 | `(let ((,start (point))) 1022 | (prog1 1023 | ,form 1024 | ,@(cl-loop for (key value) on plist by #'cddr 1025 | collect `(put-text-property ,start (point) 1026 | ,key ,value)))))) 1027 | 1028 | (defun macrostep-print-sexp (sexp) 1029 | "Insert SEXP like `print', fontifying macro forms and uninterned symbols. 1030 | 1031 | Fontifies uninterned symbols and macro forms using 1032 | `font-lock-face' property, and saves the actual text of SEXP's 1033 | sub-forms as the `macrostep-expanded-text' text property so that 1034 | any uninterned symbols can be reused in macro expansions of the 1035 | sub-forms. See also `macrostep-sexp-at-point'. 1036 | 1037 | Macro and compiler-macro forms within SEXP are identified by 1038 | comparison with the `macrostep-collected-macro-form-alist' and 1039 | `macrostep-collected-compiler-macro-forms' variables, which 1040 | should be dynamically let-bound around calls to this function." 1041 | (cond 1042 | ((symbolp sexp) 1043 | ;; Fontify gensyms 1044 | (if (not (eq sexp (intern-soft (symbol-name sexp)))) 1045 | (macrostep-propertize 1046 | (prin1 sexp (current-buffer)) 1047 | 'font-lock-face (macrostep-get-gensym-face sexp)) 1048 | ;; Print other symbols as normal 1049 | (prin1 sexp (current-buffer)))) 1050 | 1051 | ((listp sexp) 1052 | ;; Print quoted and quasiquoted forms nicely. 1053 | (let ((head (car sexp))) 1054 | (cond ((and (eq head 'quote) ; quote 1055 | (= (length sexp) 2)) 1056 | (insert "'") 1057 | (macrostep-print-sexp (cadr sexp))) 1058 | 1059 | ((and (eq head '\`) ; backquote 1060 | (= (length sexp) 2)) 1061 | (if (assq sexp macrostep-collected-macro-form-alist) 1062 | (macrostep-propertize 1063 | (insert "`") 1064 | 'macrostep-expanded-text sexp 1065 | 'macrostep-macro-start t 1066 | 'font-lock-face 'macrostep-macro-face) 1067 | (insert "`")) 1068 | (macrostep-print-sexp (cadr sexp))) 1069 | 1070 | ((and (memq head '(\, \,@)) ; unquote 1071 | (= (length sexp) 2)) 1072 | (princ head (current-buffer)) 1073 | (macrostep-print-sexp (cadr sexp))) 1074 | 1075 | (t ; other list form 1076 | (cl-destructuring-bind (macro? . environment) 1077 | (or (assq sexp macrostep-collected-macro-form-alist) 1078 | '(nil . nil)) 1079 | (let 1080 | ((compiler-macro? 1081 | (memq sexp macrostep-collected-compiler-macro-forms))) 1082 | (if (or macro? compiler-macro?) 1083 | (progn 1084 | ;; Save the real expansion as a text property on the 1085 | ;; opening paren 1086 | (macrostep-propertize 1087 | (insert "(") 1088 | 'macrostep-macro-start t 1089 | 'macrostep-expanded-text sexp 1090 | 'macrostep-environment environment) 1091 | ;; Fontify the head of the macro 1092 | (macrostep-propertize 1093 | (macrostep-print-sexp head) 1094 | 'font-lock-face 1095 | (if macro? 1096 | 'macrostep-macro-face 1097 | 'macrostep-compiler-macro-face))) 1098 | ;; Not a macro form 1099 | (insert "(") 1100 | (macrostep-print-sexp head)))) 1101 | 1102 | ;; Print remaining list elements 1103 | (setq sexp (cdr sexp)) 1104 | (when sexp (insert " ")) 1105 | (while sexp 1106 | (if (listp sexp) 1107 | (progn 1108 | (macrostep-print-sexp (car sexp)) 1109 | (when (cdr sexp) (insert " ")) 1110 | (setq sexp (cdr sexp))) 1111 | ;; Print tail of dotted list 1112 | (insert ". ") 1113 | (macrostep-print-sexp sexp) 1114 | (setq sexp nil))) 1115 | (insert ")"))))) 1116 | 1117 | ;; Print everything except symbols and lists as normal 1118 | (t (prin1 sexp (current-buffer))))) 1119 | 1120 | (defun macrostep-get-gensym-face (symbol) 1121 | "Return the face to use in fontifying SYMBOL in printed macro expansions. 1122 | 1123 | All symbols introduced in the same level of macro expansion are 1124 | fontified using the same face (modulo the number of faces; see 1125 | `macrostep-gensym-faces')." 1126 | (or (get symbol 'macrostep-gensym-face) 1127 | (progn 1128 | (if (not macrostep-gensyms-this-level) 1129 | (setq macrostep-gensym-depth (1+ macrostep-gensym-depth) 1130 | macrostep-gensyms-this-level t)) 1131 | (let ((face (ring-ref macrostep-gensym-faces macrostep-gensym-depth))) 1132 | (put symbol 'macrostep-gensym-face face) 1133 | face)))) 1134 | 1135 | 1136 | (provide 'macrostep) 1137 | ;;; macrostep.el ends here 1138 | --------------------------------------------------------------------------------