diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..a20bea7 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,31 @@ +# GNU Kind Communications Guidelines + +by Richard Stallman +## Purpose + +The GNU Project encourages contributions from anyone who wishes to advance the development of the GNU system, regardless of gender, race, ethnic group, physical appearance, religion, cultural background, and any other demographic characteristics, as well as personal political views. + +People are sometimes discouraged from participating in GNU development because of certain patterns of communication that strike them as unfriendly, unwelcoming, rejecting, or harsh. This discouragement particularly affects members of disprivileged demographics, but it is not limited to them. Therefore, we ask all contributors to make a conscious effort, in GNU Project discussions, to communicate in ways that avoid that outcome—to avoid practices that will predictably and unnecessarily risk putting some contributors off. + +These guidelines suggest specific ways to accomplish that goal. + +## Guidelines + +- Please assume other participants are posting in good faith, even if you disagree with what they say. When people present code or text as their own work, please accept it as their work. Please do not criticize people for wrongs that you only speculate they may have done; stick to what they actually say and actually do. +- Please think about how to treat other participants with respect, especially when you disagree with them. For instance, call them by the names they use, and honor their preferences about their gender identity[1]. +- Please do not take a harsh tone towards other participants, and especially don't make personal attacks against them. Go out of your way to show that you are criticizing a statement, not a person. +- Please recognize that criticism of your statements is not a personal attack on you. If you feel that someone has attacked you, or offended your personal dignity, please don't “hit back” with another personal attack. That tends to start a vicious circle of escalating verbal aggression. A private response, politely stating your feelings as feelings, and asking for peace, may calm things down. Write it, set it aside for hours or a day, revise it to remove the anger, and only then send it. +- Please avoid statements about the presumed typical desires, capabilities or actions of some demographic group. They can offend people in that group, and they are always off-topic in GNU Project discussions. +- Please be especially kind to other contributors when saying they made a mistake. Programming means making lots of mistakes, and we all do so—this is why regression tests are useful. Conscientious programmers make mistakes, and then fix them. It is helpful to show contributors that being imperfect is normal, so we don't hold it against them, and that we appreciate their imperfect contributions though we hope they follow through by fixing any problems in them. +- Likewise, be kind when pointing out to other contributors that they should stop using certain nonfree software. For their own sake, they ought to free themselves, but we welcome their contributions to our software packages even if they don't do that. So these reminders should be gentle and not too frequent—don't nag. +- By contrast, to suggest that others run a nonfree program opposes the basic principles of GNU, so it is not allowed in GNU Project discussions. +- Please respond to what people actually said, not to exaggerations of their views. Your criticism will not be constructive if it is aimed at a target other than their real views. +- If in a discussion someone brings up a tangent to the topic at hand, please keep the discussion on track by focusing on the current topic rather than the tangent. This is not to say that the tangent is bad, or not interesting to discuss—only that it shouldn't interfere with discussion of the issue at hand. In most cases, it is also off-topic, so those interested ought to discuss it somewhere else. +- If you think the tangent is an important and pertinent issue, please bring it up as a separate discussion, with a Subject field to fit, and consider waiting for the end of the current discussion. +- Rather than trying to have the last word, look for the times when there is no need to reply, perhaps because you already made the relevant point clear enough. If you know something about the game of Go, this analogy might clarify that: when the other player's move is not strong enough to require a direct response, it is advantageous to give it none and instead move elsewhere. +- Please don't argue unceasingly for your preferred course of action when a decision for some other course has already been made. That tends to block the activity's progress. +- If others have irritated you, perhaps by disregarding these guidelines, please don't excoriate them, and especially please don't hold a grudge against them. The constructive approach is to encourage and help other people to do better. When they are trying to learn to do better, please give them plenty of chances. +- If other participants complain about the way you express your ideas, please make an effort to cater to them. You can find ways to express the same points while making others more comfortable. You are more likely to persuade others if you don't arouse ire about secondary things. +- Please don't raise unrelated political issues in GNU Project discussions, because they are off-topic. The only political positions that the GNU Project endorses are (1) that users should have control of their own computing (for instance, through free software) and (2) supporting basic human rights in computing. We don't require you as a contributor to agree with these two points, but you do need to accept that our decisions will be based on them. + +By making an effort to follow these guidelines, we will encourage more contribution to our projects, and our discussions will be friendlier and reach conclusions more easily. diff --git a/Makefile b/Makefile index 130d0ef..67efc18 100644 --- a/Makefile +++ b/Makefile @@ -9,5 +9,5 @@ md2sexpr-build: # Compile with LLVM tree-query-build: - ~/dlang/ldc-1.23.0/bin/ldc2 --link-defaultlib-shared=false -O2 -release tree-query.d interp.d query.d parser.d + ldc2 --link-defaultlib-shared=false -O2 -release tree-query.d interp.d query.d parser.d strip tree-query diff --git a/README.md b/README.md index cfe7803..4debf04 100644 --- a/README.md +++ b/README.md @@ -2,68 +2,73 @@ > This README is TODO. If you'd like to use this software in a project, **don't hestiate to reach out to me.** -Tree query is a tool that searches across indented lines. +`tree-query` is a tool that lets you execute queries on ordinary directories of files like text and Markdown, inspired by Roam Research's query syntax. It is a replacement for Roam's query system. It supports everything Roam does, except for block references. -## Installation +[Join us on Discord](https://discord.gg/7B9ywS5x) -### Build from source -Currently the only supported method. DYI style. +## Quickstart -On FreeBSD, GNU+Linux, and macOS, open Terminal and go: +**Query in current directory:** ``` -curl https://dlang.org/install.sh | bash -s +tree-query '{and: [[Page 1]] [[Page 2]]}' . ``` +[*Learn to navigate to a working directory with `cd`*](https://linuxize.com/post/linux-cd-command/) -On Windows, download and install [Git Bash](https://gitforwindows.org/): +**Query in a folder:** ``` -mkdir %USERPROFILE%\dlang -powershell.exe -Command "wget https://dlang.org/install.sh -OutFile %USERPROFILE%\dlang\install.sh" +tree-query '{and: [[Page 1]] [[Page 2]]}' /Users/steve/myfoldername/ ``` +*Learn to get the location of a folder on [macOS](https://osxdaily.com/2009/11/23/copy-a-files-path-to-the-terminal-by-dragging-and-dropping/), [Windows](https://www.top-password.com/blog/copy-full-path-of-a-folder-file-in-windows/), or [GNU+Linux](https://unix.stackexchange.com/questions/102551/mouse-shortcut-to-copy-the-path-to-a-file-in-the-gnome-file-manager).* -Then: +Or query in multiple folders and files: ``` -~/dlang/install.sh install ldc-1.23.0,dub +tree-query '{and: [[Page 1]] [[Page 2]]}' /Users/steve/myfoldername/ file1 ``` -Then `cd` into the directory where you cloned this directory and type: +**Query stdin with pipes:** ``` -make tree-query-build +cat myfile | tree-query '{and: [[Page 1]] [[Page 2]]}' ``` +[*Learn to build powerful no-code applications using pipes*](https://youtu.be/tc4ROCJYbm0?t=360) -Install to make available eveywhere: -``` -chmod 700 ~/Downloads/tree-query -sudo mv ~/Downloads/tree-query /usr/local/bin -``` +## Installation +### [Download a copy](https://github.com/CrazyPython/tree-query/releases/tag/v0.1.1) +The more convenient method. Click above for instructions. -## Quickstart +### Build from source -**Query in current directory:** +On FreeBSD, GNU+Linux, and macOS, open Terminal and go: ``` -tree-query '{and: [[Page 1]] [[Page 2]]}' . +curl https://dlang.org/install.sh | bash -s ``` -[*Learn to navigate to a working directory with `cd`*](https://linuxize.com/post/linux-cd-command/) -**Query in a folder:** +On Windows, download and install [Git Bash](https://gitforwindows.org/) and [7-Zip to C:\Program Files](https://www.7-zip.org/), then run: ``` -tree-query '{and: [[Page 1]] [[Page 2]]}' /Users/steve/myfoldername/ +mkdir %USERPROFILE%\dlang +set PATH="%PATH%;C:\Program Files\7-Zip" +set BASH="\Program Files\Git\usr\bin\bash.exe" +mkdir dlang +powershell.exe -Command "wget https://dlang.org/install.sh -OutFile dlang\install.sh" ``` -*Learn to get the location of a folder on [macOS](https://osxdaily.com/2009/11/23/copy-a-files-path-to-the-terminal-by-dragging-and-dropping/), [Windows](https://www.top-password.com/blog/copy-full-path-of-a-folder-file-in-windows/), or [GNU+Linux](https://unix.stackexchange.com/questions/102551/mouse-shortcut-to-copy-the-path-to-a-file-in-the-gnome-file-manager).* -Or query in multiple folders and files: +Then: +``` +~/dlang/install.sh install ldc-1.23.0 +``` +Then `cd` into the directory where you cloned this directory (`git clone https://github.com/CrazyPython/tree-query.git && cd tree-query`) and type: ``` -tree-query '{and: [[Page 1]] [[Page 2]]}' /Users/steve/myfoldername/ file1 +~/dlang/ldc-1.23.0/bin/ldc2 --link-defaultlib-shared=false -O2 -release tree-query.d interp.d query.d parser.d ``` -**Query stdin with pipes:** +(Non-Windows) Install to make available eveywhere: ``` -cat myfile | tree-query '{and: [[Page 1]] [[Page 2]]}' +chmod 700 tree-query +sudo mv tree-query /usr/local/bin ``` -[*Learn to build powerful no-code applications using pipes*](https://youtu.be/tc4ROCJYbm0?t=360) ## Features @@ -86,6 +91,16 @@ tree-query '{and: [[Page 1]] [[Page 2]]}' . | xclip ## Contributing +**query.d**: The logic for executing Roam queries + +**parser.d**: The Markdown/org-mode parser, which detects the indentation level of each line and uses it to emit a stream of events for a handler like `query.d` to consume. + +**tree-query.d**: The command-line tool/wrapper. Recursively parses the string `{and: [[Page 1]] [[Page 2]]}` into a tree of expressions + +**interp.d**: Recursively evaluates boolean expressions on behalf of query.d + +`tree-query` has doc comments on internals and example code demonstrating how internal APIs work. (Ctrl-F for "unittest") + Tree-query is written in [Dlang](https://dlang.org) but don't let that put you off- if you know C, C++, or Java, you'll pick it up very quickly. If you have any questions on D, feel free to go to #d on freenode or D Forums. People are very nice. @@ -103,4 +118,21 @@ A string in D is a reference to a region of immutable memory. It is a length and A struct is like a Java record or class. ## Known bugs - - Mixing tabs and spaces is not supported, unless an explicit spaces per indent specified + - Mixing tabs and spaces in the same file is not supported, unless an explicit spaces per indent specified + +## Your rights + +This is open-source software. + +We use copyleft to gurantee these rights: + +0. Free for commercial use and any other purpose +1. Freedom to remix to fit your needs: You (and if you can't code, by proxy a programmer you hire) have freedom to add new query keywords, completely change the query system, add support for new formats like org-mode, or anything else +2. Freedom to help friends by sharing +3. Freedom to share remixes, commercially and noncommercially + +I believe knowledge management is a deeply, and everyone should have freedom over their "digital brain." A digital brain is a deeply intimate and personal thing. This means you are the sovereign of your digital brain. + +Compatible with permissive licenses like Apache License, MIT License, and Mozilla Public License. + +(C) 2021. Affero General Public License v3.0 or any later version diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index d5bcd63..d6b48e2 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,12 +1,13 @@ # Release notes -## Since 0.0.1 +## 0.1.1 - Added hyperlinked documentation on usage instructions for people new to the CLI - Added missing source files, now it's possible to compile - Support for starting queries with `{query:` was enabled - Shows message when executed without a query + - Fixed build instructions for Windows and added a binary release for Windows and Mac -## 0.0.1 +## 0.1.0 - Supports `{and:`, `{or:`, `{not:`, nested arbitrarily, querying using page references - Works on any kind of indentation, including tabs, spaces. - Caveat: Mixing tabs and spaces in one file may lead to undesired results, because a tab is interpreted as one space diff --git a/parser.d b/parser.d index 68a5c2b..ae1389b 100644 --- a/parser.d +++ b/parser.d @@ -14,6 +14,7 @@ int count_indents(ref int i, string input, int spaces_per_indent=4) { for (; i < input.length; ++i) { switch (input[i]) { case ' ': nspaces++; break; + case '*': nspaces++; break; case '\t': nspaces += spaces_per_indent; break; // Commented out makes it only accept "-" //case '-': return nspaces / spaces_per_indent;