mog13 / splain

small parser to create more interesting language/sentences

Splain v3

under construction

splain's Issues

Having entry contexts and dictionary contexts is confusing, we need a different name

right now you can have multiple dictionary's (i.e. EN, FR etc). In the code these are referred to as dictionaryContexts. You can also give an entry a context.

This makes the code unnecessarily confusing to work on and reason about so i propose we come up with a better name.

generate typings file

When built splain should also generate a typings file. This should just be a tsconfig change see: https://stackoverflow.com/questions/34786199/using-webpack-to-generate-typescript-libraries-with-typing-files for example

not closing templates causes an infinite loop

If you don't properly close all templates it causes the template finder to enter an infinite loop,
you can see this with the following test:

   it("should handle unclosed template",()=>{
        Splain.dictionary.addEntry({test1:["a"], test2:["b"], test3:["{{test4}}"], test4:["{{fake}}"]});
        expect(Splain.process("it {{test1 {{test2}} {{test1 test2 test4 {{test3 test4}}}}")).toBe("");
    });

Comment the code

As Splain grows i think commenting some of the more in depth code could be useful. the complexity and recursion makes it easy to get lost and this could provide some relief when working with the code base

Add eslint configuration

Should have eslint configuration added into the project

Codecova config

Should look into config for codecova to set a base minimum for tests rather than if it just decreases. Some decreases are going to happen and it looks bad on the pull request when it may be necessary.

Also need to make sure to ignore certain files as we build tools.

Use interface to avoid any.

When arrays of custom objects are passed we are using any as its a custom object we are expecting values to be on. We should create interfaces for these custom objects to be more explicit.

https://stackoverflow.com/questions/43338763/property-does-not-exist-on-type-object

Should be able to access previously executed templates/context in a variable template

We should think about passing in some sort of context when a variable token is executed. This would allow functions to make decisions based on a previous templates outcome. I'm thinking along the lines of:

Splain.addEntry({colors:["red","green","blue"]});

let getCol = (context) =>{
    if(context.someWayToGetPreviousToken === "red") return "#ff0000";
    if(context.someWayToGetPreviousToken === "green") return "#00ff00";
    if(context.someWayToGetPreviousToken === "blue") return "#0000ff";
    return '#ffffff';
};

console.log(Splain.process("why not try {{colors}} ({{##getCol}})",{getCol}));

Reimplement fixed resolution option

V3 is missing the option to make sure like tokens are always executed in the same way

Need more entries on the default dictionary. - hacktoberfest - (beginner friendly)

Splain has a default dictionary of useful and common words. So far its fairly empty so it would be great if people could add to it.

The dictionary is basically just a JSON object where the end of each route is an array of words that could be used for that. For example adj.interesting is an array of words that could all mean interesting.

I'm looking for it to be as full as possible so feel free to add more categories (e.g. you could add nouns.fruit:["banana","apple"]) but am happy for current bits to be updated or changed :)

Please try and use the object for some order rather than just add randomly to the root of the object.

see lib/defaultDictionaries for where the defaults are.

(not because of the nature of this issue id be more than happy for several people to contribute)

(Note, if you see any other issues your interested in drop me a message and id be happy to tag them with hacktoberfest :P )

Should be able to add weights

You should be able to add weightings to dictionary entries to make things more common.

for example test:[["entry1",100].["entry2".1]]

This would essentially treat entry1 as though it had 11 entries of it into the dictionary.

named resolutions

It would be useful to have a way to expose how a token got executed at the top level of process info.

e.g. Splain.process('string',.... [name])

would add 'namedResolutions' to ProcessInfo with the results of the execution of any tokens with valuename

How can we auto-generate change-set for releases?

For Splain 2 I just wrote what i knew had been changed but it would be good to maybe auto-generate a change-set on releases containing commits and or pushes.

Any ideas on how to do this or the best way to approach it?

Should be able to print out all permutations of a template

It might be useful to have functionality to print out all possible permutations of a template (within a tolerance) so that the user can sanity check a template.

Should be able to fix template resolution value throughout process

When a template is processed, I to be able to say that once a template is resolved, if that template is met again the first resolution value is used. This will mean that the context does not mess up when using the referencing the result multiple times throughout the text.

Reduce cyclomatic complexity around token.convert

codebeat has highlighted the complexity around SplainTokens convert method is too high.
Some of the longer winded token types should be split of into there own functions.

Should provide a configuration option to stop unrecognised templates compiling to null

It would be good to have the option for the template that couldn't be compiled to be left as a template (that way its more obvious which dictionary item caused the issue)

Add entries to the default dictionary.

Splain has a default dictionary of useful and common words. So far its fairly empty so it would be great if people could add to it.

The dictionary is basically just a JSON object where the end of each route is an array of words that could be used for that. For example adj.interesting is an array of words that could all mean interesting.

I'm looking for it to be as full as possible so feel free to add more categories (e.g. you could add nouns.fruit:["banana","apple"]) but am happy for current bits to be updated or changed :)

Please try and use the object for some order rather than just add randomly to the root of the object.

see lib/defaultDictionaries for where the defaults are.

(not because of the nature of this issue id be more than happy for several people to contribute)

(Note, if you see any other issues your interested in drop me a message and id be happy to tag them with hacktoberfest :P )

Multiple selectors

it could be useful to include a sort of multi selector on the end of routes. for example:

a.b.[c,d,e] would be select an entry from a.d.c or a.b.d or a.b.e.

Execution order should be left to right

At the minute the execution order is sporadic. If there is a template inside a template those will automatically get resolved before the preceding simpler tokens. This doesn't work with contexts as it means contexts may be set by tokens that actually get executed first but are near the end of the whole template/logical sentence.

Automatic weighting based on estimated amount of compilations

Splain should be able to take into account some tokens will have a much larger amount of potential compilations. This is a problem because it will make the overall execution feel very biased.

I will try and update this ticket with an example

Should be able to provide conditionals with a probability of higher than 1/2

At the minute the conditional with the highest likely hood is {{"test"?}} which will produce 1 in 2.

The user may want to have a typically occurring token with a change of 9/10.

A good way to implement this may be changing how conditionals are interpreted. Instead of reading it as a 1 in X chance the number could be taken as the fractional numbers (i.e after the decimal place)

i.e ?9 = 0.9 = 9/10 chance
?1 = 0.1 = 1/10 chance
?5 = 0.5 = 1/2 chance
?00234 = 0.00234 = tiny chance

Process should take a more generic config option

I can see Splain.process could get cluttered. instead of individual parameters i propose that a config option should be passed with these and entries in it.

e.g. { variables:{a:1,b:2}, dictionaryContext:"EN" }

| operator should not be executed if token not found on both sides

if no token is provided either side then the | operator should be ignored. I believe there is some checking for this but in the case of a conditional either side then that conditional may be processed as null and then the | select that null result

see:
console.log(Splain.process("{{{{'1'?5}}|'2'}}"))

Build Splain on push/pull request

It would be good if there was a build process to run npm build whenever there was a push or pull request. This would make sure Splain.js was always built for the branch so you don't mistakenly experiment/test/develop on an out of date library.

@luke-rogers suggest this could be part of CI after a pull request and then somehow slotted in?

I have no idea how to approach this so looking for ideas and suggestions

addEntry doesnt need name parameter

I think the second parameter to addEntry isnt needed. at the minuite its to name the entry and adds it under that property in the JSON. however this can be supplied as a root element in the JSON itself:

i.e addEntry({test:["hello world"]}) is the same as addEntry(["hello world"],"test")

this is normally ignored anyway but with the 3rd parameter to supply a dictionary context I think it just add unnecessary confusion.

provide an option to include the node of the entry as an entry

it would be useful to have a configuration option that would allow you to include the last bit of a path as an entry.

for example in the entry adj.size.big = ["huge","large","massive"] it would automatically add the word "big"

should be able to supply a partial path token

I should be able to supply part of a path as the token. Splain should then find and use any entries at that level.

a:{
    b:{
        c:["example"],
        d:["test"]
    }
}

for example above supplying the token a.b would combine a.b.c and a.b.d.

This will stop the need to an all sort of implementation i.e:

colors:{
    all:["{{blue}}","{{green}}"],
    blue:["blue","cyan"],
    green:["emerald","green","lime"]
}

Should provide a trim character

a special character or token should be used at the beginning or end of a template that will remove the white space either preceding or proceeding it. this will help the use of punctuation in some scenarios.

rename folders

We should restructure/rename the folders to src for the uncompiled code and lib for the compiled and minified library

get entry explicit option always set to false

line 13 of splainToken :

     entry = context.dictionary.getEntry(token, false, context);

is this right? feels like it should be using a config variable.

Provide an option to only use a template once

There should be a configuration option to allow splain to run in some sort of batches.
This would work by having (potentially flagged) options be 'used up' if they were selected.

This would be useful in the case of a generator or having something where the user wants to ensure fresh compilations

Should be able to use special characters in a template via escaping

You should be able to have templates like {{don't you think this should work}}

This could be achieved with escape characters: {{\"I'll use quotes if i want to!\"}}

Investigate UMD bundling approach

I don't think the current method we're using is correct. We should look at examples to see if there's a better way (still using webpack)

Should be able to add context to a variable to influence further template resolutions

should be able to separate out dictionary's or supply your own

Rather than one universal dictionary it would be useful to be able to specify one. This way different sources/characters can operate from there own dictionary.

should be able to change the template tokens

the default token "{{}}" is used in some other areas (e.g. angular) and so it could be useful to provide a config option to change it.

(it would default to {{ and }})

upgrade to TS

should look into using Typescript to make the library easier to work with.

(potentially) Requires:

• update webpack
• update jest
• refactor to TS
• add typings
• refactor some tests
• change to tslint

Update dependencies

We should upgrade dependencies

re-write new .readme

Should be able to force a context

When using Splain.process you should be able to supply a context or set of contexts before it is run.

Should be able to provide local scope for the template

Rather than have to write something like {{a.b.c.x "and" a.b.c.y}} it would be useful to provide a root for the template (for example here you would have a.b.c and your template would be simplified to {{x "and" y}}.

Add multi resolver onto Splain object

The multi resolver should be accessible from Splain (like the verifier).

e.g Splain.multiResolve(template).

The functionality is there (see tests) just need hooking up.

Should be able to provide variables

It would be useful to provide a variable or function (or many) with the splain.process.

this could be a separate token {{0]} {{1}} for example that would be replaced with the outcome of the variable

Nested conditionals dont appear to be working

Whilst writing a guide/tutorial I can see that conditionals within a token that act on the output or another internal token arn't working correctly.

e,g: console.log(Splain.process({{"signing"|"logging"}} {{"in"|"on"}} {{"to" {{loading.hardware|loading.destination}}}}?3));

(note above snippet markdown has rendered the backticks used for stings)

Should provide utility to check the integrity of a Splain dictionary

It would be useful to have an internal tool/function that will parse a dictionary and check any templates within it will compile.

Should be able to have multiple contexts

I think it'd be a good feature if you could provide an array of contexts for each entry. for instance:

Splain.addEntry({colors:[{value:"turquoise", context:["blue","green"]}]});
Splain.addEntry({environments:[{value:"sea", context:["blue","green"]},{value:"grass", context:"green"},{value:"sunset", context:["gold","bright","yellow"]}]});

console.log(Splain.process("wow look at those lovely {{colors}} {{environments}}"));

missing .contribute file

Context matching strategy set via config

There should be a config option that lets uses have control over context matching strategy.

for instance:

• select the token with the most matching contexts.
• dont match on context if they have any other context types
• destructive remove any non-matching context types

More context options

The user should be able to select config for how contexts work and contexts themselves should be be able to take on a richer interface.

Conservative: if a template currently has the contexts [a,b,c] and matches an entry with contexts [b,d,e] then no new contexts should be added as the context 'b' is considered matched and thus already a selected. If there are no contextual entries matching e.g the entry has context [x,y] then both are added as there is no common contexts.

Additive: All contexts of the selected entries will be added.

Descriptive Contexts should be presentable as objects. For example they could follow a pattern:

contexts: [{matches:[green], adds:[earthen, jungle, natural]}, {matches:[blue], adds:[ocean, cold]}]