JJ5-win
jj5-win is John's Windows scripting software. That's the software that does odds and ends on John's Windows systems. For other projects see projects.
Status
Simchar and delfiles have been added and released, but there's always stuff TODO.
Simchar status
I'm still thinking about and working on simchar, I wouldn't say this is complete yet. I'll probably change the character set somewhat before I'm done and have a 'recommended release' that I use to implement my 'unconfusable codes' (development of the characters for use in 'unconfusable codes' being the point of the simchar software).
Delfiles status
Delfiles is pretty much baked. I don't have any real plans to change it in any way. It's a simple little thing that just does its simple little job which it's doing just fine for me at the moment.
Administration
Contributors
People who have contributed to this project. Newest on top.
Copyright
Copyright 2012, Contributors.
License
Licensed under the New BSD license.
Resources
Source code
The repository can be browsed online:
The latest stable released version of the code is available via Subversion from:
Or if you want the latest version for development purposes:
Links
N/A.
Specifications
Functional specification
In the functional specification we describe what the project does.
jj5-win
The jj5-win project is broken into discrete 'utilities'. Each utility does something different, but all utilities in the project are available in the same way. Basically a utility has a command in the 'bin' folder that runs the command interactively. Some utilities also have installers for configuring the utility to be available as part of the Windows Shell, available via Windows Explorer context menus for instance. Generally you should put the 'bin' folder in your %PATH% environment variable and then you can run utility commands from the command line by invoking them with their name, e.g., 'simchar' or 'delfiles'. Documentation for each utility is provided separately and each utility is essentially a subproject.
Simchar
The simchar utility helps work with ASCII characters that are similar in various ways. For instance characters that look similar, or sound similar. Also characters that aren't as common and thus people might not know a name for, such as hat '^' or tilde '~' or pipe/vertical-bar '|' or hash/pound/number '#'.
The intent of simchar is to find sets of characters that will not be confusing to users. The idea being that numbers encoded in such character sets will result in less confusion and less mistakes and therefore aid in higher productivity.
See simchar technicalities for technical information about how simchar works.
Run the simchar help command for syntax and available commands, e.g.:
C:\Documents and Settings\jj5>simchar help
simchar: show's similar and distinct ASCII characters.
Syntax: simchar OPERATION
OPERATION: read, for characters that are safe to read.
hear, for characters that are safe to hear.
know, for characters people probably know.
safe, for characters that are readable, hearable and known.
code, for characters that can be used for codes.
Delfiles
The idea with delfiles is that you give it a path to a directory and it will go through the entire subtree deleting any files (but not directories) that it finds. So you can clear out all the files in a subtree and leave the directory structure in-tact.
I use delfiles when I'm upgrading a Subversion working copy with a new vendor drop. For example, say I download a new release of MediaWiki. I have the web directory of the jjwiki project checked out into a working copy in C:\Inetpub\wwwroot\jjwiki\web. I run delfiles on C:\Inetpub\wwwroot\jjwiki\web and it clears out all the files from the working copy. I then copy the latest files from the MediaWiki tarball into C:\Inetpub\wwwroot\jjwiki\web and the files are restored with the latest copy. But any files that have been removed from the latest version of MediaWiki will also now be missing from the working copy. So when I checkin the working copy TortoiseSVN will figure out that the missing files are to be deleted from the repository, new files are to be added, updated files to be updated, and anything else stays the same.
Pretty handy, huh?
See notes for implementers for installation/configuration instructions.
See delfiles technicalities for technical information about how delfiles works.
Once delfiles is correctly installed on your system you run it by right-clicking on a directory in Windows Explorer and selecting "Delete Files" from the context menu. However, if you don't install it, you can still run it from the command-line by running bin/delfiles.cmd and passing the folder you want to delete all the files from as the first argument.
bigfiles
This utility lists files in the current directory or any subfolders and sorts them according to their file size. Handy for finding big files on your system.
Technical specification
In the technical specification we describe how the project works.
jj5-win technicalities
The jj5-win system contains a 'bin' folder which comprises the interface to all jj5-win software. Basically each jj5-win utility should have a corresponding cmd/bat/exe file in the 'bin' folder that acts as the interface to that component. For example the interface to the 'simchar' utility is bin/simchar.cmd, and the interface to the 'delfiles' utility is bin/delfiles.cmd. The commands in the bin folder are assumed to be interactive, that is they are are assumed to have been run by a user from the command-line.
Generally the interactive command scripts do some minor processing of input and then defer the processing to a non-interactive command file in the utility's subfolder. For instance the interactive bin/simchar.cmd command defers processing to the non-interactive command bin/simchar/@simchar.cmd, and the interactive bin/delfiles.cmd command defers processing to the non-interactive command bin/delfiles/@delfiles.cmd. As you can see each jj5-win utility typically has a subfolder in the 'bin' directory named after the utility, e.g. bin/simchar/ for simchar and bin/delfiles/ for delfiles. This is called the "utility folder" and that is generally where the bulk of a utility's software is found.
The convention I use for interactive vs. non-interactive scripts is that a non-interactive script is named with a leading '@' character. Non-interactive scripts exit the command processor with an error level whereas interactive scripts do not exit the command processor, rather they just report to the user via stdout and pause on error.
Some "non-interactive" scripts still interact with the user. For example the non-interactive @delfiles.cmd script will still popup a message box asking the user to confirm that they really want to delete all of their files. I have no need for a truly non-interactive version of @delfiles.cmd so I haven't implemented one. If you really want a version of this utility that doesn't confirm that you want to delete all of your files then feel free to patch your own copy of the code. I'm crazy, but I'm not that crazy.
My favourite kind of Windows programming is in JavaScript running under cscript.exe, or if not cscript.exe then wscript.exe. Either environment allows me to get a lot done quickly, just the way I like things. I have a really long history with C# but I've kind of abandoned that programming environment these days. Still, don't be surprised if you see some .NET utilities creep into the jj5-win project. I might also create some native utilities using C++ one day. At time of writing though there are only two utilities in jj5-win and they are both JavaScript utilities.
Note: it might be curious to some of you that having been a programmer focused predominantly on Microsoft technology for over twelve years that my Windows utility scripts project only has two utilities in it. I mean, what have I been doing for the last twelve years!? Well, that's a good question. The answer is that I have hundreds of Windows utility scripts that I've written, but they have all been managed in my company's private repository. Only as of 2012 have I finally got the infrastructure in place to begin sharing my code. As I have the need to write more Windows utility scripts in the future I think you can feel assured that they will generally be implemented as components of this jj5-win project. Another thing to bear in mind is that personally and professionally I have spent the last four or so years moving away from Microsoft technology towards open-source alternatives such as Linux. Thus my jj5-bin project, which is the complement of this jj5-win project, where I keep my Linux utility scripts, is already considerably more feature rich than jj5-win. I expect I will continue to get more work done for my Linux jj5-bin project than I do for my jj5-win project, but I'm still a pretty big fan of Windows (XP, I ain't upgrading) on the desktop so my involvement with Microsoft technologies isn't over yet, thus, I will have call to implement a Windows utility from time to time.
Simchar technicalities
The simchar interface is bin/simchar.cmd. This interactive script takes one argument which it passes to the non-interactive bin/simchar/@simchar.cmd command. The non-interactive simchar command defers processing to simchar.wsf running in cscript.exe. The cscript.exe executable is the console-based Windows scripting environment that runs VB script or JavaScript scripts. The simchar.wsf file itself is an XML file that specifies which script components are run in the environment. In this case the script components are the simchar library, simchar.lib.js, and the simchar command-line processor, simchar.js. The simchar command processor has the 'main' method where execution starts and then it defers processing to component functions which have been factored into a JavaScript library that does not rely on the cscript.exe environment. Thus the simchar library itself should be available for use in a web browser too. And that's all there is to simchar from a technical perspective.
Delfiles technicalities
The delfiles interface is bin/delfiles.cmd. This interactive script takes one argument which it passes to the non-interactive bin/delfines/@delfiles.cmd command. The non-interactive delfiles command defers processing to delfiles.js running in wscript.exe. The wscript.exe executable is the Windows-based Windows scripting environment that runs VB script or JavaScript scripts. The delfiles.js file itself is a JavaScript file that runs as the command processor. The delfiles.js script uses the Scripting.FileSystemObject and WScript.Shell ActiveX components to prompt the user to confirm they want to delete all their files and then to go ahead and delete them (or not).
The delfiles utility can be run from the command-line passing the path of the folder you want to delete all files from as the first argument to bin/delfiles.cmd. The delfiles utility can also be installed so that a folder context menu "Delete Files" is available in Windows Explorer. To install delfiles you run the bin/delfiles/install.cmd script which will generate a VB script file that will configure your Windows registry with appropriate values for specifying the folder shell context menu item. The VB script installer defers to the RegWrite interface available on the WScript.Shell ActiveX component and writes a registry entry for delfiles into "HKCR\Folder\Shell\Delete Files". After creating and running the VBS installer the install.cmd script deletes the VBS file and cleans up after itself. I guess it's a bit dodgy that the installer just works out of the current directory rather than %TEMP% or %USERPROFILE% and if I cared enough about that I would fix it. :P
The delfiles installer defers processing of the specified folder to the non-interactive command bin/delfiles/@delfiles.cmd, thus you will see a cmd.exe window popup when you run Delete Files from Windows Explorer. If you wanted to you could probably change this easily enough so that the delfiles.js script was run directly in wscript.exe from the context menu and then there would be no such cmd.exe window visible during processing. Again, if I cared enough about this I would fix it. :P
bigfiles
The bigfiles script is a windows shell script and a JavaScript program that runs in cscript.
Notes
Notes for implementers
If you are interested in incorporating this software into your project, here's what you need to know.
Firstly, feel free to ask questions if something is unclear or missing.
Secondly, at the moment there is no downloadable tarball/zip file, nor is there an installer. To get the software you need to grab it from svn.
Installing jj5-win
On my systems I have a 'util' folder in G:\data\util. The 'util' folder is a Windows share also called 'util'. I map the 'util' folder to the U: drive with the following command:
net use u: \\bender-xp\util
Note: in this case my machine name is 'bender-xp', you would use the name of your own computer if you were following my standard. Note also that it's not important where the 'util' share is actually located, it doesn't need to be in G:\data\util as long as wherever it is it is shared as 'util'.
Now I have a U: drive. In the U: drive I create a folder called 'jj5-win'. I right-click on that folder and use TortoiseSVN to checkout the latest stable release of jj5-win from Subversion:
https://svn.jj5.net/svn/public/jjrepo/jj5-win/tags/latest
I then edit the %PATH% environment variable, by clicking through:
Start -> Right-click My Computer -> Properties -> Advanced -> Environment Variables -> System Variables -> Path -> Edit
Then in the "Variable value:" textbox prepend the text:
U:\jj5-win\bin;
If you have any cmd.exe windows open you will need to close them and reopen them to get the new value of the %PATH% variable. Your path will now include the jj5-win commands.
Installing delfiles
After you have installed jj5-win you can install delfiles. When delfiles is installed it will add a context menu item called "Delete Files" to folder context menus in Windows Explorer. To install delfiles run:
U:\jj5-win\bin\delfiles\install.cmd
Be careful with this command because it can delete all your files!
Notes for developers
If you're interested in contributing to this software, here's what you need to know:
Send your patch to jj5@jj5.net along with a statement that you are willing to be listed in the contributors section of the documentation and willing to license your contribution under the license.
For security reasons write access to jjrepo is only available for John. It's basically my private repository. If you'd like to hack on projects where you do have checkin permissions on the Subversion repository, along with infrastructure for running your code, then why not head over to ProgClub and register?
Configuring a development environment
I keep my source code on a partition mounted on the K: drive, which I call my KODE drive. Cheesy, huh?
I keep my jj5.net projects in:
K:\jj5.net
So I create a folder in the 'jj5.net' folder called 'jj5-win'. I.e.:
K:\jj5.net\jj5-win
I then use TortoiseSVN to checkout the jj5-win trunk, being:
https://svn.jj5.net/svn/public/jjrepo/jj5-win/trunk
That's pretty much it. Because I have a 'production' version of jj5-win installed on my development environment per the instructions in addition to the development code if I want to run the development version of my code I need to change directory into the development jj5-win/bin folder before running a command, e.g.:
cd /d K:\jj5.net\jj5-win\bin
If you run an installer from the development working copy, such as jj5-win/bin/delfiles/install.cmd, then your system will be configured to run the development version of your code. If you did this and then later wanted to revert your setup back to using the production version of the code then you would run the corresponding installer from the production folder, e.g. U:\jj5-win\bin\delfiles\install.cmd.
Releasing a stable version
Releases of jj5-win can only be done by John. To do a release run the jjrepo-release script from either empathy or orac. E.g.:
jj5@orac:~$ jjrepo-release jj5-win
After you've done a release don't forget to update the release notes.
If you've noticed that there is code in jj5-win/trunk that hasn't been released into jj5-win/tags/latest and you'd like John to do a release for you then feel free to drop him a line.
Release notes
Release notes are (supposed to be) added after notable releases are made. New release notes are added to the bottom of the release notes section and have a level 3 title based on the release date.
Release 2012-03-25
The jj5-win project has been released with simchar and delfiles functionality. There are presently no downloadable versions or an installer, to get the system you need to grab it from svn.
Tasks
TODO
Things to do, in rough order of priority:
- Simchar coding.
- Add a 'long' classification for characters that take a long time to say, e.g. '!' as 'exclamation point' or '?' as 'question mark'.
- Add a 'case' operation to simchar for characters that aren't confusable in either upper or lower case.
Done
Stuff that's done. Latest stuff goes on the bottom of the list.
2012-02-25
- JE: Create the project in svn.
- JE: Add delfiles.