felixSchl/neodoc

Publish on pursuit

adius opened this issue ยท 20 comments

adius commented

Great tool, but it does not seem to be published on pursuit, or am I missing something?

Hey, the Purescript side of things has never really taken shape (and i've seen no interest from the Purescript community so far) and the JS side of things turned out to be really low maintenance thanks to the language, which in turn meant I didn't keep this project up to date. It would be quite an undertaking to update this project to compile under the latest version of purescript, hence it's unlikely to happen unless someone's willing to endure the pain of a million compile errors :-/

adius commented

Oh, that's too bad.
I just tried to compile it with the latest version and I got "just" 60 errors and they all had really clear instructions how to fix them, so maybe it's doable...

Don't be deceived, it will be 60 until the compiler can discover the next 60. I mean if you're wanting to get stuck into it, by all means, but just a warning. There's probably a solid day of work in this, if I had to guess.

adius commented

I wanted to give this a shot, but the whole Foreign stuff seems to have changed quite a bit.
What's the correct way to implement this nowadays? https://pursuit.purescript.org/packages/purescript-foreign-generic ?

Oh cool! From what I remember, the biggest change in that department was the removal of the IsForeign typeclass (purescript/purescript-foreign#49). I guess we could backport it or update the code to work w/o the typeclass, which would be the proper way to go about it, I guess

adius commented

Why are there so many places using IsForeign anyways? Shouldn't there just one place where the docstring gets parsed and that's all the interaction with the outside world?

Well, the idea was that the spec itself (the thing describing the structure of the command line) could be passed in directly, thus being able to cache it, or use it's output for other purposes (maybe auto completion etc).

It's essentially doc-string -> spec -> input -> output

The signature of the _run function should make this clear:

_run
:: โˆ€ eff
. Either (Spec UsageLayout) String
-> NeodocOptions
-> Eff (NeodocEff eff) Output
_run input (NeodocOptions opts) = do

I found myself thinking about taking another go at this. @adius how far did you get at the time?

I've produced a dependency graph that might make it easier to get an overview and port piece by piece:

deps

ad-si commented

Hi, my @adius account is unfortunately locked, so I didn't get a notification.
But coincidentally I just came back to this issue, because I saw you working on pure-c (awesome project btw!) and thought maybe we can revive it. ๐Ÿ˜

However, I think I accidentally deleted my progress on porting it ๐Ÿ˜ญ, so I guess we'll have to start from scratch.

Can you maybe answer #93 (comment) again, I didn't really get your answer. I still feel this should be simpler.

Sure, the reason for the IsForeign instances was that - at the time - I was primarily interested to have this library be consumed by JavaScript. So, in order to make sure the values I pass to JS are simple types (i.e. no sum types), and to ensure that whatever I get from JS is actually as advertised, I chose to buy into these type classes. Little did I know they wouldn't be around a year later. Not sure why these type classes are gone in the first place, to be honest.

I'd be happy to ditch JS integration altogether, rename to purescript-neodoc or similar, and build a separate js front end (so neodoc as a purescript library, and neodoc as an npm package). What do you think of that?

Neodoc is already more powerful than the current JS integration let's on, which is a shame. For example, the current output is always run through this lossy fold:

reduce
:: Env
-> List Description
-> Maybe (Branch SolvedLayoutArg)
-> List KeyValue
-> _ -- Map ArgKey RichValue

The structure before the fold has valuable position and association information that just gets tossed.

Another annoying thing - the thing I regret most as of this writing - is that I thought it was a good idea to interpret textual values as JS types (to please the JS crowd). But I diverge. Once we get this updated to the latest compiler version we can move ahead and break as much as we'd like for some v3 release.

ad-si commented

I'd be happy to ditch JS integration altogether, rename to purescript-neodoc or similar, and build a separate js front end (so neodoc as a purescript library, and neodoc as an npm package). What do you think of that?

That sounds like a good idea! Let me know, how I can help. I'd really love to use neodoc for https://github.com/feramhq/transity.

Another annoying thing - the thing I regret most as of this writing - is that I thought it was a good idea to interpret textual values as JS types (to please the JS crowd). But I diverge. Once we get this updated to the latest compiler version we can move ahead and break as much as we'd like for some v3 release.

Hehe, JavaScript's bad practices have a way of getting at you ๐Ÿ˜. I guess I have more opinions on a future version after integrating it in Transity!

ad-si commented

I just forked it and started to resolve compiler errors. Will upload and link it later!

ad-si commented

The hard part is going to be updating all sub dependencies which haven't upgraded to purs 0.12 yet ๐Ÿ˜Ÿ. I recently upgraded Transity from 0.11 to 0.12 and I had to fix like 3 sub-dependencies first. That's also why I switched to https://psc-package.readthedocs.io, as I was able to depend on my own versions until my changes were merged upstream. Shall we proceed likewise with Neodoc?

ad-si commented

My first efforts: #96

This is awesome! I wonder if it would be easier to start with a blank page and start copying modules in based on the dependency graph above?

transity looks awesome by the way, I've always wanted to get into managing my finances on the command line, but couldn't afford the time to learn the existing tools

ad-si commented

This is awesome! I wonder if it would be easier to start with a blank page and start copying modules in based on the dependency graph above?

Mh, If you think your code is decoupled enough, sure. But I'd guess if there is a straight forward way to replace / fix the Foreign usages, it should almost be usable again. And it's always easier to refactor a working solution =P

transity looks awesome by the way, I've always wanted to get into managing my finances on the command line, but couldn't afford the time to learn the existing tools

Thanks! Then you're the perfect user ๐Ÿ˜ ... I'd love to hear your thoughts if you find the time to try it out!

Have you come to an end?

ad-si commented

I'm working on this again in #96.
I'll try to decouple the JavaScript and Purescript code as desribed in #93 (comment). This will be no easy task, but this time I won't let it get me down! ๐Ÿ’ช