Skip to content

Latest commit

 

History

History
195 lines (144 loc) · 5.63 KB

README.md

File metadata and controls

195 lines (144 loc) · 5.63 KB
Raw

vsm-dictionary-local


Summary

vsm-dictionary-local is a full, local (=in-memory) implementation of the 'VsmDictionary' parent-class/interface (from the package vsm-dictionary).


Background

  • VSM-sentences are built from terms that are linked to identifiers.
  • The 'vsm-dictionary' package defines a standardized interface, for VSM-related tools to communicate with services that provide terms+IDs (e.g. a webserver API).
  • That packages also includes the 'VsmDictionary' parent class that provides some shared functionality for concrete subclasses (like this package).

A local implementation of a VsmDictionary

This is VsmDictionaryLocal:

  • It extends the VsmDictionary parent class, and provides a concrete implementation that fully implements the vsm-dictionary specification.
    • i.e. it has the complete Create, Read, Update, Delete, search, sort, filter, etc. functionality for terms, subdictionary-info objects, etc.
  • It does not use an online server for data storage or lookup. Instead, it stores all data in-memory, as long as the application is running.

When to use VsmDictionaryLocal

Because of the above:

  • During the development of new tools that depend on a VsmDictionary, this module can be used as a fully functional placeholder that does not need an online server.
  • Or, it could provide mock terms+ids while running standalone demos of VSM-sentence building tools.
  • The many automated tests in VsmDictionaryLocal can give inspiration for testing future, webserver-connecting implementations.

Specification

Apart from following the parent class specification, VsmDictionaryLocal follows the additional the spec described in DictionaryLocal.spec.md.
• (Note: we simply use the name 'DictionaryLocal' for VsmDictionaryLocal, in the spec & source code).


Installation

Node.js

npm install vsm-dictionary-local

const VsmDictionaryLocal = require('vsm-dictionary-local');

Browsers

<script src="https://unpkg.com/vsm-dictionary-local@^2.0.0/dist/vsm-dictionary-local.min.js"></script>

after which it is accessible as the global variable VsmDictionaryLocal.


Example use in Node.js

Example that (only):
 • adds one subdictionary (by adding a dictionary-info object),
 • adds entries to it (=concepts/IDs + terms),
 • string-searches for matching terms:

const VsmDictionaryLocal = require('vsm-dictionary-local');

var dict = new VsmDictionaryLocal();
var dictInfos = [ { id: 'DictID_12', name: 'Example subdictionary' } ];
var entries = [
  { id: 'URI:001', dictID: 'DictID_12', terms: [{str: 'aaa'}, {str: 'synonym'}] },
  { id: 'URI:002', dictID: 'DictID_12', terms: [{str: 'aab'}] },
  { id: 'URI:003', dictID: 'DictID_12', terms: [{str: 'abc'}], descr: 'description' }
];

dict.addDictInfos(dictInfos, (err) => {  // Add 1 subdictionary-info object.
  dict.addEntries(entries, (err) => {    // Add 3 entries.
    dict.getMatchesForString('ab', {}, (err, res) => {  // Query for string 'ab'.
      console.dir(res.items, { depth: 3 });
    });
  });
});

This gives the output:

[ { id: 'URI:003',         // Concept-ID.
    dictID: 'DictID_12',   // Dictionary-ID.
    descr: 'description',  // Description of the meaning of concept `URI:003`.
    terms: [ { str: 'abc' } ],  // Term-objects: one term as an unstyled string.
    str: 'abc',            // The term-string that this match pertains to.
    type: 'S' },           // Match type. Prefix(S)-matches come before infix(T).
  { id: 'URI:002',
    dictID: 'DictID_12',
    terms: [ { str: 'aab' } ],
    str: 'aab',
    type: 'T' } ]

Or we can load all data in one synchronous call, by giving it to VsmDictionaryLocal's constructor: 
const VsmDictionaryLocal = require('vsm-dictionary-local');

// Create.
var dict = new VsmDictionaryLocal({
  dictData: [
    { id: 'DictID_12',
      name: 'Example subdictionary',
      entries: [
        { id: 'URI:001', terms: [{str: 'aaa'}, {str: 'synonym'}] },
        { id: 'URI:002', terms: [{str: 'aab'}] },
        { id: 'URI:003', terms: [{str: 'abc'}], descr: 'description' }
      ]
    },
  ],
});

// Query.
dict.getMatchesForString('ab', {}, (err, res) => {
  console.dir(res.items, {depth: 3});
});

which gives the same output.


Tests

Run npm test, which runs tests with Mocha.
Run npm run testw, which automatically reruns tests when any file changes.


Demo in Node.js

More examples are included in demoInNode.js (based on demoData.js).
Run it with: node demo/demoInNode.js.


Interactive demo in the browser

Run npm run demo to start an interactive demo of (only) the string-search functionality, based on example data.
This opens a browser page with an input-field to search on demoData.js.

The demo works by making a Webpack dev-server bundle all source code (VsmDictionaryLocal and its dependencies) and serve it to the browser.
This is useful during development, to see immediate effects of changes to the source code (excl. the demo code).

(For normal use in browsers, just include the browser-build via a <script>-tag, see above).


License

This project is licensed under the AGPL license - see LICENSE.md.