YASHE

YASHE (Yet Another ShEx Editor) is a Shape Expressions (ShEx) editor which started as a fork of YASQE (which is based on SPARQL). This tool performs lexical and syntactic analysis of the content of the editor, thus offering the user a realtime syntactic error detector. It has features like: syntax highlighting, visual aid elements (tooltips) and autocomplete mechanisms. In addition, it offers a simple way of integrating into other projects

Features
Install
- NPM
- JsDelivr
- Github
Getting Started
Getting Started
- React.js
Configuration
Events
- Event Handlers
- Fire your own events
Shortcuts
API
Statics
Developing YASHE
- Docker
Used By
Forked By
Thanks!!!

Features 📋

Completely client-side
ShEx syntax highlighting and error checking
Light and Dark modes
Extremely customizable: All functions and handlers from the CodeMirror library are accessible
Persistent values (optional): your query is stored for easier reuse between browser sessions
Prefix definition autocompletion (using prefix.cc)
Prefix and ShEx keywords autocompletion
Wikidata property and entity autocompletion (using the MediaWiki API)
Information tooltip when hovering over wikidata properties and entities (using the MediaWiki API)
Handy keyboard shortcuts
Integrated buttons that alows to:
- Upload ShEx files
- Download the editor content as a ShEx file
- Copy the editor content to the clipboard
- Delete all the editor content
- Change between light and dark mode
- FullScreen Mode

Install 💾

NPM

YASHE is registered as a node package as well, so you'll be able to use the node package manager to keep your version of YASHE up to date. (YASHE NPM Package)

$ npm i yashe

JsDelivr

The YASHE files are hosted via JsDelivr. This CDN is the easiest way to include YASHE in your website.

<link href='https://cdn.jsdelivr.net/npm/yashe/dist/yashe.min.css' rel='stylesheet' type='text/css'/>
<script src='https://cdn.jsdelivr.net/npm/yashe/dist/yashe.bundled.min.js'></script>

Github

Visit the GitHub repository to download the YASHE .css and .js files (find them in the dist directory).

Getting Started

You can initialize YASHE via its constructor, or via the command fromTextArea. Both return in instance of YASHE, from now on referred to as yashe (lowercase). Both function take as argument a config object (that can be null). Main YASHE constructor. Pass a DOM element as argument to append the editor to, and (optionally) pass along config settings. YASHE(parent: DOM-Element, settings: Object) → YASHE instance: yashe . Codepen Example

var yashe = YASHE(document.getElementById('domId'), {
  //Options
});

Initialize YASHE from an existing text area (see CodeMirror for more info) YASHE.fromTextArea(textArea: DOM element, config: Object) → YASHE instance: yashe Codepen Example

var yashe = YASHE.fromTextArea(document.getElementById('texAreaId'), {
  //Options
});

React.js

This is a basic example about how to use YASHE in React.js using hooks:

import React, {useState,useEffect,useRef} from 'react';
import YASHE from 'yashe';

function Editor() {

  const [yashe,setYashe] = useState(null);
  const divRef = useRef(null);

    useEffect(() => {
    
        if (!yashe) {
            const options = {
                persistent:false,
                lineNumbers: true,
            }
            
            const y = YASHE(divRef.current,options);
        
            y.refresh();
            setYashe(y);           
          }
      }, [yashe]
    );
    return  (<div ref={divRef}/>);
}

export default Editor;

Configuration

This configuration object is accessible/changeable via YASHE.defaults and yashe.options, and you can pass these along when initializing YASHE as well. Other than the configuration we describe here, check the CodeMirror documentation for even more options you can set, such as disabling line numbers, or changing keyboard shortcut keys.

var yashe = YASHE(document.getElementById('domId'), {
  value:'Starting value of the editor',
  mode:'shex',
  theme:'wiki', //dark
  lineNumbers: true,
  lineWrapping: true,
  fontSize: 14, 
  cursorHeight:15,
  firstLineNumber:1,
  readOnly:false,
  showCursorWhenSelecting:fasle,
  tabMode: 'indent',
  collapsePrefixesOnLoad: false,
  matchBrackets: true,
  fixedGutter: true,
  syntaxErrorCheck: true,
  showTooltip: true,
  showUploadButton: true,
  showDownloadButton: true,
  showCopyButton: true,
  showDeleteButton: true,
  showThemeButton: true,
  showFullScreenButton: true,
  persistent: null,
  extraKeys: {
    "Ctrl-Space": YASHE.autoComplete,
    "Cmd-Space": YASHE.autoComplete,
    "Ctrl-D": YASHE.deleteLine,
    "Cmd-K": YASHE.deleteLine,
    "Ctrl-/": YASHE.commentLines,
    "Cmd-/": YASHE.commentLines,
    "Ctrl-Down": YASHE.copyLineDown,
    "Ctrl-Up": YASHE.copyLineUp,
    "Cmd-Down": YASHE.copyLineDown,
    "Cmd-Up": YASHE.copyLineUp,
    "Shift-Ctrl-F": YASHE.doAutoFormat,
    "Shift-Cmd-F": YASHE.doAutoFormat,
    "Ctrl-S": YASHE.storeContent,
    "Cmd-S": YASHE.storeConten,
    "Ctrl-Enter": YASHE.executeQuery,
    "Cmd-Enter": YASHE.executeQuery,
    }
});

Events

Here are some events provided by YASHE (check the Codemirror Documentation for more info ):

Event	Objects	Action
change	yashe: CodeMirror, changeObj: object	Fires every time the content of the editor is changed
cursorActivity	yashe: CodeMirror	Will be fired when the cursor or selection moves, or any change is made to the editor content.
keyHandled	yashe: CodeMirror,name: string,event: Event	Fired after a key is handled through a key map
focus	yashe: CodeMirror, event: Event	Fires whenever the editor is focused
blur	yashe: CodeMirror, event: Event	Fires whenever the editor is unfocused
scroll	yashe: CodeMirror	Fires whenever the editor is scrolled
refresh	yashe: CodeMirror	Fires when the editor is refreshed or resized
optionChange	yashe: CodeMirror, option: string	Dispatched every time an option is changed with setOption
upload	yashe: CodeMirror	Fires after uploading a file by the upload button
download	yashe: CodeMirror	Fires after downloading a file by the download button
copy	yashe: CodeMirror	Fires after copying the editor content using the copy button
themeChange	yashe: CodeMirror	Fires after changing the editor theme using the change theme button
delete	yashe: CodeMirror	Fires after deleting the editor content by the delete buttton
expandScreen	yashe: CodeMirror	Fires after expanding screen
collapseScreen	yashe: CodeMirror	Fires after collapsing screen

Event Handlers

cm.on(type: string, func: (...args))

Register an event handler for the given event type (a string) on the editor instance. There is also a CodeMirror.on(object, type, func) version that allows registering of events on any object.

yashe.on('blur', function(yashe) {
 console.log('The editor has been unfocused!');
});

cm.off(type: string, func: (...args))

Remove an event handler on the editor instance. An equivalent CodeMirror.off(object, type, func) also exists.

yashe.off('blur');

Fire your own events

CodeMirror.signal(target, name, args...)

Codemirror.signal(yashe,'myOwnEvent'args...);

Shortcuts provided by YASHE:

Shortcut	Action
Ctrl/Cmd-Space	Trigger Autocompletion
Ctrl/Cmd-D	Delete current/selected line(s)
Ctrl/Cmd-/	Comment or uncomment current/selected line(s)
Ctrl/Cmd-Down	Copy line down
Ctrl/Cmd-Up	Copy line up
Ctrl/Cmd-Shift-F	Auto-format/indent selected lines
Ctrl/Cmd-S	Save current content in local storage
Ctrl/Cmd-Z	Undo
Ctrl/Cmd-Y	Redo
F11	Set query editor full-screen (or leave full-screen)
Esc	Leave full-screen

API

API methods accessible via the yashe instance ( check the Codemirror Manual for more info:

// Get query value from editor
yashe.getValue() → query: String

//Set query value in editor
yashe.setValue(query: String)

// Get the content of line n.
yashe.getLine(n: integer) → string

// Get the number of lines in the editor.
yashe.lineCount() → integer

// Get the number of first line in the editor. 
yashe.firstLine() → integer

// Get the number of last line in the editor. 
yashe.lastLine() → integer

// Get the currently selected code. 
// Optionally pass a line separator to put between the lines in the output. 
// When multiple selections are present, they are concatenated with instances 
// of lineSep in between.
yashe.getSelection(?lineSep: string) → string


// Replace the selection(s) with the given string. By default, the new selection 
// ends up after the inserted text. The optional select argument can be used to 
// change this—passing "around" will cause the new text to be selected, passing 
// "start" will collapse the selection to the start of the inserted text.
yashe.replaceSelection(replacement: string, ?select: string)

// Retrieve one end of the primary selection. start is an optional string indicating 
// which end of the selection to return. It may be "from", "to", "head" (the side of 
// the selection that moves when you press shift+arrow), or "anchor" (the fixed side 
// of the selection). Omitting the argument is the same as passing "head". A {line, ch} 
// object will be returned.
yashe.getCursor(?start: string) → {line, ch}

// Return true if any text is selected
yashe.somethingSelected() → boolean

// Set the cursor position. You can either pass a single {line, ch} object, or the line 
// and the character as two separate parameters. Will replace all selections with a single, 
// empty selection at the given position
yashe.setCursor(pos: {line, ch}|number, ?ch: number, ?options: object)

// Tells you whether the editor currently has focus.
yashe.hasFocus() → boolean

// Returns the start and end of the 'word' (the stretch of letters, whitespace, or 
// punctuation) at the given position.
yashe.findWordAt(pos: {line, ch}) → {anchor: {line, ch}, head: {line, ch}}


// Retrieves the current value of the given option for this editor instance.
yashe.getOption(option: string) → any

// Change the configuration of the editor. option should the name of an option, 
// and value should be a valid value for that option.
yashe.setOption(option: string, value: any)

// Retrieve the currently active document from an editor.
yashe.getDoc() → Doc

// Retrieve the editor associated with a document. May return null.
yashe.getEditor() → CodeMirror

// Undo one edit (if any undo events are stored).
yashe.undo()

// Redo one undone edit.
yashe.redo()

// Programmatically set the size of the editor (overriding the applicable CSS rules). 
// width and height can be either numbers (interpreted as pixels) or CSS units (e.g "100%"). 
// You can pass null for either of them to indicate that that dimension should not be changed.
yashe.setSize(width: number|string, height: number|string)

// Scroll the editor to a given (pixel) position. Both arguments may be left as null 
// or undefined to have no effect.
yashe.scrollTo(x: number, y: number)

// If your code does something to change the size of the editor element (window resizes 
// are already listened for), or unhides it, you should probably follow up by calling 
// this method to ensure CodeMirror is still looking as intended.
yashe.refresh()

//Retrieves information about the token the current mode found before the given 
// position (a {line, ch} object). The returned object has the following properties:
// start -> The character (on the given line) at which the token starts
// end -> The character at which the token ends.
// string->The token's string.
// type -> The token type the mode assigned to the token, such as "keyword" or 
//         "comment" (may also be null).
// state -> The mode's state at the end of this token.
yashe.getTokenAt(pos: {line, ch}, ?precise: boolean) → object

// Fetch defined prefixes
yashe.getDefinedPrefixes() → object:

// Add prefixes to the query. The prefixes are defined as 
// {"rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#"}
yashe.addPrefixes(prefixes: object)

// Remove prefixes from query. The prefixes are defined as 
// {"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#"}
yashe.removePrefixes(prefixes: object)

// Set size. Use null value to leave width or height unchanged. 
// To resize the editor to fit its content, see //http://codemirror.net/demo/resize.html
yashe.setSize(width: Number|string, height: Number|string)

// Enable an autocompleter with this name. Only makes sense if you've programatically 
// disabled this completer before, as a plugin is automatically enabled when registering it 
// (see this function)
yashe.enableCompleter(completerName: String)

// Disable an autocompleter with this name.
yashe.disableCompleter(completerName: String)

// Store bulk completions in memory as trie, and in localstorage as well (if enabled). 
// The argument should be a key from the //autocompletion settings
yashe.storeBulkCompletions(type: String)

// Collapsing prefixes if there are any. Use false to expand them.
yashe.collapsePrefixes(collapse: boolean)

Statics

Static functions YASHE

// Register an autocompleter in YASHE. This automatically enables the completer as well
YASHE.registerAutocompleter(name: String, autocompleter: function)

// When typing a shape, this shape is sometimes syntactically invalid, 
// causing the current tokens to be incorrect.
// This causes problem for autocompletion. http://bla might result in two tokens: http:// and bla. 
// We'll want to combine these
YASHE.getCompleteToken(doc: yashe, token: Object, cursor: Object) //→ token: Object

Developing YASHE 🚧

Feel free to fork and develop this tool. You can submit your contributions as GitHub pull requests. To develop YASHE locally:

npm install
npm run dev for local development

Docker

You can also deploy YASHE with Docker. The only important requirement is that you have Docker installed and running on your computer. Then, you just need to follow these steps.

Download the latest version of the repository, either as a ZIP file or by cloning the master branch.

git clone https://github.com/weso/yashe

Then move to the docker folder from inside YASHE:

cd yashe/docker

Build yashe image: docker-compose build.
Finally, execute docker-compose up. This will deploy the container and expose the port 4000.

Used By: 🔗

ShExAuthor: ShEx Graphic Assistant
RDFShape: RDF service for conversion and validation using ShEX and SHACL
WikiShape: Shape Expressions playground customized for Wikidata
ShExML Playground to convert ShExML to RDF and RML offering diferent syntaxes

Forked By: 🔗

YASME Yet Another Shape Map Editor
ShExML Editor ShExML is a language based on ShEx to map and merge heterogeneous data sources. It is designed with usability in mind trying to make the script creation easier to the user

Thanks!

A big thanks goes out to:

Laurens Rietveld for his great work on the YASQE library
Maxime Lefrançois for his tips at the beginning of the project and for his work on the YATE library in which I could be inspired

A big thanks transitively goes out to:

The people behind the MediaWiki API which I use for autocompleting Wikidata entities and properties.
Marijn Haverbeke for his great work on the CodeMirror library syntax highlighting library
Richard Cyganiak for his simple but effective Prefix.cc service, which I use for autocompleting prefixes.

weso/YASHE