eibhearPublic/enode
1
0
Fork 0
Code Issues 1 Pull requests Releases Wiki Activity

Converting from Org to Markdown. WhodaThunk!

Browse source
This commit is contained in:
Éibhear Ó hAnluain 2016-10-05 21:29:25 +01:00
parent b99b56dd68
commit 9403a67ac7
1 changed files with 356 additions and 324 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

202
README.md
View file

@ -1,5 +1,23 @@
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#orgheadline8">1. ENODE: ENODE is Not an Oracle Development Environment</a>
<ul>
<li><a href="#orgheadline1">1.1. Interface &#x2013; look and feel.</a></li>
<li><a href="#orgheadline2">1.2. Connect and disconnect.</a></li>
<li><a href="#orgheadline3">1.3. Database object listing and examination.</a></li>
<li><a href="#orgheadline4">1.4. Area for typing of ad hoc SQL statements.</a></li>
<li><a href="#orgheadline5">1.5. Presentation of SQL (query) output.</a></li>
<li><a href="#orgheadline6">1.6. Internals</a></li>
<li><a href="#orgheadline7">1.7. A typical session might be:</a></li>
</ul>
</li>
</ul>
</div>
</div>
* ENODE: ENODE is Not an Oracle Development Environment # ENODE: ENODE is Not an Oracle Development Environment<a id="orgheadline8"></a>
A package and 'mode' for providing an interface for examining and A package and 'mode' for providing an interface for examining and
developing for relational databases. developing for relational databases.
@ -8,6 +26,7 @@
an emacs based interface to examine and develop for a relational an emacs based interface to examine and develop for a relational
database. It's hoped that the following databases will ultimately database. It's hoped that the following databases will ultimately
supported: supported:
- mysql - mysql
- postgres - postgres
- oracle - oracle
@ -19,86 +38,89 @@
layer for interacting with databases from other vendors. layer for interacting with databases from other vendors.
Initially, the following functionality will be provided: Initially, the following functionality will be provided:
- Interface -- look and feel.
- Interface &#x2013; look and feel.
- Connect and disconnect, plus management of saved connection - Connect and disconnect, plus management of saved connection
information. information.
- Database object listing and examination. - Database object listing and examination.
- Area for typing of ad hoc SQL statements. - Area for typing of ad hoc SQL statements.
- Presentation of SQL query output. - Presentation of SQL query output.
+ There'll be no facility to change data as presented from a query. - There'll be no facility to change data as presented from a query.
However, update, delete and insert commands will be facilitated However, update, delete and insert commands will be facilitated
through the SQL area. through the SQL area.
** Interface -- look and feel. ## Interface &#x2013; look and feel.<a id="orgheadline1"></a>
The emacs frame will be divided into three windows: The emacs frame will be divided into three windows:
- The 'object list' or 'navigator' window. - The 'object list' or 'navigator' window.
+ Here will be listed in tree format the various objects that a - Here will be listed in tree format the various objects that a
schema has. Hierarchy will be something like: Schema, objects schema has. Hierarchy will be something like: Schema, objects
(tables, views, packages, etc.), columns/indexes (for tables (tables, views, packages, etc.), columns/indexes (for tables
and views) or procedures/functions (for packages), parameters, and views) or procedures/functions (for packages), parameters,
etc. etc.
+ The user will enter and leave this window by key strokes or - The user will enter and leave this window by key strokes or
mouse clicks. mouse clicks.
+ An object is selected by clicking with the middle button or - An object is selected by clicking with the middle button or
hitting return when point is somewhere on its name. Once hitting return when point is somewhere on its name. Once
selected, information will be presented in the information selected, information will be presented in the information
frame (see below). frame (see below).
+ As a tree structure will be used, opening and closing of nodes - As a tree structure will be used, opening and closing of nodes
will result from selection of the node as described. Selecting will result from selection of the node as described. Selecting
an 'open' node will 'close' it and vice versa. an 'open' node will 'close' it and vice versa.
+ A node can be closed or opened using the left and right arrow - A node can be closed or opened using the left and right arrow
keys. This will not result in selecting the node, therefore keys. This will not result in selecting the node, therefore
preserving the information presented. preserving the information presented.
+ This window can present any of a number of buffers. However, - This window can present any of a number of buffers. However,
each of these buffers must be of a perticular type each of these buffers must be of a perticular type
(e.g. navigator), and will have a local key map specific to its (e.g. navigator), and will have a local key map specific to its
use. Separation of the buffers will facilitate management -- use. Separation of the buffers will facilitate management &#x2013;
one buffer for tables, another for views, etc. one buffer for tables, another for views, etc.
+ The top node for each buffer will be the name of the schema - The top node for each buffer will be the name of the schema
owner. owner.
+ The user can toggle between showing only one schema owner in - The user can toggle between showing only one schema owner in
the list or all of them the list or all of them
- The information window. - The information window.
+ This will present information on the item from the navigation - This will present information on the item from the navigation
window that has most recently been selected. window that has most recently been selected.
+ The user can navigate to this window by way of key stroke or - The user can navigate to this window by way of key stroke or
mouse click. mouse click.
+ The window will provide a subset of all the information on the - The window will provide a subset of all the information on the
object, and a menu to facilitate showing other information. object, and a menu to facilitate showing other information.
+ This window can present any of a number of buffers. There will - This window can present any of a number of buffers. There will
be a separate buffer type for each type of information being be a separate buffer type for each type of information being
displayed (i.e. table columns are presented differently from a displayed (i.e. table columns are presented differently from a
table's indexes, which is also different from the list of table's indexes, which is also different from the list of
triggers on the table, etc.) triggers on the table, etc.)
- The SQL interaction window. - The SQL interaction window.
+ This window will present one of two buffers -- the SQL input - This window will present one of two buffers &#x2013; the SQL input
buffer and the SQL result buffer. buffer and the SQL result buffer.
+ They can both be presented, but at the expense of the other - They can both be presented, but at the expense of the other
windows. windows.
+ In the SQL input buffer, entering commands will be as simple as - In the SQL input buffer, entering commands will be as simple as
entering SQL commands in any sql-mode buffer. entering SQL commands in any sql-mode buffer.
+ Indentation will eventually be based on my preferred - Indentation will eventually be based on my preferred
indentation scheme, as I am the dictator, and not necessarily indentation scheme, as I am the dictator, and not necessarily
benevolent. benevolent.
+ Execution of the command will involve typing a key stroke - Execution of the command will involve typing a key stroke
rather than the RET key as we will want to format the command rather than the RET key as we will want to format the command
nicely. nicely.
+ The output buffer will present data in one of two formats: - The output buffer will present data in one of two formats:
* Select commands will present the selected data in grid - Select commands will present the selected data in grid
format. format.
* Other commands will generate output in simply sequential - Other commands will generate output in simply sequential
output format. output format.
- Possible arrangements can include: - Possible arrangements can include:
+ Three windows in two rows. The navigator and information - Three windows in two rows. The navigator and information
windows in the upper row, the latter being the wider. The SQL windows in the upper row, the latter being the wider. The SQL
interaction window being in the lower. The upper row would be interaction window being in the lower. The upper row would be
the higher. the higher.
+ Three windows in two columns. The navigator in the first - Three windows in two columns. The navigator in the first
column, and the information and SQL interaction windows in the column, and the information and SQL interaction windows in the
second. The latter column will be the wider and the second. The latter column will be the wider and the
information window will be higher than the SQL interaction information window will be higher than the SQL interaction
window. window.
+ Two windows in either columnar or tiered format. The user - Two windows in either columnar or tiered format. The user
decides. The windows will be related by function: The decides. The windows will be related by function: The
navigator and information windows together with the latter navigator and information windows together with the latter
getting more space; the SQL input and output windows together, getting more space; the SQL input and output windows together,
@ -106,26 +128,27 @@
displayed in one of the first two configurations if a function displayed in one of the first two configurations if a function
is called from the information window that warrants it. is called from the information window that warrants it.
- Help information. - Help information.
+ Help can be brought up by typing the '?' key. This will present - Help can be brought up by typing the '?' key. This will present
the list of key strokes that perform tasks in the window which the list of key strokes that perform tasks in the window which
has focus. has focus.
+ The help display will be presented in the SQL interaction - The help display will be presented in the SQL interaction
window, which will be presented if it isn't already. window, which will be presented if it isn't already.
+ If the focus is already in a buffer in the SQL interaction - If the focus is already in a buffer in the SQL interaction
window, the help screen will be presented in the largest window, the help screen will be presented in the largest
visible other window. visible other window.
+ Typing the '?' key in the help buffer will replace its contents - Typing the '?' key in the help buffer will replace its contents
with all the keystrokes possible based on the type of buffer with all the keystrokes possible based on the type of buffer
supported and listing key strokes that work all over ENODE. supported and listing key strokes that work all over ENODE.
+ The user can return to the buffer of most recent focus using a - The user can return to the buffer of most recent focus using a
single key stroke. single key stroke.
+ The user can dismiss the help screen and replace the windows to - The user can dismiss the help screen and replace the windows to
their previous configuration by typing the 'q' key while in the their previous configuration by typing the 'q' key while in the
help buffer. help buffer.
** Connect and disconnect. ## Connect and disconnect.<a id="orgheadline2"></a>
- Upon startup, ENODE will ask for connection information in almost - Upon startup, ENODE will ask for connection information in almost
precisely the manner in which sql-.+ asks for it -- using the precisely the manner in which sql-.+ asks for it &#x2013; using the
minibuffer to get the username, password and database minibuffer to get the username, password and database
information. information.
- ENODE will save each connection information in a history file, - ENODE will save each connection information in a history file,
@ -147,20 +170,21 @@
by an alias given to it explicitly by the user or by a connection by an alias given to it explicitly by the user or by a connection
string in the format of something like <user>/<database>@<host> string in the format of something like <user>/<database>@<host>
- Switching between connections will be at the drop of key stroke. - Switching between connections will be at the drop of key stroke.
+ It will be wise to figure out from the start how new - It will be wise to figure out from the start how new
connections effect the buffers being displayed at the time. connections effect the buffers being displayed at the time.
+ See above regarding switching between connections using the - See above regarding switching between connections using the
navigator window. navigator window.
- Closing connections can be done by one of two means: - Closing connections can be done by one of two means:
+ Close the current connection. Done with a key stroke and a - Close the current connection. Done with a key stroke and a
response to an 'Are you sure?' question, the next connection in response to an 'Are you sure?' question, the next connection in
the list of open connections will be activated. If we are the list of open connections will be activated. If we are
closing the final connection ENODE will report this but not closing the final connection ENODE will report this but not
close the application. close the application.
+ Place the point in the connection in the navigator and execute - Place the point in the connection in the navigator and execute
a key stroke. a key stroke.
** Database object listing and examination. ## Database object listing and examination.<a id="orgheadline3"></a>
- The most useful window here will be the navigator. It will list - The most useful window here will be the navigator. It will list
the objects of interest in a tree structure. There will be the objects of interest in a tree structure. There will be
separate lists for tables, views, indexes and stored separate lists for tables, views, indexes and stored
@ -174,28 +198,31 @@
appropriate). appropriate).
- The types of information displayed and the information itself - The types of information displayed and the information itself
will depend on the selected item, examples of which are: will depend on the selected item, examples of which are:
+ Tables
* Data - Tables
* Columns - Data
* Constraints - Columns
* Indexes - Constraints
* Triggers - Indexes
+ Views - Triggers
* Data - Views
* Columns - Data
* Source - Columns
+ Constraints - Source
* Tables/Columns - Constraints
+ Packages/procedures/functions - Tables/Columns
* Dependancies - Packages/procedures/functions
* Source - Dependancies
+ Triggers - Source
* Tables - Triggers
* Source - Tables
- Source
In the case of views and tables, if we want to see data, it is to In the case of views and tables, if we want to see data, it is to
be displayed in the SQL interaction window. be displayed in the SQL interaction window.
** Area for typing of ad hoc SQL statements. ## Area for typing of ad hoc SQL statements.<a id="orgheadline4"></a>
- This will display the SQL input buffer. - This will display the SQL input buffer.
- SQL commands can be typed as free text into the buffer. - SQL commands can be typed as free text into the buffer.
- Using key strokes, certain actions can then be run on the command - Using key strokes, certain actions can then be run on the command
@ -212,24 +239,26 @@
- Inserting the contents of the file into the buffer will not mean - Inserting the contents of the file into the buffer will not mean
visiting the file. That functionality will come later. visiting the file. That functionality will come later.
** Presentation of SQL (query) output. ## Presentation of SQL (query) output.<a id="orgheadline5"></a>
- For commands other than select statements, the output presented - For commands other than select statements, the output presented
will be as if the commands had been run on the command line. will be as if the commands had been run on the command line.
- Output from queries will be presented in a grid manner, the - Output from queries will be presented in a grid manner, the
configuration of which will be decided after some initial configuration of which will be decided after some initial
testing. testing.
** Internals ## Internals<a id="orgheadline6"></a>
- ENODE will maintain many lists which will be used - ENODE will maintain many lists which will be used
extensively. These will all be association lists. All the extensively. These will all be association lists. All the
elements of these lists will be string values, not elements of these lists will be string values, not
symbols. Depending on the case sensitivity of the database symbols. Depending on the case sensitivity of the database
system, these will be case sensitive or not. The following are system, these will be case sensitive or not. The following are
some of these lists: some of these lists:
+ Databases. This list will be populated with the first database - Databases. This list will be populated with the first database
we connect to. The variable describing the current database we connect to. The variable describing the current database
will contain a string value from this list. will contain a string value from this list.
+ Schema owners. There will be a separate list of schema owners - Schema owners. There will be a separate list of schema owners
per database. As we connect to databases afresh, the first two per database. As we connect to databases afresh, the first two
elements of this list will be the user we connect as and the elements of this list will be the user we connect as and the
system/root schema. The variable describing the current schema system/root schema. The variable describing the current schema
@ -240,30 +269,31 @@
refresh key stroke while a schema owner has been selected in refresh key stroke while a schema owner has been selected in
the navigation window. Refreshing the list also refreshes its the navigation window. Refreshing the list also refreshes its
presentation in the navigation window. presentation in the navigation window.
+ Tables. There will be a separate list for each owner. This list - Tables. There will be a separate list for each owner. This list
will be populated for the current schema owner as we connect will be populated for the current schema owner as we connect
for the first time. It will be populated for other schema for the first time. It will be populated for other schema
owners as we request information on a table owned by that owners as we request information on a table owned by that
schema owner. This list can be refreshed by typing the refresh schema owner. This list can be refreshed by typing the refresh
key stroke while a table is selected in the navigation window. key stroke while a table is selected in the navigation window.
+ Views. There will be a separate list for each owner. This list - Views. There will be a separate list for each owner. This list
will be populated for the current schema owner as we connect will be populated for the current schema owner as we connect
for the first time. It will be populated for other schema for the first time. It will be populated for other schema
owners as we request information on a view owned by that schema owners as we request information on a view owned by that schema
owner. This list can be refreshed by typing the refresh key owner. This list can be refreshed by typing the refresh key
stroke while a view is selected in the navigation window. stroke while a view is selected in the navigation window.
+ Constraints. - Constraints.
+ Columns. A list per table or view. - Columns. A list per table or view.
+ Indexes. A list per table. - Indexes. A list per table.
+ Packages. A list per schema owner. - Packages. A list per schema owner.
+ Procedures. A list per schema owner for non packaged - Procedures. A list per schema owner for non packaged
procedures, a list per package for packaged. procedures, a list per package for packaged.
+ Functions. A list per schema owner for non packaged functions, - Functions. A list per schema owner for non packaged functions,
a list per package for packaged. a list per package for packaged.
- Refreshing a list. - Refreshing a list.
The following will happen when a command to refresh a list is called. The following will happen when a command to refresh a list is called.
1. An empty list will be created. 1. An empty list will be created.
2. The command to populate this new list will be executed. 2. The command to populate this new list will be executed.
3. The contents of the new list will be compared with the 3. The contents of the new list will be compared with the
@ -289,24 +319,25 @@
node is 'selected'. node is 'selected'.
- Interacting with the database. - Interacting with the database.
+ The main engine will be the sql-<engine> functionality that is - The main engine will be the sql-<engine> functionality that is
provided as standard with GNU/Emacs distributions. provided as standard with GNU/Emacs distributions.
+ All commands will be run in the background and will use the - All commands will be run in the background and will use the
comint-redirect-send-command* functionality. comint-redirect-send-command\* functionality.
+ Lists will be read from temporary buffers. - Lists will be read from temporary buffers.
+ Presented SQL output will probably have outputting formatting - Presented SQL output will probably have outputting formatting
specified for the actual SQL interpreter being used and send to specified for the actual SQL interpreter being used and send to
the SQL output buffer. the SQL output buffer.
- Context. - Context.
There will be variables that will maintain: There will be variables that will maintain:
+ The current database and the most recent one.
+ The current schema owner and the most recent one. - The current database and the most recent one.
+ The current table/view/package/etc. and the most recent one. - The current schema owner and the most recent one.
- The current table/view/package/etc. and the most recent one.
There will be a separate pair of variables for each type of There will be a separate pair of variables for each type of
object ENODE supports. object ENODE supports.
+ The current selected item. I.e. There is a table named "FOO" - The current selected item. I.e. There is a table named "FOO"
and an index named "BAR". Both the enode-current-table, and an index named "BAR". Both the enode-current-table,
enode-current-index and enode-selected-item are nil. The user enode-current-index and enode-selected-item are nil. The user
navigates to "FOO" in the navigation window and selects it. navigates to "FOO" in the navigation window and selects it.
@ -315,11 +346,12 @@
the "BAR" index and selects it. enode-selected-item and the "BAR" index and selects it. enode-selected-item and
enode-current-index are set to "BAR", but enode-current-table enode-current-index are set to "BAR", but enode-current-table
remains set to "FOO". remains set to "FOO".
+ The previous selected item. - The previous selected item.
+ The current buffer and the previous one. - The current buffer and the previous one.
+ The current window and the previous one. - The current window and the previous one.
## A typical session might be:<a id="orgheadline7"></a>
** A typical session might be:
1. A user calls the command M-x enode. 1. A user calls the command M-x enode.
2. The user is asked to enter a connection string, and is presented 2. The user is asked to enter a connection string, and is presented
with a default which is the most recently used connection. with a default which is the most recently used connection.