@geemike/twitter-search-query-parser

    1.0.1 • Public • Published

    twitter-search-query-parser

    semantic-release Build Status

    Parser, simplifier and stringifier of Twitter search queries.

    Install

    npm install --save twitter-search-query-parser
    

    Use

    parse turns a search query into a data structure:

    import {parse} from 'twitter-search-query-parser';
    
    parse('@jack from:twitter') ===
      [ 'And',
        [ [ 'Including', [ 'Text', '@jack' ] ],
          [ 'Including', [ 'Pair', 'from', 'twitter' ] ] ] ]

    stringify turns a data structure back into a query:

    import {stringify} from 'twitter-search-query-parser';
    
    stringify(
      [ 'And',
        [ [ 'Including', [ 'Text', '@jack' ] ],
          [ 'Including', [ 'Pair', 'from', 'twitter' ] ] ] ]
    ) === '@jack from:twitter'

    simplify squashes the data structure by turning complex types into text. This makes it easier to build an interface for the query, and it stringifies just the same.

    import {parse, simplify} from 'twitter-search-query-parser';
    
    const parsed = parse('@jack OR @twitter -(@support OR @twitterdev)');
    
    parsed ===
      [ 'And',
        [ [ 'Including',
            [ 'Or',
              [ [ 'Including', [ 'Text', '@jack' ] ],
                [ 'Including', [ 'Text', '@twitter' ] ] ] ] ],
          [ 'Excluding',
            [ 'Group',
              [ 'And',
                [ [ 'Including',
                    [ 'Or',
                      [ [ 'Including', [ 'Text', '@support' ] ],
                        [ 'Including', [ 'Text', '@twitterdev' ] ] ] ] ] ] ] ] ] ] ]
    
    const simplified = simplify(parsed, {
      disallow: ['Group', 'Or']
    });
    
    simplified ===
      [ 'And',
        [ [ 'Including', [ 'Text', '@jack OR @twitter' ] ],
          [ 'Excluding', [ 'Text', '(@support OR @twitterdev)' ] ] ] ]

    Terms

    The parsed data stucture follows the format: [Type, ...values]. The nature of the values depends on the Type.

    Text

    Represents a text value, including hashtags, mentions and cashtags. For example:

    #x
    

    Contains a single string value.

    ['Text', 'x']
    

    Exactly

    Represents an exact text match, in quotes.

    "b c"
    

    Contains one string value.

    ['Exactly', 'b c']
    

    And

    Represents a conjunction of other terms, and is the root of the query and grouped sub-queries. For example:

    x #y
    

    Contains an Array value of other terms.

    ['And', [ ... ]]
    

    Or

    Represents a disjunction of other terms. For example:

    x OR #y
    

    Contains an Array value of other terms.

    ['Or', [ ... ]]
    

    Including

    Represents the inclusion of the contained term. Every term is either included or excluded.

    Contains a single value, another term.

    ['Including', ['Text', 'x']]
    

    Excluding

    Represents the exclusion of the contained term. Every term is either included or excluded.

    Contains a single value, another term.

    ['Excluding', ['Text', 'x']]
    

    Group

    Represents a group of terms. For example:

    (a b) OR (c d)
    

    Contains a single value, another term.

    ['Group', [ ... ]]
    

    Pair

    Represents a search facet operator. For example:

    filter:vine exclude:retweets
    

    Contains two string values: they key and the value.

    ['Pair', 'filter', 'vine']
    

    List

    Represents a list facet operator.

    list:NASA/astronauts-in-space-now
    

    Contains two values: user name and list slug.

    ['List', 'NASA', 'astronauts-in-space-now']
    

    Known bugs

    • This library has only been tested in English and likely has insufficient query parsing cababilities in other alphabets

    Development

    $ npm install
    $ npm run gen
    $ npm run try "some -search from:twitter @jack #tagged OR \"exactly this\""
    

    Commit messages should follow the Angular commit message guidelines.

    Release

    This repository uses semantic-release. Changes will automatically be released to npm.

    Keywords

    none

    Install

    npm i @geemike/twitter-search-query-parser

    DownloadsWeekly Downloads

    112

    Version

    1.0.1

    License

    ISC

    Unpacked Size

    85 kB

    Total Files

    10

    Last publish

    Collaborators

    • geemike