LispCookbook / LispCookbook/cl-cookbook

Data structures page revamps

Open
#625 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
1.1k
Forks
158
Avg merge
6d 3h
Merged PRs (30d)
2

Description

I noticed that there is a section on the data structures page that notes how you can use plists as queues. It at least goes on to clarify that these are LIFO queues. In my opinion such structures should never be referred to as queues, but stacks; a queue without any clarification is typically implicitly a FIFO queue (vs. e.g. a priority queue), and plists don't offer a particularly good way of implementing that. They can be implemented with a combination of setf + append (for enqueuing) and remf (for dequeuing), but the example should show this explicitly if it's going to talk about queues, or my suggestion just remove the section entirely.

Similarly, there is no example for pop on normal lists, but it would make sense to call out the combination of push and pop making for a good enough stack implementation.

The concept of "shadowing", where a key appears multiple times in either a plist or an alist, may be worth explaining separately, but not in relation to queues or stacks. I think its best use case (especially with alists) is that it offers a way to cheaply push (to the head) most-recent state while preserving the mutation history and not requiring you to iterate a list to find an exact key to modify or remove. For example, from the Land of Lisp book, the author uses an alist of item name -> location in a simple text adventure game. It's initialized with items and their initial locations, but if the player "picks up" an item, then instead of a list-traversing setf to modify its location, he just pushes a new item name -> body association. Dropping an item can also just be another push of the item with its new location. (Whether this is a good use of the feature is debatable vs. just doing things with a hash table or database or having a locations -> items association instead, the book does talk about it some, but the example demonstrating shadowing behavior did completely go over at least one reader's head, nevertheless it's better than bringing in queues or stacks to elaborate on the spec's description of assoc and getf using the first matching indicator if there are multiple matching. Personally I think the whole concept can be omitted.)

For a bigger change to the page, it'd be worth talking about more data structures explicitly and what the CL ecosystem offers, with examples, and ideally even data-backed suggestions when there are multiple candidates. This is of course a bigger undertaking and would require maintenance. Just for queues, the picture is complicated: e.g. you could build your own with lists and nconc and take the O(N) hit on enqueue, but "serapeum/queue" has a usually-good-enough list-based one based on Norvig that uses a clever trick to avoid the O(N) behavior in enqueue , but there's also the various queues in "lparallel" (mentioned on the concurrency page) which offer thread-safety and optional fixed-capacity behavior. (Though simple semaphores can sometimes be used for bounded-queue behavior.) There are also a few lock-free queue implementations out there.

In short, the page could use more meat and do better than even the haphazard listing at awesome-cl so there's less need for people to figure things out on their own and more following recipes.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked data structures page and review its existing plist, alist, and list examples. Decide which focused revision is in scope, then update the explanations and examples so stack, queue, and shadowing terminology is accurate; broader ecosystem coverage would need an explicit scope and maintenance plan.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.