Switch to reStructuredText for documentation.
This commit is contained in:
parent
18c3d78834
commit
6c3aa57276
11 changed files with 305 additions and 233 deletions
62
js/readme.md
62
js/readme.md
|
@ -1,62 +0,0 @@
|
|||
# Module descriptions - core
|
||||
|
||||
This document serves as basic documentation for Caret's AMD modules. It's not
|
||||
exhaustive, but it will serve as a starting place for anyone wanting to dive
|
||||
in a little deeper.
|
||||
|
||||
Caret's execution starts in main.js, which mostly serves as bootstrap for the
|
||||
other modules. It also registers command listeners for the UI themes, various
|
||||
window events, and app-level commands like `app:check-for-updates`. After
|
||||
that, we really get down to business.
|
||||
|
||||
In addition to the module folders, which contain their own readme files, there
|
||||
are also folders for the current Ace build (ace) and any external libraries
|
||||
used by Caret, such as the ES6 Promises shim (lib).
|
||||
|
||||
## aceBindings.js
|
||||
|
||||
Takes care of any messiness between Caret and Ace APIs. Registers the
|
||||
`ace:command` listener, as well as a bunch of Sublime emulation commands.
|
||||
Exposes no external methods or data.
|
||||
|
||||
## api.js
|
||||
|
||||
Registers for chrome.runtime.onMessageExternal events, patching them into the
|
||||
command module, and dispatches messages from `api:execute` commands. Exposes
|
||||
no external methods or data.
|
||||
|
||||
## command.js
|
||||
|
||||
Serves as a messaging buffer between modules, and from declarative DOM
|
||||
attributes to modules. Exposes three properties: `fire()` for sending
|
||||
commands, `on()` for subscribing to them, and an array called `list` that can
|
||||
be used to add palette-only items at runtime.
|
||||
|
||||
## editor.js
|
||||
|
||||
Sets up the Ace editor and registers for events in the `editor:*` namespace.
|
||||
Returns the Ace object.
|
||||
|
||||
## fileManager.js
|
||||
|
||||
Handles opening files from launch data, retained handles, and user commands.
|
||||
Exposes no external methods or data.
|
||||
|
||||
## sessions.js
|
||||
|
||||
Manages Caret's tabs, including all UI interaction with the tab bar and the
|
||||
process of adding or removing tabs. Exposes a number of methods and
|
||||
manipulating the tab structure. Most of the actual session code is loaded from the `/sessions` folder, to make the file more manageable.
|
||||
|
||||
## settings.js
|
||||
|
||||
Runs as a RequireJS plugin, so that dependent modules can rely on having
|
||||
settings available on startup, but actually just returns the same singleton
|
||||
as `storage/settingsProvider`.
|
||||
|
||||
## tab.js
|
||||
|
||||
Exposes a Tab constructor to dependents, which is an augmented Ace
|
||||
EditorSession. Tabs do additional setup work to support Caret, as well as
|
||||
adding methods for saving files and dropping retained file handles.
|
||||
|
71
js/readme.rst
Normal file
71
js/readme.rst
Normal file
|
@ -0,0 +1,71 @@
|
|||
Module descriptions - core
|
||||
==========================
|
||||
|
||||
This document serves as basic documentation for Caret's AMD modules.
|
||||
It's not exhaustive, but it will serve as a starting place for anyone
|
||||
wanting to dive in a little deeper.
|
||||
|
||||
Caret's execution starts in main.js, which mostly serves as bootstrap
|
||||
for the other modules. It also registers command listeners for the UI
|
||||
themes, various window events, and app-level commands like
|
||||
``app:check-for-updates``. After that, we really get down to business.
|
||||
|
||||
In addition to the module folders, which contain their own readme files,
|
||||
there are also folders for the current Ace build (ace) and any external
|
||||
libraries used by Caret, such as the ES6 Promises shim (lib).
|
||||
|
||||
aceBindings.js
|
||||
--------------
|
||||
|
||||
Takes care of any messiness between Caret and Ace APIs. Registers the
|
||||
``ace:command`` listener, as well as a bunch of Sublime emulation
|
||||
commands. Exposes no external methods or data.
|
||||
|
||||
api.js
|
||||
------
|
||||
|
||||
Registers for chrome.runtime.onMessageExternal events, patching them
|
||||
into the command module, and dispatches messages from ``api:execute``
|
||||
commands. Exposes no external methods or data.
|
||||
|
||||
command.js
|
||||
----------
|
||||
|
||||
Serves as a messaging buffer between modules, and from declarative DOM
|
||||
attributes to modules. Exposes three properties: ``fire()`` for sending
|
||||
commands, ``on()`` for subscribing to them, and an array called ``list``
|
||||
that can be used to add palette-only items at runtime.
|
||||
|
||||
editor.js
|
||||
---------
|
||||
|
||||
Sets up the Ace editor and registers for events in the ``editor:*``
|
||||
namespace. Returns the Ace object.
|
||||
|
||||
fileManager.js
|
||||
--------------
|
||||
|
||||
Handles opening files from launch data, retained handles, and user
|
||||
commands. Exposes no external methods or data.
|
||||
|
||||
sessions.js
|
||||
-----------
|
||||
|
||||
Manages Caret's tabs, including all UI interaction with the tab bar and
|
||||
the process of adding or removing tabs. Exposes a number of methods and
|
||||
manipulating the tab structure. Most of the actual session code is
|
||||
loaded from the ``/sessions`` folder, to make the file more manageable.
|
||||
|
||||
settings.js
|
||||
-----------
|
||||
|
||||
Runs as a RequireJS plugin, so that dependent modules can rely on having
|
||||
settings available on startup, but actually just returns the same
|
||||
singleton as ``storage/settingsProvider``.
|
||||
|
||||
tab.js
|
||||
------
|
||||
|
||||
Exposes a Tab constructor to dependents, which is an augmented Ace
|
||||
EditorSession. Tabs do additional setup work to support Caret, as well
|
||||
as adding methods for saving files and dropping retained file handles.
|
|
@ -1,21 +1,27 @@
|
|||
# Module description - sessions/*
|
||||
Module description - sessions/\*
|
||||
================================
|
||||
|
||||
The sessions folder contains functionality that was broken out to keep
|
||||
`sessions.js` from getting huge.
|
||||
``sessions.js`` from getting huge.
|
||||
|
||||
## addRemove.js
|
||||
addRemove.js
|
||||
------------
|
||||
|
||||
Provides methods for adding, removing, and re-ordering sessions and their tabs.
|
||||
Provides methods for adding, removing, and re-ordering sessions and
|
||||
their tabs.
|
||||
|
||||
## binding.js
|
||||
binding.js
|
||||
----------
|
||||
|
||||
Event bindings, such as drag/drop and middle click
|
||||
|
||||
## state.js
|
||||
state.js
|
||||
--------
|
||||
|
||||
Actual tab state as a singleton, imported by other modules to do re-ordering or
|
||||
other tab manipulation.
|
||||
Actual tab state as a singleton, imported by other modules to do
|
||||
re-ordering or other tab manipulation.
|
||||
|
||||
## switching.js
|
||||
switching.js
|
||||
------------
|
||||
|
||||
Provides the utility methods for between tabs, directly or in order.
|
||||
Provides the utility methods for between tabs, directly or in order.
|
|
@ -1,45 +0,0 @@
|
|||
# Module descriptions - storage/*
|
||||
|
||||
## file.js
|
||||
|
||||
Wraps the chrome.fileSystem APIs in a friendly File constructor. File objects
|
||||
have the following methods or properties, most of which should be self
|
||||
explanatory. Most methods return promises, but also accept node-style callbacks.
|
||||
|
||||
- `open`
|
||||
- `read`
|
||||
- `write`
|
||||
- `stat`
|
||||
- `retain`
|
||||
- `restore`
|
||||
- `getPath`
|
||||
- `entry` - contains the actual entry object.
|
||||
|
||||
All storage in Caret, regardless of its actual backing structure, goes through
|
||||
objects adhering to the File interface, which makes it much easier to open
|
||||
many types of data through the same tab/editor UI. It also makes persistence
|
||||
much more consistent and less verbose throughout Caret.
|
||||
|
||||
## settingsProvider.js
|
||||
|
||||
The actual singleton returned when modules load configs via the `settings`
|
||||
plugin. Provides the following API:
|
||||
|
||||
- `get` Retrieves the current settings object by name, with all layers `(project, local, and default) merged over top each other.
|
||||
- `getAsString` Retrieves the local settings as a string, mostly used when opening settings for editing.
|
||||
- `getAsFile`
|
||||
- `load` Requests a fresh copy of the local settings from sync storage, usually called after either writing to settings or when the dependent module does not have a settings cache.
|
||||
- `setProject` Sets the top-most JSON object to be merged when calling `Settings.get()`, used for the project-specific settings overrides.
|
||||
- `clearProject` Removes the top-most JSON object, so that only local and default settings are merged.
|
||||
- `pull` Calls load/get for you on the list of arguments, and returns a promise that's fullfilled with a hash of the requested settings.
|
||||
|
||||
## syncfile.js
|
||||
|
||||
A constructor matching the File interface, but backed by chrome.storage.sync.
|
||||
Used to open settings "files."
|
||||
|
||||
## syncFS.js
|
||||
|
||||
An abstraction over top of chrome.storage.sync, capable of storing data larger
|
||||
than the sync storage limit by splitting it into multiple entries behind the
|
||||
scenes. Returns promises for all methods.
|
60
js/storage/readme.rst
Normal file
60
js/storage/readme.rst
Normal file
|
@ -0,0 +1,60 @@
|
|||
Module descriptions - storage/\*
|
||||
================================
|
||||
|
||||
file.js
|
||||
-------
|
||||
|
||||
Wraps the chrome.fileSystem APIs in a friendly File constructor. File
|
||||
objects have the following methods or properties, most of which should
|
||||
be self explanatory. Most methods return promises, but also accept
|
||||
node-style callbacks.
|
||||
|
||||
- ``open``
|
||||
- ``read``
|
||||
- ``write``
|
||||
- ``stat``
|
||||
- ``retain``
|
||||
- ``restore``
|
||||
- ``getPath``
|
||||
- ``entry`` - contains the actual entry object.
|
||||
|
||||
All storage in Caret, regardless of its actual backing structure, goes
|
||||
through objects adhering to the File interface, which makes it much
|
||||
easier to open many types of data through the same tab/editor UI. It
|
||||
also makes persistence much more consistent and less verbose throughout
|
||||
Caret.
|
||||
|
||||
settingsProvider.js
|
||||
-------------------
|
||||
|
||||
The actual singleton returned when modules load configs via the
|
||||
``settings`` plugin. Provides the following API:
|
||||
|
||||
- ``get`` Retrieves the current settings object by name, with all
|
||||
layers \`(project, local, and default) merged over top each other.
|
||||
- ``getAsString`` Retrieves the local settings as a string, mostly used
|
||||
when opening settings for editing.
|
||||
- ``getAsFile``
|
||||
- ``load`` Requests a fresh copy of the local settings from sync
|
||||
storage, usually called after either writing to settings or when the
|
||||
dependent module does not have a settings cache.
|
||||
- ``setProject`` Sets the top-most JSON object to be merged when
|
||||
calling ``Settings.get()``, used for the project-specific settings
|
||||
overrides.
|
||||
- ``clearProject`` Removes the top-most JSON object, so that only local
|
||||
and default settings are merged.
|
||||
- ``pull`` Calls load/get for you on the list of arguments, and returns
|
||||
a promise that's fullfilled with a hash of the requested settings.
|
||||
|
||||
syncfile.js
|
||||
-----------
|
||||
|
||||
A constructor matching the File interface, but backed by
|
||||
chrome.storage.sync. Used to open settings "files."
|
||||
|
||||
syncFS.js
|
||||
---------
|
||||
|
||||
An abstraction over top of chrome.storage.sync, capable of storing data
|
||||
larger than the sync storage limit by splitting it into multiple entries
|
||||
behind the scenes. Returns promises for all methods.
|
|
@ -1,47 +0,0 @@
|
|||
# Module description - ui/*
|
||||
|
||||
## cli.js
|
||||
|
||||
Creates the UI and bindings for a "command line" that can run Caret commands
|
||||
directly. Useful when testing a new command, since you don't need to change
|
||||
keys.json or menu.json in order to run it.
|
||||
|
||||
## contextMenus.js
|
||||
|
||||
Simplifies the process of adding Chrome context menus to page links, including
|
||||
adding a basic REST-style router for getting parameters out of the link URL.
|
||||
Exposes a `register` method for setting up the actual menu and its callback,
|
||||
and a `makeURL` method to help with making route URLs that correctly start
|
||||
with the app's extension ID.
|
||||
|
||||
## dialog.js
|
||||
|
||||
Exposes a function that will pop up a dialog box, since Chrome apps are not
|
||||
allowed to use `alert()`, `confirm()`, or `prompt()`. Reasonably customizable.
|
||||
|
||||
## keys.js
|
||||
|
||||
Reads the local keyboard settings and registers on the document body to
|
||||
convert them into commands. Also handles unbinding any Ace commands that would
|
||||
otherwise collide. Exposes no external methods or data.
|
||||
|
||||
## menus.js
|
||||
|
||||
Generates the menu bar from the local menu settings file. Exposes no external
|
||||
methods or data at this time.
|
||||
|
||||
## palette.js
|
||||
|
||||
Sets up the command palette and returns it as a singleton for any other
|
||||
modules that might want to trigger it or alter its data, although it is
|
||||
recommended that other modules simply send `palette:*` commands instead.
|
||||
|
||||
## projectManager.js
|
||||
|
||||
Tracks any current project settings, files, and navigable directories. Exposes
|
||||
the manager object to dependent modules, primarily so that the palette can get
|
||||
the list of files for Go To File.
|
||||
|
||||
## statusbar.js
|
||||
|
||||
Sets the status text, and returns an interface with `setMessage()`, `clearMessage()`, and `toast()` methods. It's recommended to use the `status:*` commands instead of requiring this module directly.
|
60
js/ui/readme.rst
Normal file
60
js/ui/readme.rst
Normal file
|
@ -0,0 +1,60 @@
|
|||
Module description - ui/\*
|
||||
==========================
|
||||
|
||||
cli.js
|
||||
------
|
||||
|
||||
Creates the UI and bindings for a "command line" that can run Caret
|
||||
commands directly. Useful when testing a new command, since you don't
|
||||
need to change keys.json or menu.json in order to run it.
|
||||
|
||||
contextMenus.js
|
||||
---------------
|
||||
|
||||
Simplifies the process of adding Chrome context menus to page links,
|
||||
including adding a basic REST-style router for getting parameters out of
|
||||
the link URL. Exposes a ``register`` method for setting up the actual
|
||||
menu and its callback, and a ``makeURL`` method to help with making
|
||||
route URLs that correctly start with the app's extension ID.
|
||||
|
||||
dialog.js
|
||||
---------
|
||||
|
||||
Exposes a function that will pop up a dialog box, since Chrome apps are
|
||||
not allowed to use ``alert()``, ``confirm()``, or ``prompt()``.
|
||||
Reasonably customizable.
|
||||
|
||||
keys.js
|
||||
-------
|
||||
|
||||
Reads the local keyboard settings and registers on the document body to
|
||||
convert them into commands. Also handles unbinding any Ace commands that
|
||||
would otherwise collide. Exposes no external methods or data.
|
||||
|
||||
menus.js
|
||||
--------
|
||||
|
||||
Generates the menu bar from the local menu settings file. Exposes no
|
||||
external methods or data at this time.
|
||||
|
||||
palette.js
|
||||
----------
|
||||
|
||||
Sets up the command palette and returns it as a singleton for any other
|
||||
modules that might want to trigger it or alter its data, although it is
|
||||
recommended that other modules simply send ``palette:*`` commands
|
||||
instead.
|
||||
|
||||
projectManager.js
|
||||
-----------------
|
||||
|
||||
Tracks any current project settings, files, and navigable directories.
|
||||
Exposes the manager object to dependent modules, primarily so that the
|
||||
palette can get the list of files for Go To File.
|
||||
|
||||
statusbar.js
|
||||
------------
|
||||
|
||||
Sets the status text, and returns an interface with ``setMessage()``,
|
||||
``clearMessage()``, and ``toast()`` methods. It's recommended to use the
|
||||
``status:*`` commands instead of requiring this module directly.
|
|
@ -1,46 +0,0 @@
|
|||
# Module descriptions - util
|
||||
|
||||
## aceLoad.js
|
||||
|
||||
Shims Ace's loadScript() async loader so that AMD modules can simply declare Ace dependencies the same way they declare AMD dependencies.
|
||||
|
||||
## dom2.js
|
||||
|
||||
Instead of using an MVC framework like Backbone or a view binding library like
|
||||
Angular, Caret modifies the DOM prototypes to have a more jQuery-like UI with
|
||||
this module. Since Chrome apps cannot share a page with external scripts, and
|
||||
since we know that the Chrome DOM prototypes are stable, this is a safe and
|
||||
easy way to get sensible DOM manipulation. Exposes no methods or data, but
|
||||
does modify the Document, DocumentFragment, Element, and Window prototypes.
|
||||
|
||||
## inflate.js
|
||||
|
||||
Chrome OS disallows using `eval()` or `new Function()`, which means many
|
||||
template libraries simply won't work without pre-compiling the templates.
|
||||
Instead of going that route, recognizing that template speed is almost never a
|
||||
bottleneck for Caret, inflate.js provides Mustache-compatible templating that
|
||||
can load from the filesystem or the DOM (loaded automatically by ID). Exposes
|
||||
the following methods:
|
||||
|
||||
- `load`- Pulls a template from the given filesystem path. Returns a promise that resolves when the template is ready.
|
||||
- `loadHTML` - Directly insert HTML into the template cache for use.
|
||||
- `get` - Fills a template with data and returns a DOM element.
|
||||
- `getHTML` - Fills a template with data and returns the string representation
|
||||
- `getAsync` - Used to simultaneously load and fill a template. Returns a promise that resolves with the filled template as a DOM element.
|
||||
|
||||
## manos.js
|
||||
|
||||
A lightweight library for handling async code, this serves as the "hands of
|
||||
fate" for your callbacks. Provides `serial()` and `map()` for async array
|
||||
manipulation, and `pton()` and `deferred` for working with native ES6
|
||||
Promises.
|
||||
|
||||
## template.js
|
||||
|
||||
A plugin that loads a template from disk, then returns the `inflate` templating
|
||||
object. Useful for modules that need a template as part of their dependencies.
|
||||
|
||||
## text.js
|
||||
|
||||
A RequireJS plugin that loads files from Caret's app directory using XHR. Used
|
||||
to get the default settings JSON through a standard interface.
|
60
js/util/readme.rst
Normal file
60
js/util/readme.rst
Normal file
|
@ -0,0 +1,60 @@
|
|||
Module descriptions - util
|
||||
==========================
|
||||
|
||||
aceLoad.js
|
||||
----------
|
||||
|
||||
Shims Ace's loadScript() async loader so that AMD modules can simply
|
||||
declare Ace dependencies the same way they declare AMD dependencies.
|
||||
|
||||
dom2.js
|
||||
-------
|
||||
|
||||
Instead of using an MVC framework like Backbone or a view binding
|
||||
library like Angular, Caret modifies the DOM prototypes to have a more
|
||||
jQuery-like UI with this module. Since Chrome apps cannot share a page
|
||||
with external scripts, and since we know that the Chrome DOM prototypes
|
||||
are stable, this is a safe and easy way to get sensible DOM
|
||||
manipulation. Exposes no methods or data, but does modify the Document,
|
||||
DocumentFragment, Element, and Window prototypes.
|
||||
|
||||
inflate.js
|
||||
----------
|
||||
|
||||
Chrome OS disallows using ``eval()`` or ``new Function()``, which means
|
||||
many template libraries simply won't work without pre-compiling the
|
||||
templates. Instead of going that route, recognizing that template speed
|
||||
is almost never a bottleneck for Caret, inflate.js provides
|
||||
Mustache-compatible templating that can load from the filesystem or the
|
||||
DOM (loaded automatically by ID). Exposes the following methods:
|
||||
|
||||
- ``load``- Pulls a template from the given filesystem path. Returns a
|
||||
promise that resolves when the template is ready.
|
||||
- ``loadHTML`` - Directly insert HTML into the template cache for use.
|
||||
- ``get`` - Fills a template with data and returns a DOM element.
|
||||
- ``getHTML`` - Fills a template with data and returns the string
|
||||
representation
|
||||
- ``getAsync`` - Used to simultaneously load and fill a template.
|
||||
Returns a promise that resolves with the filled template as a DOM
|
||||
element.
|
||||
|
||||
manos.js
|
||||
--------
|
||||
|
||||
A lightweight library for handling async code, this serves as the "hands
|
||||
of fate" for your callbacks. Provides ``serial()`` and ``map()`` for
|
||||
async array manipulation, and ``pton()`` and ``deferred`` for working
|
||||
with native ES6 Promises.
|
||||
|
||||
template.js
|
||||
-----------
|
||||
|
||||
A plugin that loads a template from disk, then returns the ``inflate``
|
||||
templating object. Useful for modules that need a template as part of
|
||||
their dependencies.
|
||||
|
||||
text.js
|
||||
-------
|
||||
|
||||
A RequireJS plugin that loads files from Caret's app directory using
|
||||
XHR. Used to get the default settings JSON through a standard interface.
|
23
readme.md
23
readme.md
|
@ -1,23 +0,0 @@
|
|||
Caret
|
||||
=====
|
||||
|
||||
Caret is a serious, graphical programmer's editor running as a Chrome Packaged App. Inspired by Sublime and built on top of the Ace editing component, it offers powerful features like:
|
||||
|
||||
* multiple cursors
|
||||
* tabbed editing and retained files
|
||||
* syntax highlighting and themes
|
||||
* command palette/smart go to
|
||||
* hackable, synchronized configuration files
|
||||
* project files and folder view
|
||||
|
||||
More information, links to Caret in the Chrome Web Store, and an external package file are available at http://thomaswilburn.net/caret. Documentation can be found in the [wiki](https://github.com/thomaswilburn/Caret/wiki).
|
||||
|
||||
You can also easily load Caret from source, either to hack around on or to have the absolute bleeding edge. You'll need to have Node and NPM installed first, then follow these steps:
|
||||
|
||||
0. Clone this repo to your local machine
|
||||
0. Run `npm install` to get the development dependencies (Grunt, LESS, and some other packages)
|
||||
0. Start `grunt`, which will generate the CSS files from the LESS source
|
||||
0. Visit `chrome://extensions` and enable Developer Mode.
|
||||
0. Still on the extensions page, click the button marked "Load unpacked extension..." and select the directory containing Caret's manifest.json.
|
||||
|
||||
If you use Caret and would like to show your appreciation, please consider donating to the [EFF's Fund to End Software Patents](https://my.fsf.org/donate/directed-donations/esp). You can also give a gift through [Gittip](https://www.gittip.com/thomaswilburn/).
|
38
readme.rst
Normal file
38
readme.rst
Normal file
|
@ -0,0 +1,38 @@
|
|||
Caret
|
||||
=====
|
||||
|
||||
Caret is a serious, graphical programmer's editor running as a Chrome
|
||||
Packaged App. Inspired by Sublime and built on top of the Ace editing
|
||||
component, it offers powerful features like:
|
||||
|
||||
- multiple cursors
|
||||
- tabbed editing and retained files
|
||||
- syntax highlighting and themes
|
||||
- command palette/smart go to
|
||||
- hackable, synchronized configuration files
|
||||
- project files and folder view
|
||||
|
||||
More information, links to Caret in the Chrome Web Store, and an
|
||||
external package file are available at http://thomaswilburn.net/caret.
|
||||
Documentation can be found in the
|
||||
`wiki <https://github.com/thomaswilburn/Caret/wiki>`__.
|
||||
|
||||
You can also easily load Caret from source, either to hack around on or
|
||||
to have the absolute bleeding edge. You'll need to have Node and NPM
|
||||
installed first, then follow these steps:
|
||||
|
||||
0. Clone this repo to your local machine
|
||||
1. Run ``npm install`` to get the development dependencies (Grunt, LESS,
|
||||
and some other packages)
|
||||
2. Start ``grunt``, which will generate the CSS files from the LESS
|
||||
source
|
||||
3. Visit ``chrome://extensions`` and enable Developer Mode.
|
||||
4. Still on the extensions page, click the button marked "Load unpacked
|
||||
extension..." and select the directory containing Caret's
|
||||
manifest.json.
|
||||
|
||||
If you use Caret and would like to show your appreciation, please
|
||||
consider donating to the `EFF's Fund to End Software
|
||||
Patents <https://my.fsf.org/donate/directed-donations/esp>`__. You can
|
||||
also give a gift through
|
||||
`Gittip <https://www.gittip.com/thomaswilburn/>`__.
|
Loading…
Reference in a new issue