Skip to content

Instantly share code, notes, and snippets.

@sogaiu

sogaiu/janet-projects-notes.txt

Last active February 10, 2026 05:32
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save sogaiu/9ddbac987c15749c5d98c642b62d79a3 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save sogaiu/9ddbac987c15749c5d98c642b62d79a3 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
janet-projects-notes.txt
* make all new things not use project.janet as much as possible?
following things still have project.janet (not comprehensive):
babashka-tasks-view
clojure-peg
forcett
git-some-janets
index-janet
index-janet-source
jandent
janet-bencode
janet-bits
janet-bounds
janet-checksums
janet-delims
janet-docstring-notes
janet-editor-elf
janet-indent
janet-jsonish
janet-last-expression
janet-localpath
janet-location-zipper
janet-minipbt-translation
janet-notrepl
janet-pcg-random
janet-pegdoc
janet-peg
janet-please
janet-punyishcode
janet-ref
janet-repl
janet-socket-repl
janet-subprocess-notes
janet-syntax-highlighting
janet-tempdir
janet-tempfiles
janet-termsize
janet-totp
janet-tree-sitter
janet-ts-dsl
janet-unwrap
janet-vendor-sample
janet-walk-dir
janet-xmlish
janet-zipper
jaylib-netrepl-demo
jaylib-tetris
jaylib-wasm-demo
jdnish-peg
jdoc
jeat-toolz
jog
jpm-tasks-view
judge-gen
look-up-janet-def
margaret
pajama
review-janet
small-peg-tracer
spork-htmlgen-sample
spork-http-sample
* try to make pieces of project usable as "single file"
* who-uses would be helpful for figuring out which projects
need to be updated
* before "redoing" a project, find whether any projects are being used
as dependencies. if it isn't, easier to just change things.
* use jipper to get at :dependencies value in declare-project in
project.janet? is this a bit like querying?
* also scan for files where something might be vendored?
* could apply to determine how often each project (of all collected
projects) is being reused across all collected projects?
* who-uses / what-uses command ("inquiry", "ask")
* learning about usage of various projects
* figure out what projects need updating
* project.janet declare-project based search
* info.jdn based search
* find info.jdn, parse content, look for vendored key,
examine associated value
* filename (optionally checksum?) based search (who-has command?)
* use as part of figuring out batch updating of some vendored piece
followed by batch testing?
* random
* castanet - querying program
* other folks' interesting bits
* janet-pnlib
* janet-pnxml
* arrange for vendored files that are used as ingredients in the
process of building the final artifact to live in a location that
is slightly different (so not right next to other files in src/)
to help avoid accidental editing. a dir like src/deps/ might
work. directories "outside" of src/ aren't currently supported by
jell.
* create pre-commit scripts using sh-dsl in various projects
tried already in:
* empathy
* jackal
* janet-punyishcode
* jargon
* jell
* jog
* jref
* margaret
* niche
* pdoc
* small-peg-tracer
consider a different name for the script. may be "prep"?
how can it be made easier to execute? putting it in the
repository root is one way. any other ways?
* certain functions are being used by "other projects", perhaps
these should be documented as being an intended to be used api.
e.g. gen and par from location.janet. may be this fits well
providing a single file in the root of a repository?
* any way to automate the discovery of which functions are used by
which projects and how often?
* used-by command
* single repository that vendors all / many tools for ease of
obtaining?
* picky
* remote vendoring - git, curl, other?
* local vendoring (copy jakl.janet to jakl)
* ordered operations, because sometimes order matters
* store checksums?
* apply sh-dsl - though may be it's nicer if that is used in
combination with parsing info from info.jdn
https://gist.github.com/sogaiu/d7de7e88bbc4461654890f3919f1db56
* format for specifying file paths to copy / retain
* collect actual use cases
* specifying all desired paths explicitly seems like it could be
laborious (though may be it's better?). this motivates things
like glob patterns, but may be those can lead to certain kinds
of otherwise non-existent problems?
* specifying things to not copy / retain seems convenient, but
as with glob patterns, isn't this likely to lead to certain
kinds of issues?
* perhaps in the end, an explicit list of paths is the least
problematic approach?
https://stackoverflow.com/a/18538444
https://stackoverflow.com/a/1060061
* patchy - for patching files? how about something like editscript?
* snap (input), crackle (transform), pop (output)
* jed - a bit like sed, but for editing janet and jdn?
* repository organization
* make the main deliverable `<name>.janet` -- the extension is
important if wanting to be able to use as a library. nicest if
this deliverable sits in the repository root as well.
* for libraries, could still have a `<name>` directory that has the
content `init.janet` and `<name>.janet` for jpm / jeep
installation, but `<name>.janet` can still be used independently
as a single file library? would be nice to have `<name>.janet` at
the repository root. how to avoid the multiple files getting out
of sync though...
* jeep vendoring to track bits and their "versions". better for
reproducibility and investigation. if not going to use jeep, need
own vendoring bits. the pieces can be brought together in a
single file using a tool like jell.
* by default, jell now embeds a date-time string as a version string
in the file it produces. this is potentially helpful for the case
where the file is copied elsewhere and later one wants to get a
sense of which "version" it might be. (don't commit obj
directories.)
* can still provide jpm / jeep / etc. installation methods.
* for some repositories, am bundling the specific jtfm.jdn
(transitioning to .tche.jdn) and jell files. this makes the
specific dev bits more self-contained and less brittle. currently
they can be brought in via jeep's vendoring mechanism.
* for non-windows, can copy the `<name>.janet` file to PATH as
`<name>`, or clone the repository and symlink from one's PATH dir to
`<name>.janet`, but call the link `<name>`.
* need to think a bit more for what to do about windows...shim,
.bat launcher, etc...just include a suitable .bat file in the
repository?
* would be nice if README was straight-forward and simple.
currently trying just usage output - but what about installation
instructions...
* random
* argument 0 of args might be inspected to change the behavior of a
janet script. is there some value in this? one can make multiple
symlinks to the same file, each symlink having a different name
for example.
* fast-forwarding may have the benefit that the commit hashes used
to vendor various points along the refine-renaming branch won't
change so bundle/info.jdn files that used those commit hashes
won't need to change.
* project organization
apart from the repository organization, keep at least one notes.txt
file which most likely doesn't get committed to the repository.
notes.txt could contain:
* description
* rationale
* non-goals
* limits
* random (for capturing stuff)
* hidden features
* semi-recurring tasks
* pre commit steps
* identifying and addressing synchronization issues
some projects are ending up with files with different names but
the same content, e.g. jackal has `jakl` and `jakl.janet`. is
there some way to avoid these bits getting out of sync?
yes, this is now done via a pre-commit script.
vendor within the project using jeep? this would at least make it
possible to have only a single command that keeps things
up-to-date...
also, using jell means that "compiled" output might not be
up-to-date...so this is also a synchronization issue.
usage output being used in the README is also another
synchronization situation.
tests ought to be run before commiting as well. how can this be
checked?
perhaps having a single command to automate at least checking if
things are out-of-sync would be useful?
would do nothing scripts be any use?
there is now a pre-commit script in some projects -- it could
also have portions that are "do nothing" (but remind)
* testing
* frequent enough batch testing across all projects
* sub-batch testing for things like jell
* testing of things in jtfm's search.janet is light perhaps because
it involves the filesystem. are there good ways to test such
things? touching of secondary storage has issues related to
creating and destroying things?
* platform-specific testing is not so straight-forward?
e.g. windows file system paths are different from *nix paths.
* unwanted duplication
* jtfm's parse-path (in utils.janet) appears to be something similar
to split-path from jell's utils.janet. also take a look at
localpath.janet (from janet-localpath).
* operational points
* adopt approach of recording thoughts in notes.txt but waiting
until need is dire, painful, etc. to work on implementation or
even sketching out what an implementation might look like?
* spend time between "read-only mode" (e.g. via a tablet) and
sitting in front of editor. switch between them as well as
spending time on other things (allow background processing).
* benefits from having a decent data formatter (e.g. suspect that
zprint can do this for clojure)
* less time spent on manual formatting while working with source in
an editor (at least the actual value portions of tests)
* programmatic updating of actual values in jtfm
* investigating unformatted data values shared by others should
become easier
* other folks can use the tool to format the values they are about
to share.
* notes on data formatting / pretty printing
* possibly a "good enough" / "close enough" thing plus manual
intervention would be better than nothing? or may be one
could use the existing value as a hint for formatting the new
value in some cases?
* could it somehow be easier to use zippers for reformatting?
the clojure zprint program uses rewrite-clj. perhaps there
are some hints there...
* if an approach that ignored line lengths were adopted
initially, could it be practically adapted to an approach that
accounted for line length limits?
* indenting the formatted result should match the indentation
that the editor provides so when working in an editor with the
"results", indentation doesn't alter what was generated.
* some constructs may not be desirable for output such as
long-strings and long-buffers. in source code, these can end
up being affected by special "dedenting" and they evaluate to
strings anyway so it might be better to avoid using them for
output (except if non-multiline?).
paren arrays (e.g. `@(:a :b)`) are also an "input"
representation. they just evaluate to ordinary (i.e. square
bracket) arrays anyway so these may also be "ignorable".
ordinary (i.e. "round paren") tuples may be good to avoid as
well because expected values that contain them don't expect
them to resolve to function / macro / etc. calls. may be
better to stick with square bracket tuples or quote paren
tuples (the former seems nicer, but not sure if that might
cause issues).
hex and other non-decimal ways of expressing numbers for input
might be problematic for output. how would one know when to
use some non-decimal representation?
comparing expected and actual results for numbers seems tricky
/ problematic because of things like:
(= 0.3 (+ 0.1 0.2))
# =>
false
quoting and quasiquoting don't show up in output. they, like
other reader macros, get transformed into "calls", e.g. 'a is
replaced with (quote a), ~a is replaced with (quasiquote a)
line comments will not be output as they can't be the result
of evaluation.
draft list of things to handle in an output format:
* nil, true, false (constants)
* decimal numbers
* strings (using double quote delimiters)
* buffers (handle similarly to strings)
* keywords
* symbols
* bracket array
* bracket tuple
* table
* struct
* non-eol whitespace
* eol sequence
the "atomic" things in the list above (starting at `nil` and
continuing through symbols) should never be "broken" across lines
(except perhaps buffers and strings using the functions `buffer`
or `string` but that kind of thing should probably be held off on
until much later if at all?). in practice, things strings and
buffers seem like they can end up being quite a bit longer than
constants, numbers, keywords, and symbols.
non-atomic things (from bracket arrays through structs) can
(and likely should in some cases) be broken across lines to
improve readability.
non-eol whitespace and eol sequences are probably most of what
can be manipulated toward arriving at an improved formatting
of data?
the collections (e.g. structs, etc.) have visible delimiters.
the opening sets of delimiters are just like atomic things
from a formatting perspective(?). the closing delimiters can
bunch up and possibly end up making the last "item" of a
collection "longer".
* come up with samples of formatted data? spelling out specific
data (e.g. structs, tuples, etc.) and then observing the
process of formatting them might result in ideas for various
approaches? collect samples in to a directory as individual
files instead of inlining them in this file?
* jeep vendoring notes
trying to switch to using jeep's vendoring.
this should result in:
* tracking of explicit pieces and commits used when vendoring
* no more use of git subrepo
* switching over to use jtfm (over jeat)
* usage of jell where it makes sense
-----------------------------------------
transition away from git subrepo and jeat
-----------------------------------------
------------------
not so useful atm?
------------------
* clojure-peg
* jeat
* janet-bits
* jeat
* index-janet-source
* jeat
* janet-please
* jeat
* jpm-tasks-view
* jeat
* babashka-tasks-view
* clojure-peg
* janet-zipper
* jeat
* janet-editor-elf
* janet-bounds
* janet-indent
* janet-unwrap
* jeat
--------
consider
--------
* jdoc?
* janet-localpath
* jeat
* janet-minipbt-transation
* jeat
* janet-syntax-highlighting
* jeat
* janet-tempdir
* jeat
* janet-xmlish
* jeat
* janet-zipper (5)
* jeat
* review-janet
* jeat
* janet-bounds (2)
* janet-delims
* janet-peg
* jeat
* janet-indent (1)
* janet-delims
* jandent
* jeat
* janet-unwrap (1)
* janet-bounds
* janet-delims
* jeat
--------
archived
--------
* janet-pegdoc - made pdoc which is a replacement / successor?
* janet-ref - made jref which is a replacement / successor?
* janet-walk-dir
- someone might have been using, but perhaps no longer?
----------
to archive
----------
* janet-delims (4) -> dalimit
- actually has a janet-delims/init.janet file but
probably doesn't need?
* janet-last-expression -> lastly
* jandent -> gappy? dent? arthur?
- indent.janet (like spork/fmt)
- jindt.janet (executable) - just drop or make binscript?
* janet-indent -> ?
- indent-line.janet
- indent-region.janet
- locations.janet (another janet grammar but diff from janet-peg ones)
* janet-location-zipper -> jipper
* janet-peg
* janet-zipper
* jeat
* janet-aliases -> add similar thing to jipper's usages?
* janet-pcg-random
* jeat
* pcg-c
------------
newly create
------------
* collection of janet-pegs? rename files and some internals (e.g. jg)?
use sh-dsl to build three targets?
include pieces:
* grammar.janet
* rewrite.janet (uses grammar.janet)
* location.janet
* bounds.janet
* locations.janet (from janet-indent)
* loc.janet (from review-janet)
* merge all of the indentation stuff (jandent and janet-indent)?
use sh-dsl to build three targets (use subdirs for each?)?
- jandent.janet - make it a library and a binscript (incorporate jindt)?
- indent-line.janet
- indent-region.janet
--------------
has native bit
--------------
* pcgrand
-----------------------
uses jell - single file
-----------------------
* index-janet (2)
* jackal
* jargon
* jell
* jipper
- vendor location.janet from janet-peg, but if janet-peg is split up...
* jog
* jref
* lastly (1)
* look-up-janet-def (1)
* niche
* pdoc
* quiche
* small-peg-tracer
--------------------------------
uses jell - not just single file
--------------------------------
* jandent (3)
- still has executable in project.janet - split off?
- also library bits unclear?
* janet-totp
- gh-totp is built using jell - split off?
- janet-totp dir has lib files
- base32.janet
- hmac-sha-1.janet
- hotp.janet
- totp.janet
----------------------------------------------------
not single-file - should it be or possibly split up?
----------------------------------------------------
* janet-checksums
- pieces
- md5.janet - utils, uint32
- sha-1.janet - utils, uint32
- sha-2.janet - utils, uint32, uint64
- uint32.janet
- uint64.janet
- utils.janet
- split off uint32 and uint64 into own project(s) and vendor?
- then split off md5 on its own
- then split off sha-* elsewhere
- what about utils?
* janet-peg (4)
- isn't a single file artifact - split?
- location.janet - used by jipper.janet
- bounds.janet - used by janet-bounds
- rewrite.janet (uses grammar.janet) - used by hiccup lexer
- extras.janet - not really used elsewhere?
- revisit use of lib directory?
- if starting new project, consider renaming things (e.g. jg)
- rewrite.janet can be built via jell
-----------------------------------
doesn't use jell but is single file
-----------------------------------
* dalimit (?)
* janet-etags
* janet-jsonish
* janet-punyishcode
* margaret (2)
------------
transitioned
------------
* ajrepl
* can-we-do-better
--------------------
breaking out pieces?
--------------------
----------------
to remove use of
----------------
* janet-ex-as-tests (34)
* git subrepo
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment