<commit_before># Abel - the declarative DOM manipulator

A micro-library that lets you easily show and hide elements based on the values of form controls and 
user interactions elsewhere on the page.

**Abel is great when you want to make things happen in the DOM but don't want
to load a view library (like React or Angular) or templating framework (like 
Handlebars or Knockout).**

### A Simple Example

Let's say you've got a signup form and the user shouldn't be able to submit  until they agree to 
your terms and conditions. 

Using the `data-abel` attribute, it's easy:

```html
<label>
    <input type="checkbox" id="terms_agreement_checkbox">
    I agree to the terms and conditions
</label>

<button id="submit_button"
    data-abel="
        i start as hidden. 
        when #terms_agreement_checkbox is checked, i will show."
    type="submit">
    Submit
</button>
```

The first statement will hide the `<input id="submit_button">` button as soon as 
the script is run. The second statement adds a listener to `<input id="terms_agreement_checkbox">`.
Then whenever the user checks it, the submit button will show.

**Note: the submit button does not hide when the user unchecks the checkbox.** 
This is because Abel does exactly what you decree and does not execute any other implied actions. To 
make the button hide if the user unchecks the checkbox, just add another statement to the decree:

```html
<button id="submit_button"
    type="submit"
    data-abel="
        i start as hidden. 
        when #terms_agreement_checkbox is checked, i will show.
        when #terms_agreement_checkbox is not checked, i will hide."
    type="submit">
    Submit
</button>
```

## How To Use

### Installation

#### Easy-Mode: In-Browser Automatic Usage

Add the following code to your page (just before `</body>`):

```html
<script src="path/to/abel.js"></script>
<script> Abel.go(); </script>
```

This will load Abel and do everything automatically. 

Note that if you have a very slow website, elements that Abel will hide (when it's loaded) might be 
visible for a short time until the page actually gets to the `Abel.go()` block. If this happens, you
basically just need to [make your web pages load faster](https://developers.google.com/speed/).

### Usage

Using ordinary strings with specific keywords in the `data-abel` attribute of an element, Abel will 
invisibly do what you ask and your page will react to the interactions you specify.

The API exists entirely within the HTML markup, and Abel will automatically parse it and follow your
instructions. The Abel parser reads the sentences as an instruction called a *decree* and uses 
JavaScript to execute each *statement*. 

For a decree to be valid, the following rules apply:

1. All statements are lowercase (however, you can use `I` as well as `i`)
2. All statements must end with a period / full stop (`.`)
3. If a statement starts with `when`, there must be a comma (`,`) and a space 
   before the `i will show` or `i will hide`.
   <commit_msg>update read to explain npm usage<commit_after># Abel - the declarative DOM manipulator

A micro-library that lets you easily show and hide elements based on the values of form controls and 
user interactions elsewhere on the page.

**Abel is great when you want to make things happen in the DOM but don't want
to load a view library (like React or Angular) or templating framework (like 
Handlebars or Knockout).**

### A Simple Example

Let's say you've got a signup form and the user shouldn't be able to submit  until they agree to 
your terms and conditions. 

Using the `data-abel` attribute, it's easy:

```html
<label>
    <input type="checkbox" id="terms_agreement_checkbox">
    I agree to the terms and conditions
</label>

<button id="submit_button"
    data-abel="
        i start as hidden. 
        when #terms_agreement_checkbox is checked, i will show."
    type="submit">
    Submit
</button>
```

The first statement will hide the `<input id="submit_button">` button as soon as 
the script is run. The second statement adds a listener to `<input id="terms_agreement_checkbox">`.
Then whenever the user checks it, the submit button will show.

**Note: the submit button does not hide when the user unchecks the checkbox.** 
This is because Abel does exactly what you decree and does not execute any other implied actions. To 
make the button hide if the user unchecks the checkbox, just add another statement to the decree:

```html
<button id="submit_button"
    type="submit"
    data-abel="
        i start as hidden. 
        when #terms_agreement_checkbox is checked, i will show.
        when #terms_agreement_checkbox is not checked, i will hide."
    type="submit">
    Submit
</button>
```

## How To Use

### Installation

#### Easy-Mode: In-Browser Automatic Usage

Add the following code to your page (just before `</body>`):

```html
<script src="path/to/abel.js"></script>
<script> Abel.go(); </script>
```

This will load Abel and do everything automatically. 

Note that if you have a very slow website, elements that Abel will hide (when it's loaded) might be 
visible for a short time until the page actually gets to the `Abel.go()` block. If this happens, you
basically just need to [make your web pages load faster](https://developers.google.com/speed/).

#### Advanced-Mode: As An npm Module

If you need more fine-grained control over the items that Abel controls, you can pass in a reference
to a DOM node manually:

```js
// Make Abel available for use
var Abel = require('abel');

// Call Abel on a single element (make sure it has a `[data-abel]` attribute with some statements)
Abel( document.getElementById('some-element') );
```

Of course, you can still call `Abel.go()` at any time to automagically initialise all Abel statements.

### Usage

Using ordinary strings with specific keywords in the `data-abel` attribute of an element, Abel will 
invisibly do what you ask and your page will react to the interactions you specify.

The API exists entirely within the HTML markup, and Abel will automatically parse it and follow your
instructions. The Abel parser reads the sentences as an instruction called a *decree* and uses 
JavaScript to execute each *statement*. 

For a decree to be valid, the following rules apply:

1. All statements are lowercase (however, you can use `I` as well as `i`)
2. All statements must end with a period / full stop (`.`)
3. If a statement starts with `when`, there must be a comma (`,`) and a space 
   before the `i will show` or `i will hide`.
   
{'fraction_non_alphanumeric': 0.0811470408785845, 'fraction_numerical': 0.0009151921903599756, 'mean_word_length': 3.8823529411764706, 'pattern_counts': {'":': 0, '<': 31, '<?xml version=': 0, '>': 31, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2159163', 'n_tokens_mistral': 1849, 'n_tokens_neox': 1728, 'n_words': 956}