<commit_before>higml
=====

Overview
--------

Higml is a terse format for converting an input hash to an output hash.

Example Higml and input:

    # Higml
    action:show
      :pageName Search Results
      :keywords= keywords

      filter
        :filter_terms= filter_terms
    
    # Input hash
    {
      :action => "show",
      :filter => "any value"
    }
    
This output is produced:

    {
      :pageName => "Search Results",
      :keywords => ... #depends on value of "keywords" method in given context
      :filter_terms => ... #depends on value of "filter_terms" method in given context
    }

To get a better understand of _what_ Higml does, go through spec/higml_spec.rb and the corresponding .higml files in spec/fixtures.

Why would you want to use it? The original use case was generating a json object for analytics. The json object had different fields and values depending on what section of the site and individual page were being viewed. When viewing a profile, the json might be

    {
      pageName: "Profile: 4320",
      section: "Profiles"
    }
    
whereas search might look like

    {
      pageName: "Search: 'robert'",
      section:  "Search"
    }
    
The actual json was much more complicated, containing about 20 keys. Writing the mapping between input and output in higml allowed my coworkers and I to quickly understand what the json would be for a given page, or why the json was the way it was. Example .higml files can be found in /examples.

Syntax
------

Example:

    @import application.higml
    action:show, action:new
      :pageName Search Results
      :keywords= keywords
      
      q:rutabagas
        :rutabagas true
      
      filter
        :filter_terms= filter_terms

<dl>
  <dt>@import appication.higml</dt>
  <dd>acts as if the contents of application.higml were located where @import is</dd>
  <dt>action:show, action:new</dt>
  <dd>If the input hash has a value of "show" _or_ "new" for the key :action, then use the mapping that follows</dd>
  <dt>:pageName Search Results</dt>
  <dd>Output hash has a value of "Search Results" for the :pageName key; constant string</dd>
  <dt>:keywords= keywords</dt>
  <dd>Value of :keywords in output hash is whatever "keywords" evaluates to in the Higml mapper_context; let's you have dynamic values</dd>
  <dt>q:rutabagas</dt>
  <dd>If input hash satisfies action:show _or_ action:new, _and_ it has a value of "rutabagas" for :q, then apply the mapping that follows</dd>
  <dt>filter</dt>
  <dd>If input hash has a key of :filter at all (regardless of :q but dependent on :action), then apply mapping that follows</dd>
</dl>

Contributing to higml
---------------------
 <commit_msg>more doc<commit_after>higml
=====

Overview
--------

Higml is a terse format for converting an input hash to an output hash.

Example Higml and input:

    # Higml
    action:show
      :pageName Search Results
      :keywords= keywords

      filter
        :filter_terms= filter_terms
    
    # Input hash
    {
      :action => "show",
      :filter => "any value"
    }
    
This output is produced:

    {
      :pageName => "Search Results",
      :keywords => ... #depends on value of "keywords" method in given context
      :filter_terms => ... #depends on value of "filter_terms" method in given context
    }

To get a better understand of _what_ Higml does, go through spec/higml_spec.rb and the corresponding .higml files in spec/fixtures.

Why would you want to use it? The original use case was generating a json object for analytics. The json object had different fields and values depending on what section of the site and individual page were being viewed. When viewing a profile, the json might be

    {
      pageName: "Profile: 4320",
      section: "Profiles"
    }
    
whereas search might look like

    {
      pageName: "Search: 'robert'",
      section:  "Search"
    }
    
The actual json was much more complicated, containing about 20 keys. Writing the mapping between input and output in higml allowed my coworkers and I to quickly understand what the json would be for a given page, or why the json was the way it was. Example .higml files can be found in /examples.

Syntax
------

Example:

    @import application.higml
    action:show, action:new
      :pageName Search Results
      :keywords= keywords
      
      q:rutabagas
        :rutabagas true
      
      filter
        :filter_terms= filter_terms

<dl>
  <dt>@import appication.higml</dt>
  <dd>acts as if the contents of application.higml were located where @import is</dd>
  <dt>action:show, action:new</dt>
  <dd>If the input hash has a value of "show" _or_ "new" for the key :action, then use the mapping that follows</dd>
  <dt>:pageName Search Results</dt>
  <dd>Output hash has a value of "Search Results" for the :pageName key; constant string</dd>
  <dt>:keywords= keywords</dt>
  <dd>Value of :keywords in output hash is whatever "keywords" evaluates to in the Higml mapper_context; let's you have dynamic values</dd>
  <dt>q:rutabagas</dt>
  <dd>If input hash satisfies action:show _or_ action:new, _and_ it has a value of "rutabagas" for :q, then apply the mapping that follows</dd>
  <dt>filter</dt>
  <dd>If input hash has a key of :filter at all (regardless of :q but dependent on :action), then apply mapping that follows</dd>
</dl>

Config
------
Use Higml.config.x to set these

<dl>
  <dt>config_directory</dt>
  <dd>Where higml-config.yml is stored #this may be overkill :(</dd>
  <dt>higml_directory</dt>
  <dd>Where all the .higml files are stored</dd>
  <dt>global_pairs</dt>
  <dd>should be hash; used as base hash that result of mapping is merged on to</dd>
</dl>

Contributing to higml
---------------------
 
{'fraction_non_alphanumeric': 0.09548701864436313, 'fraction_numerical': 0.0020909566126502874, 'mean_word_length': 2.9888811674774147, 'pattern_counts': {'":': 0, '<': 69, '<?xml version=': 0, '>': 79, 'https://': 0, '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': '1625006', 'n_tokens_mistral': 1754, 'n_tokens_neox': 1664, 'n_words': 729}