Skip to content

Commit 89fee8a

Browse files
pponecpponec
committed
Documentation
1 parent e62f474 commit 89fee8a

File tree

6 files changed

+147
-100
lines changed

6 files changed

+147
-100
lines changed

‎README.md

Lines changed: 10 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,15 @@
1-
# DirectoryBookmarks.java
1+
# Common Script Utilities for Java 17
22

3-
Do you often switch between different directories of the file system in the character terminal?
4-
Then you might find the application described in this project useful.
5-
How does it work?
6-
In the currently visited directory you can type (in the terminal) the command `sdf d1`, where the parameter `d1` is an alphanumeric text representing the name of the bookmark.
7-
From that point on, the same directory can be returned to at any later time with the `cdf d1` command.
8-
Multiple bookmarks can be assigned to a single directory.
9-
Used bookmark names can be recycled: when the same bookmark is saved again, the original entry is silently overwritten.
10-
Bookmarks are case-sensitive and are saved in CSV text format (tab delimiter) in the user's home directory named `.directory-bookmarks.csv`, so they can be easily edited with a regular text editor.
11-
A typical reason for editing might be to change the directory structure, but the file can also be useful when transferring a project to another computer.
3+
The project contains several classes with different uses that can be run (without further dependencies)
4+
as a script (without prior compilation).
125

13-
The original implementation was created 30 years ago (sometime during 1993) - as a Unix C-shell script.
14-
After switching to Linux, I modified the script slightly for Bash and have used it in that form until now, practically every working day.
15-
This year I decided to rewrite the tool in Java for my originally planned Windows work.
16-
I then implemented the new solution in a single file (or more precisely, in a single Java class) called `DirectoryBookmarks.java` so that it could be run in Java 17 even without prior compilation.
17-
The class accepts the original data format, but some functions have been added.
18-
It makes sense to start using the above shortcuts (of application commands) after integrating it into the character terminal environment.
19-
Recall them:
6+
## Java Script Descriptions
207

21-
* `sdf d1 [comment]` : the command name was inspired by the words "Save Directory to a File".
22-
The parameter at position `d1` is mandatory and represents the bookmark name of the currently visited directory.
23-
Optionally, a text comment can be added.
24-
* `cdf d1` : the command name was inspired by the words "Change Directory using the bookmark from the File" and switches the user to the directory that is paired with the saved bookmark.
25-
Optionally, the bookmark name can be followed by a slash (without a space) and the name of one of the actual subdirectories.
26-
Example: `cdf d1/mySubdirectory`.
27-
* `ldf` : the name of the command was inspired by the words "List Directories from the File", the command prints a sorted list of all the bookmarks stored in the CSV file, including their directories and comments.
28-
* `ldf d1` : If we add the bookmark name to the previous command, we get the path of the paired directory.
29-
In Linux, this expression can also be used for copying files, for example.
30-
In Linux, the following example copies all java files from the directory labeled d1 to the directory labeled d2: `cp $(ldf d1)/*.java $(ldf d2)`.
31-
* `cpf f1 d1` : copy a file name `f1` (multiple files are allowed) to the target directory marked with the name `d1`.
32-
The function does not perform the copying itself, but delegates it to a standard operating system command.
33-
This is a simplified notation of the `cp f1 $(ldf d1)` command.
8+
* [DirectoryBookmarks](docs/DirectoryBookmarks.md) - A tool for switching directories in the character terminal using bookmarks.
9+
* [Mp3PlayerGenerator](docs/Mp3PlayerGenerator.md) - The script builds a music player for your music files in HTML format.
10+
* [SqlParamBuilder](docs/SqlParamBuilder.md) - Script template for working with relational database using JDBC.
11+
* [PPUtils](docs/PPUtils.md) - Services called from the command line for general use (find, grep, json parser, base64 utils and more).
3412

35-
Performance note: although direct use of a Java class may resemble interpreting a script, compilation is always done in the background.
36-
On newer machines, there is a barely noticeable delay, but on older machines such a delay can be distracting.
37-
To eliminate this problem, the class can compile itself and compile the result into an executable JAR file, reducing execution time by an order of magnitude.
38-
Starting Java with only the kernel module parameter had no measurable effect on the result.
13+
## License
3914

40-
Next, I will present a description of selected commands for the character terminal.
41-
Depending on the circumstances, it may be necessary to add a path to the files.
42-
In the following examples, the first expression represents the Java executable file, the second expression denotes the class with the implementation, and the third expression represents the implementation command.
43-
Commands can optionally be represented by a hyphen (one or more).
44-
You can, of course, prepare a command shortcut for each of these commands using a script or function.
45-
46-
* `java DirectoryBookmarks.java i` : (Integrate) - lists the code needed to initialize the shell before the first use. On Ubuntu, the generated code for Bash can be written to the end of the `.bashrc` file. On Windows, the class generates functions for PowerShell, for their automatic initialization you need to find a solution in the documentation. A template for integration with a terminal of type `CMD` can also be found in the project directory. As a reminder, the above abbreviations can only be used after the generated functions have been implemented in the shell. For example, by reopening the character terminal.
47-
* `java DirectoryBookmarks.java b` : (Bookmarks) Lists all bookmarks assigned to the current directory.
48-
* `java DirectoryBookmarks.java r d1` : (Remove) This command removes the bookmark specified by `d1`, leaving the referenced directory unchanged, of course.
49-
* `java DirectoryBookmarks.java f` : (Fix) Removes all bookmarks that point to nonexistent (or invisible) directories.
50-
* `java DirectoryBookmarks.java c` : (Compile) compiles the source code of the current class into a JAR file.
51-
The JAR version then needs to be run with a slightly different command, see below.
52-
* `java -jar DirectoryBookmarks.jar i` : (Integrate) - A slightly different initialization is generated for the JAR version of the program.
53-
* `java DirectoryBookmarks.java` : running without the "execute command" prints the current version and a list of available parameters.
54-
55-
The application has been released under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) and requires Java 17 or higher to run.
56-
I have already found similar tools on the Internet, but they either did not meet my expectations or were not portable to Windows.
57-
58-
## How to integrate the application
59-
60-
1. Install Java17+.
61-
2. Download the file [DirectoryBookmarks.java](https://raw.githubusercontent.com/pponec/DirectoryBookmarks/main/DirectoryBookmarks.java) to a local directory
62-
3. Open a character terminal and run commands depending on the operating system.
63-
64-
### For the Ubuntu:
65-
66-
1. `java DirectoryBookmarks.java c`
67-
2. `java -jar DirectoryBookmarks.jar i >> ~/.bashrc`
68-
3. Re-open the terminal emulator.
69-
70-
**Note:** The easiest way for Ubuntu is to download and run the installation script [installDirectoryBookmarks.sh](installDirectoryBookmarks.sh).
71-
72-
### For the Windows PowerShell:
73-
74-
1. `mkdir $HOME\Documents\WindowsPowerShell`
75-
2. `java DirectoryBookmarks.java c`
76-
3. `java -jar DirectoryBookmarks.jar i >> $HOME\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1`
77-
4. `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted`
78-
5. Re-open the PowerShell console.
79-
80-
### For the Windows Command Prompt:
81-
82-
1. `mkdir %USERPROFILE%\bin`
83-
2. `cd %USERPROFILE%\bin`
84-
3. Move the file `DirectoryBookmarks.java` to the current directory.
85-
3. `java DirectoryBookmarks.java c`
86-
4. Copy the file [init.bat](windows/init.bat) to the directory `$HOME/bin`.
87-
5. Open `regedit` and follow the instructions in the file header.
88-
6. Modify path to Java and optionally remove unnecessary auxiliary functions.
89-
90-
### For the Windows GitBash (Bash emulator):
91-
92-
1. Follow the instructions (1-4) for **Command Prompt**.
93-
2. Instal the **GitBash** from the [project page](https://gitforwindows.org/).
94-
3. Copy the file [.profile](windows/.profile) to the directory `$HOME`.
95-
4. Modify path to Java and optionally remove unnecessary auxiliary functions.
96-
97-
98-
## Similar projects:
99-
100-
* https://github.com/C-Hess/cd-bookmark
101-
* https://github.com/huyng/bashmarks
102-
* https://github.com/wting/autojump/wiki
15+
[Apache License](LICENSE), Version 2.0, [Pavel Ponec](https://github.com/pponec/Mp3PlayerGenerator/)

‎docs/DirectoryBookmarks.md

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# DirectoryBookmarks.java
2+
3+
Do you often switch between different directories of the file system in the character terminal?
4+
Then you might find the application described in this project useful.
5+
How does it work?
6+
In the currently visited directory you can type (in the terminal) the command `sdf d1`, where the parameter `d1` is an alphanumeric text representing the name of the bookmark.
7+
From that point on, the same directory can be returned to at any later time with the `cdf d1` command.
8+
Multiple bookmarks can be assigned to a single directory.
9+
Used bookmark names can be recycled: when the same bookmark is saved again, the original entry is silently overwritten.
10+
Bookmarks are case-sensitive and are saved in CSV text format (tab delimiter) in the user's home directory named `.directory-bookmarks.csv`, so they can be easily edited with a regular text editor.
11+
A typical reason for editing might be to change the directory structure, but the file can also be useful when transferring a project to another computer.
12+
13+
The original implementation was created 30 years ago (sometime during 1993) - as a Unix C-shell script.
14+
After switching to Linux, I modified the script slightly for Bash and have used it in that form until now, practically every working day.
15+
This year I decided to rewrite the tool in Java for my originally planned Windows work.
16+
I then implemented the new solution in a single file (or more precisely, in a single Java class) called `DirectoryBookmarks.java` so that it could be run in Java 17 even without prior compilation.
17+
The class accepts the original data format, but some functions have been added.
18+
It makes sense to start using the above shortcuts (of application commands) after integrating it into the character terminal environment.
19+
Recall them:
20+
21+
* `sdf d1 [comment]` : the command name was inspired by the words "Save Directory to a File".
22+
The parameter at position `d1` is mandatory and represents the bookmark name of the currently visited directory.
23+
Optionally, a text comment can be added.
24+
* `cdf d1` : the command name was inspired by the words "Change Directory using the bookmark from the File" and switches the user to the directory that is paired with the saved bookmark.
25+
Optionally, the bookmark name can be followed by a slash (without a space) and the name of one of the actual subdirectories.
26+
Example: `cdf d1/mySubdirectory`.
27+
* `ldf` : the name of the command was inspired by the words "List Directories from the File", the command prints a sorted list of all the bookmarks stored in the CSV file, including their directories and comments.
28+
* `ldf d1` : If we add the bookmark name to the previous command, we get the path of the paired directory.
29+
In Linux, this expression can also be used for copying files, for example.
30+
In Linux, the following example copies all java files from the directory labeled d1 to the directory labeled d2: `cp $(ldf d1)/*.java $(ldf d2)`.
31+
* `cpf f1 d1` : copy a file name `f1` (multiple files are allowed) to the target directory marked with the name `d1`.
32+
The function does not perform the copying itself, but delegates it to a standard operating system command.
33+
This is a simplified notation of the `cp f1 $(ldf d1)` command.
34+
35+
Performance note: although direct use of a Java class may resemble interpreting a script, compilation is always done in the background.
36+
On newer machines, there is a barely noticeable delay, but on older machines such a delay can be distracting.
37+
To eliminate this problem, the class can compile itself and compile the result into an executable JAR file, reducing execution time by an order of magnitude.
38+
Starting Java with only the kernel module parameter had no measurable effect on the result.
39+
40+
Next, I will present a description of selected commands for the character terminal.
41+
Depending on the circumstances, it may be necessary to add a path to the files.
42+
In the following examples, the first expression represents the Java executable file, the second expression denotes the class with the implementation, and the third expression represents the implementation command.
43+
Commands can optionally be represented by a hyphen (one or more).
44+
You can, of course, prepare a command shortcut for each of these commands using a script or function.
45+
46+
* `java DirectoryBookmarks.java i` : (Integrate) - lists the code needed to initialize the shell before the first use. On Ubuntu, the generated code for Bash can be written to the end of the `.bashrc` file. On Windows, the class generates functions for PowerShell, for their automatic initialization you need to find a solution in the documentation. A template for integration with a terminal of type `CMD` can also be found in the project directory. As a reminder, the above abbreviations can only be used after the generated functions have been implemented in the shell. For example, by reopening the character terminal.
47+
* `java DirectoryBookmarks.java b` : (Bookmarks) Lists all bookmarks assigned to the current directory.
48+
* `java DirectoryBookmarks.java r d1` : (Remove) This command removes the bookmark specified by `d1`, leaving the referenced directory unchanged, of course.
49+
* `java DirectoryBookmarks.java f` : (Fix) Removes all bookmarks that point to nonexistent (or invisible) directories.
50+
* `java DirectoryBookmarks.java c` : (Compile) compiles the source code of the current class into a JAR file.
51+
The JAR version then needs to be run with a slightly different command, see below.
52+
* `java -jar DirectoryBookmarks.jar i` : (Integrate) - A slightly different initialization is generated for the JAR version of the program.
53+
* `java DirectoryBookmarks.java` : running without the "execute command" prints the current version and a list of available parameters.
54+
55+
The application has been released under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) and requires Java 17 or higher to run.
56+
I have already found similar tools on the Internet, but they either did not meet my expectations or were not portable to Windows.
57+
58+
## How to integrate the application
59+
60+
1. Install Java17+.
61+
2. Download the file [DirectoryBookmarks.java](https://raw.githubusercontent.com/pponec/DirectoryBookmarks/main/DirectoryBookmarks.java) to a local directory
62+
3. Open a character terminal and run commands depending on the operating system.
63+
64+
### For the Ubuntu:
65+
66+
1. `java DirectoryBookmarks.java c`
67+
2. `java -jar DirectoryBookmarks.jar i >> ~/.bashrc`
68+
3. Re-open the terminal emulator.
69+
70+
**Note:** The easiest way for Ubuntu is to download and run the installation script [installDirectoryBookmarks.sh](installDirectoryBookmarks.sh).
71+
72+
### For the Windows PowerShell:
73+
74+
1. `mkdir $HOME\Documents\WindowsPowerShell`
75+
2. `java DirectoryBookmarks.java c`
76+
3. `java -jar DirectoryBookmarks.jar i >> $HOME\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1`
77+
4. `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted`
78+
5. Re-open the PowerShell console.
79+
80+
### For the Windows Command Prompt:
81+
82+
1. `mkdir %USERPROFILE%\bin`
83+
2. `cd %USERPROFILE%\bin`
84+
3. Move the file `DirectoryBookmarks.java` to the current directory.
85+
3. `java DirectoryBookmarks.java c`
86+
4. Copy the file [init.bat](../windows/init.bat) to the directory `$HOME/bin`.
87+
5. Open `regedit` and follow the instructions in the file header.
88+
6. Modify path to Java and optionally remove unnecessary auxiliary functions.
89+
90+
### For the Windows GitBash (Bash emulator):
91+
92+
1. Follow the instructions (1-4) for **Command Prompt**.
93+
2. Instal the **GitBash** from the [project page](https://gitforwindows.org/).
94+
3. Copy the file [.profile](../windows/.profile) to the directory `$HOME`.
95+
4. Modify path to Java and optionally remove unnecessary auxiliary functions.
96+
97+
98+
## Similar projects:
99+
100+
* https://github.com/C-Hess/cd-bookmark
101+
* https://github.com/huyng/bashmarks
102+
* https://github.com/wting/autojump/wiki

‎docs/Mp3PlayerGenerator.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Generated music player
2+
3+
Do you listen to music, language courses, or other audio files?
4+
You may find a simple audio player generated into a single HTML file useful.
5+
The advantage of such a player is the included playlist and easy portability between operating systems, so you can upload it to your mobile phone or tablet, for example.
6+
However, it is not a problem to upload it to a web server as well.
7+
8+
The generator code is written in a single text file that runs with Java (version 17 or later) without the need for compilation.
9+
To listen music, all you need is a web browser with HTML 5 and Javascript support.
10+
The procedure for generating the HTML player is as follows:
11+
12+
1. Switch to the local directory with your `mp3` files.
13+
2. Download the source file [Mp3PlayerGenerator.java](https://raw.githubusercontent.com/pponec/Mp3PlayerGenerator/main/Mp3PlayerGenerator.java) to the local directory.
14+
3. Run the command: `java Mp3PlayerGenerator.java` from a command line. If the downloaded file is not in the current directory, you need to add the path to it.
15+
4. The music player will be generated to the `index.html` file.
16+
5. After opening the file in the web browser, select the required file from displayed playlist (by the mouse) a use the space bar to pause and resume.
17+
The playlist plays over and over again.
18+
19+
![screenshot](Mp3playerScreenshot.png)
20+
21+
## More information:
22+
23+
* Homepage: https://github.com/pponec/Mp3PlayerGenerator/
24+
* License: Apache License, Version 2.0
25+
* Original solution was written in the [Kotlin script](original).

‎docs/PPUtils.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# PPUtils
2+
3+
Services called from the command line for general use.
4+
5+
For more information see a source code: [SqlExecutor.java](../src/main/java/net/ponec/script/PPUtils.java) .

‎docs/SqlParamBuilder.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# SqlParamBuilder
2+
3+
Script template for working with relational database using JDBC.
4+
5+
For more information see a source code: [SqlExecutor.java](../src/main/java/net/ponec/script/SqlExecutor.java) .

‎target/maven-archiver/pom.properties

Lines changed: 0 additions & 3 deletions
This file was deleted.

0 commit comments

Comments
 (0)