Skip to content

/ grawlix

Permalink
master
Switch branches/tags

grawlix/docs/STYLES.md

Go to file
 
 
Cannot retrieve contributors at this time
292 lines (228 sloc) 8.19 KB
Raw Blame

grawlix: Styles

Contents

Choosing a Grawlix Style

The simplest way to specify a style is by passing the name of one of the default styles. In addition to passing in a raw String, developers of a more nervous disposition can access the Style enumeration via the grawlix.Style property:

grawlix.setDefaults({
  style: grawlix.Style.REDACTED
});

Enumeration: grawlix.Style

Properties:

  • ASCII: the 'ascii' style
  • ASTERIX: the 'asterix' style
  • DINGBATS: the 'dingbats' style
  • NEXTWAVE: the 'nextwave' style
  • REDACTED: the 'redacted' style
  • UNICODE: the 'unicode' style
  • UNDERSCORE: the 'underscore' style

Style Objects

For those who want to completely customize their grawlixes, style objects can be used to either create new styles or configure existing ones.

// style object - basic format
grawlix.setDefaults({
  style: {
    name: 'style-name',
    randomChars: 'string-of-characters',
    // or:
    randomChars: {
      add: 'characters-to-add',
      remove: 'characters-to-remove',
      replace: {
        // map of characters to replace
      }
    },
    // or:
    char: 'single-character',
    fixed: {
      // map of fixed replacemets
    },
    allowOverride: true
  }
});

Style objects can have the following properties:

name

Type: String

The name of the style. Required.

randomChars

Type: String, Function, or Object

A string or function that the style should use to construct random grawlixes. When a string is provided, the style will split and recombine its individual characters at random:

grawlix.setDefaults({
  style: {
    name: 'custom-style',
    randomChars: '?!#$%*'
  }
});
grawlix('i invoke fsck'); // will output 'i invoke ?*$#'

If a function is provided, the style will invoke it when a random grawlix is called for, passing in the length of the desired output as an argument. The function is expected to return a string:

grawlix.setDefaults({
  style: {
    name: 'custom-style',
    randomChars: function(len) {
      var str = '';
      for (var i=0; i<len; i++) {
        if (i % 2 > 0) {
          str += '!';
        } else {
          str += '*'
        }
      }
      return str;
    }
  }
});
grawlix('you bastard'); // outputs 'you *!*!*!*'

An object can only be provided when configuring an existing style. It can have three properties: add, remove, and replace, all of which modify the style's character string.

randomChars.add

Type: String

This option adds the given characters to the string the style uses to randomly generate grawlixes. Let's say, for instance, that one wants the ~ and ? characters to be included in the grawlixes randomly generated by the 'ascii' style:

grawlix.setDefaults({
  style: {
    name: 'ascii',
    randomChars: {
      add: '~?' // tilde and question mark will now be included in generated grawlixes
    }
  }
});
randomChars.remove

Type: String

The characters specified in this option will be removed from the string the style uses to randomly generate grawlixes.

grawlix.setDefaults({
  style: {
    name: 'unicode',
    randomChars: {
      remove: '♡♢♤♧' // playing card symbols will not appear in grawlixes
    }
  }
});
randomChars.replace

Type: Object

This option allows one to pass in a map of characters to replace within the string the style uses to randomly generate grawlixes. The object's keys represent the characters to be replaced, while the object's values represent the characters that should be inserted instead.

// replaces red playing card symbols with black playing card symbols within the 
// 'dingbats' style.
grawlix.setDefaults({
  style: {
    name: 'dingbats',
    randomChars: {
      replace: {
        '♡': '♥',
        '♢': '♦',
        '♤': '♠',
        '♧': '♣'
      }
    }
  }
});

char

Type: String

Alternate shorthand property that specifies the character to use when creating a single-character style.

fixed

Type: Object

Adds or replaces strings within the style's fixed replacement dictionary. See Using Fixed Replacement Strings below for more details.

allowOverride

Type: Boolean
Default: true

Sets whether or not a style should allow itself to be overridden by filter styles when it's the main style. When set to false, the style will ignore any filter-specific settings.

Creating New Grawlix Styles

You can use style objects to create entirely new styles:

grawlix.setDefaults({
  style: {
    name: 'x-out',
    char: 'X'
  }
});
grawlix('you bastards'); // outputs 'you XXXXXXX'

New styles can also be passed in via the styles option:

grawlix.setDefaults({
  styles: [
    {
      name: 'x-out',
      char: 'X'
    },
    {
      name: 'playing-cards',
      randomChars: '♡♢♤♧'
    }
  ],
  style: 'playing-cards'
});

Please note that objects used to create new styles must have at least one of the following properties defined (in addition to name): randomChars, char, and/or fixed. Otherwise, the package will throw an error.

Configuring Existing Grawlix Styles

To exert exact control over the main style's configuration, pass in a style object instead:

grawlix.setDefaults({
  style: {
    name: 'ascii',
    randomChars: {
      add: '...',
      remove: '...',
      replace: {}
    },
    fixed: {
      // add or replace fixed replacement strings
    }
  }
});

Using Fixed Replacement Strings

When the randomize flag is set to false, certain grawlix styles -- namely 'ascii', 'dingbats', and 'unicode' -- will, instead of generating random grawlixes, attempt to replace profanities with fixed replacement strings drawn from a dictionary contained with the GrawlixStyle object. While primarily used for testing, this mode may also be of interest to those who wish to replace obscenities with alternate words, or to build a sort of 'grawlix language' that will allow end users in the know to easily infer the original word used while (hopefully) going over younger viewers' heads.

You can add or replace strings within an existing style's dictionary by passing in a object map via the style.fixed property:

grawlix.setDefaults({
  style: {
    name: 'ascii',
    fixed: {
      'word': '%!&#',
      'word2': '#&!%'
    }
  }
});

When creating a new style, you can optionally pass in a dictionary of replacement strings via the fixed parameter:

grawlix.setDefaults({
  style: {
    name: 'my-custom-style',
    randomChars: 'string-of-characters',
    fixed: {
      'word': '%!&#',
      'word2': '#&!%'
    }
  }
});

Things to keep in mind when coming up with your own fixed replacement strings:

  • Fixed replacement strings will be automatically wrapped in a filter's template. In certain cases, this may have unexpected outcomes.
  • When using the $ character, note that it will need to be repeated twice in order to render properly, on account of how JavaScript's String#replace function works. So '%!$$#' will be rendered as '%!$#'.

For examples of how this works, see the default styles in styles.js.

Last updated April 18, 2017.