Feature: Users should be able to tell what platform they use.
cmdlucas opened this issue · comments
Despite this PR, I do think that there is a case for allowing users explicitly specify that they use a windows platform, otherwise we default to false.
The Case
First, let us make an assumption that platform.os.family
would always be available from PlatformJS (which is not the case, because I've been failed multiple times).
When a template literal is sent into markdown-yaml-metadata-parser
on a such a confirmed Windows platform, the package fails to read the string as a non-windows file.
To clarify with code:
const yamlParser = require('markdown-yaml-metadata-parser');
const markdown = `
---
title: SpaceX Launch
author: Caleb Lucas
---
Some content here
`
const markdownData = yamlParser(markdown);
console.log(markdownData.metadata) // returns empty object
Since the user is oblivious to the inner workings of this package, an empty object would not be expected. But that's what is gotten because the markdown is being treated as a windows string with \r\n
as the eol.
The case is even more confusing (and that's mildly put) when PlatformJs fails to supply a correct platform.os.family. Could be null or any other false value.
The user sends in markdown file with the same content above, read with fs.readFileSync
or its equivalent and expects to get metadata as specified but gets empty object again because windows platform was not correctly specified.
Proposal
The ultimate fix to this issue, I believe, would be to allow users tell whether to read the input markdown as though on windows or not. That could be achieved by allowing users supply an optional configuration as { windows: boolean}
to the exposed facade.
I'll be implementing this and submitting a new PR.
Hi @cmdlucas ,
thanks for your time and effort to improve this module, I appreciate it.
Regarding the PR, I was already not totally convinced of the platform.js solution that is in place right now. Your idea made me think once again.
This library should only be doing one thing, that is parsing metadata. Checking the platform is probably too much, and even useless. The only thing that matters is: what is the new line char in the provided text?
That's why I think, instead of checking the platform, we should just determine the new line char. I see that's something you've partially introduced, but probably we could also use a library for that (e.g. https://github.com/sindresorhus/detect-newline) so to keep the single responsibility principle for this module.
In this case the windows attribute wouldn't be needed, which I'll probably prefer in order to keep the module agnostic and simple.
That's my idea for updating the module, what do you think?
Thanks again for your time,
Alberto
Hello @ninjabachelor
I think it makes perfect sense to determine the new line. In fact, in one of my commits (see here), I removed the PlatformJS dependency completely but later reverted (see here) because I was unsure about how much users currently unknowingly depend on the PlatformJS feature for browser environments. I was worried that it might trigger unforeseen breaking changes when I was simply trying to introduce a release that is backward compatible.
But from what I now understand, the source is simply supplied as a string, so the PlatformJS dependency should be removed. So, I agree that the detect-newline package would be helpful in doing just the detection of newline.
In addition, the reason for PR #12 , is to set the background for a future where, apart from windows config, other configurations can be sent in and used by the package to infer more details about the metadata being parsed, without introducing unintended bugs. As I understand, the functional programming style inhibits that.
However, if a scenario where user-supplied configuration is not foreseen for the future, then PR #12 is useless. We would just need to detect the new line (using any one of the values from our default newline, the new-line detector) and then continue with the parsing.
I'll be glad to submit another PR based on the direction we're headed.
Cheers,
Caleb
Hi @cmdlucas ,
yes, I would proceed in this direction. For now, I would keep the module simple, remove the platform and add the new line char detection.
If in the future we'll see the need of a user-supplied configuration, your PR will be a very good starting point.
I've started creating a new branch (v2.1) and added some micro-changes. Feel free to help with a PR starting from that if you like.
Thanks!
Alberto
Hi @cmdlucas ,
I've published version 2.1.0 with the ideas discussed here.
Thank you very much for your time and inputs to improve this module.
Cheers,
Alberto