├── .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 |
--------------------------------------------------------------------------------