Skip to content

Commit 6541736

Browse files
dschachdschach
committed
Initial release
First release * Many illegals to ensure auto-detection * Test in this repo does not work yet; import into main highlight repo extra folder to see all tests pass. This is a TODO. * Highlighting a method declaration that returns a collection is not yet perfect.
0 parents  commit 6541736

19 files changed

+4186
-0
lines changed

‎.gitignore

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
lerna-debug.log*
8+
9+
# Diagnostic reports (https://nodejs.org/api/report.html)
10+
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
11+
12+
# Runtime data
13+
pids
14+
*.pid
15+
*.seed
16+
*.pid.lock
17+
18+
# Directory for instrumented libs generated by jscoverage/JSCover
19+
lib-cov
20+
21+
# Coverage directory used by tools like istanbul
22+
coverage
23+
*.lcov
24+
25+
# nyc test coverage
26+
.nyc_output
27+
28+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
29+
.grunt
30+
31+
# Bower dependency directory (https://bower.io/)
32+
bower_components
33+
34+
# node-waf configuration
35+
.lock-wscript
36+
37+
# Compiled binary addons (https://nodejs.org/api/addons.html)
38+
build/Release
39+
40+
# Dependency directories
41+
node_modules/
42+
jspm_packages/
43+
44+
# TypeScript v1 declaration files
45+
typings/
46+
47+
# TypeScript cache
48+
*.tsbuildinfo
49+
50+
# Optional npm cache directory
51+
.npm
52+
53+
# Optional eslint cache
54+
.eslintcache
55+
56+
# Microbundle cache
57+
.rpt2_cache/
58+
.rts2_cache_cjs/
59+
.rts2_cache_es/
60+
.rts2_cache_umd/
61+
62+
# Optional REPL history
63+
.node_repl_history
64+
65+
# Output of 'npm pack'
66+
*.tgz
67+
68+
# Yarn Integrity file
69+
.yarn-integrity
70+
71+
# dotenv environment variables file
72+
.env
73+
.env.test
74+
75+
# parcel-bundler cache (https://parceljs.org/)
76+
.cache
77+
78+
# Next.js build output
79+
.next
80+
81+
# Nuxt.js build / generate output
82+
.nuxt
83+
#dist
84+
85+
# Gatsby files
86+
.cache/
87+
# Comment in the public line in if your project uses Gatsby and *not* Next.js
88+
# https://nextjs.org/blog/next-9-1#public-directory-support
89+
# public
90+
91+
# vuepress build output
92+
.vuepress/dist
93+
94+
# Serverless directories
95+
.serverless/
96+
97+
# FuseBox cache
98+
.fusebox/
99+
100+
# DynamoDB Local files
101+
.dynamodb/
102+
103+
# TernJS port file
104+
.tern-port
105+
106+
# OSX file
107+
.DS_Store

‎.prettierignore

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# List files or directories below to ignore them when running prettier
2+
# More information: https://prettier.io/docs/en/ignore.html
3+
#
4+
5+
node_modules
6+
.localdevserver
7+
.vscode

‎.prettierrc

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"trailingComma": "none",
3+
"useTabs": true,
4+
"printWidth": 100,
5+
"bracketSameLine": true,
6+
"bracketSpacing": true,
7+
"tabWidth": 2,
8+
"singleQuote": true
9+
}

‎3RD_PARTY_QUICK_START.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Language Contribution Guide
2+
3+
So you'd like to create and share your own language definition for Highlight.js. That's awesome.
4+
5+
## Getting started
6+
7+
- [ ] Have a look at some real-life examples first
8+
- https://github.com/highlightjs/highlightjs-cypher
9+
- https://github.com/highlightjs/highlightjs-robots-txt
10+
- [ ] Clone the main [highlight-js](https://github.com/highlightjs/highlightjs) repository from GitHub
11+
- [ ] Read our [Language Contributor Checklist](https://highlightjs.readthedocs.io/en/latest/language-contribution.html)
12+
- [ ] Review the [Language Definition Guide](https://highlightjs.readthedocs.io/en/latest/language-guide.html)
13+
- [ ] Start with our [repository template](https://github.com/highlightjs/highlightjs-language-template) to more easily follow the suggested layout. (this isn't ready yet!)
14+
15+
## Create your repository
16+
17+
Each language is developed in its own repo. This helps keep language definitions and maintenance independent of the core work.
18+
Determine if you will host the repository yourself or you want it to be part of the [highlightjs organization on GitHub](https://github.com/highlightjs).
19+
20+
> To host your new language with the highlightjs organization, [create an issue](https://github.com/highlightjs/highlight.js/issues/new/choose) using the language request template and provide a description of your language and your intent to host it. We will follow up in that issue.
21+
22+
Setup your directory structure to follow exactly the example(s) above. Note: The template repository does this for you, so if you started with the template you can skip this step.
23+
24+
For example, if your grammar is named `apex`, create your repository directory structure as follows (renaming `apex` to match your language name of course. For example, if your language is `pascal`, then replace all occurrences of `apex` with `pascal`):
25+
26+
- Put your language file in `src/languages/apex.js`.
27+
- Add detect tests in `test/detect/apex`.
28+
- Add markup tests in `test/markup/apex`.
29+
- Add a `package.json` file.
30+
- Add a `dist` folder (see [Packaging](#packaging), below.)
31+
- Include a LICENSE.
32+
- Include a README.
33+
34+
## Testing
35+
36+
Switching back to your clone of the `highlight-js` core repository now, `git clone` or symlink your language repo into the `extra` folder. There should now be an `extra/apex` folder for your language.
37+
38+
> 3rd party language directories placed in `extra` should not be committed to the highlight-js repository (by default they are ignored, just don't override that behavior.)
39+
40+
To test (detect and markup tests), just build Highlight.js and test it. Your tests should be automatically run with the full suite:
41+
42+
```bash
43+
node ./tools/build.js -t node
44+
npm run test
45+
```
46+
47+
Running the tests this way runs the complete suite of tests for all languages. You can set the `ONLY_EXTRA` environment variable to focus the tests on just the language(s) you are currently working on in the `extra` folder.
48+
49+
```bash
50+
ONLY_EXTRA=true
51+
npm run test-markup
52+
```
53+
54+
*This currently only works for markup tests*, but those are the most common tests that need to be run while developing a language grammar.
55+
56+
If you can't get the auto-detect tests passing then turn off auto-detection for your language in its definition with `disableAutodetect: true`. [Auto-detection is hard.](https://github.com/highlightjs/highlight.js/issues/1213)
57+
58+
## Packaging
59+
60+
Users will expect your package to include a minified CDN distributable in your `dist` folder. This allows them to add your language to their website using only a single `<script>` tag and no additional JavaScript.
61+
62+
*The Highlight.js CDN build process will build this file for you automatically.* You can simply commit and push your repo, and done.
63+
64+
```bash
65+
node ./tools/build.js -t cdn
66+
67+
...
68+
Building extra/highlightjs-apex/dist/apex.min.js.
69+
...
70+
```
71+
72+
After building, simply commit the `dist/apex.min.js` that was generated for you inside your repository.
73+
74+
```
75+
cd extra/highlightjs-apex
76+
git add dist
77+
git commit -m'(chore) add CDN distributable`
78+
git push
79+
```
80+
81+
## Publishing
82+
83+
We're happy to host 3rd party module repos inside the `highlightjs` organization on GitHub. Just [file an issue](https://github.com/highlightjs/highlight.js/issues/new/choose) and request a repository.
84+
85+
Please also consider publishing your package to NPM. This will make it much easier for many using Node.js or bundlers to use your package.
86+
87+
When your language definition is ready, create a PR that adds it to our [`SUPPORTED_LANGUAGES.md`](https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md) file.
88+
89+
## The Future
90+
91+
More work could be done on:
92+
93+
- Allowing you to ONLY run your own tests, not the whole suite.
94+
- Allowing you to maintain a 3rd party module WITHOUT it being inside of a `highlight-js` checkout (this requires discussion though)
95+
- Simply make some easier tools or scripts to simply the existing process.

‎CONTRIBUTING.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Contributing Code
2+
3+
## Setup
4+
5+
To build highlightjs-apex, you'll need the latest long term support (LTS) release of Node and npm.
6+
We recommend nvm to manage multiple active Node versions.
7+
8+
Start by cloning the source from GitHub:
9+
10+
$ git clone https://github.com/highlightjs/highlightjs-apex.git
11+
12+
Next, install the dependencies using `npm`:
13+
14+
$ npm i
15+
16+
## Test
17+
18+
To execute the tests, open a terminal and type:
19+
20+
$ npm t
21+
22+
## Build the distribution
23+
24+
To generate the `dist` file, we need to clone the [highlight.js](https://github.com/highlightjs/highlight.js) main repository:
25+
26+
$ git clone https://github.com/highlightjs/highlight.js
27+
$ cd highlight.js
28+
29+
Then, install the dependencies:
30+
31+
$ npm i
32+
33+
Create an `extra` directory and clone the [highlightjs-apex](https://github.com/highlightjs/highlightjs-apex) repository in it:
34+
35+
$ mkdir extra
36+
$ cd extra
37+
$ git clone https://github.com/highlightjs/highlightjs-apex
38+
$ cd ..
39+
40+
Now we are ready to generate the `dist` file.
41+
Open a terminal and type:
42+
43+
$ node --stack-size=65500 ./tools/build.js -t cdn
44+
45+
The generated file will be available in both `build/languages/apex.min.js` and `extra/apex/dist/apex.min.js`.

‎LICENSE.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2022 David Schach
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Apex - a language grammar for the [Salesforce Platform](https://developer.salesforce.com)
2+
3+
## Demo
4+
5+
The below screenshot was captured from a [demo webpage](demo/testcode.html) after dropping `highlight.min.js` to a `dist` folder.
6+
(Code taken from [Salesforce Trigger Framework](https://github.com/dschach/salesforce-trigger-framework) and Highlight Java example code)
7+
![Demo](demo/ApexHighlighting.png)
8+
9+
## Usage
10+
11+
Simply include the Highlight.js library in your webpage, then load this module.
12+
13+
### Static website or simple usage
14+
15+
Simply load this module after loading Highlight.js. You'll use the minified version found in the `dist` directory. This module is just a CDN build of the language, so it will register itself as the Javascript is loaded.
16+
17+
```html
18+
<script type="text/javascript" src="/path/to/highlight.min.js"></script>
19+
<script type="text/javascript" src="/path/to/highlightjs-apex/dist/apex.min.js"></script>
20+
<link rel="stylesheet" href="/path/to/highlightjs-apex/demo/highlight.css" />
21+
<script type="text/javascript">
22+
hljs.highlightAll();
23+
</script>
24+
```
25+
26+
For more details of the usage see [Highlight.js main page](https://github.com/highlightjs/highlight.js#highlightjs).
27+
28+
### With Node or another build system
29+
30+
If you're using Node / Webpack / Rollup / Browserify, etc, simply require the language module, then register it with Highlight.js.
31+
32+
```javascript
33+
var hljs = require('highlight.js');
34+
var hljsApexTxt = require('highlightjs-apex');
35+
36+
hljs.registerLanguage("apex", hljsApexTxt);
37+
hljs.highlightAll();
38+
```
39+
40+
## License
41+
42+
Highlight.js is released under the BSD 3-Clause License. See [LICENSE](/LICENSE) file for details.
43+
44+
## Author
45+
46+
[David Schach](https://github.com/dschach)
47+
48+
## Contribution
49+
50+
Feel free to create issues or (even better) pull requests.
51+
## Links
52+
53+
- The official site for the Highlight.js library is <https://highlightjs.org/>.
54+
- The Highlight.js GitHub project: <https://github.com/highlightjs/highlight.js>
55+
- Learn more about Apex: <https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_intro_what_is_apex.htm>

‎demo/ApexHighlighting.png

365 KB
Loading

0 commit comments

Comments
 (0)