Skip to content

Update Readme.md - Added spaces so mardown can markdown #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update Readme.md - Added spaces so mardown can markdown #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Format-Script++*WhatTheFormattingDoes*++

It feels a bit wonky but we can always change it later I suppose....

##Warnings
## Warnings
I really don't think this should need to be stated but here it is anyway...

Do **NOT** just read in your source code and blindly pipe it to the cmdlets included in this module and then write the results out to the same file! I've tried to account for a large number of caveats and scenarios but I'm positive I've not thought of them all. Additionally I've written this code primarily for myself (hey, we are all selfish creatures). What seems to work fine for me may not work at all for your code.
Expand All @@ -29,19 +29,19 @@ Even though every function defaults to validating the script text after processi

Consider yourself warned.

##Logic
## Logic
Each formatting function has its own special logic. Generally though we tend to perform the actual string manipulations (script formatting) working from the bottom up. Working in reverse lets us not have to refactor token/string locations after every change made. This is especially true of token driven updates like tabifying your script with Format-ScriptFormatCodeIndentation.

There are many interesting exceptions I've run into which required some elegant and not so elegant methods to work around. In these cases I try to note in comments where I think more elegant code or algorithms could have been used (which I simply was unable to figure out). A good example is NamedBlockAST or StatementBlockAST code expansion. As there can be embedded blocks beneath each block you find you cannot simply make a change without all the extent start and end locations for every AST element below it changing. So I recreate the AST search results on every iteration for every change made. It feels... awkward but I've no better solution yet.

**Note:** *None of the functions in this module touch comments! I've no way to tell what you are intending with your comments so we do our very best to simply leave them alone. This doesn't mean that I've tested every varient of comments existing in oddball places in your code so I'll repeat that you should proceed with caution!*

##Usage
## Usage
Each function included with this module can be used individually but many of these functions were built around one another for specific purposes. Simply piping all your code through all the cmdlets exported in this module is likely to make your code even more grotesque looking than it was beforehand. Here are a few example usages which you may find handy.

**Note:** *Most functions which affect newlines in any manner (expanding code blocks, removing semicolons, et cetera) do nothing for your indentation. This was done on purpose to keep each function as basic as possible. This means you will almost always run your code through Format-ScriptFormatCodeIndentation at the very end of any transformations you are performing*!

###Example 1 - Condense and Remove 'Here Strings'
### Example 1 - Condense and Remove 'Here Strings'
[Here-strings](https://technet.microsoft.com/en-us/library/ee692792.aspx) are pretty useful variable assignments which are essentially multi-lined strings. I've used them for embedding quick templates into my code among other things. They are also totally unwieldly when it comes to making your code look nice. This is because they have strict requirements as to where the terminating here string characters must be (the start of the next line in column 0). Here is an example function with a here string assignment embedded within:

```
Expand Down Expand Up @@ -103,7 +103,7 @@ $Data = Get-Process | Sort-Object -Property CPU -Descending | select -First 5
New-CPUReport 'My Rocking Report!' $Data
```

###Example 2 - Deobfuscation
### Example 2 - Deobfuscation
A truly obfuscated bit of PowerShell code will require more than this module to deobfuscate but this module may help a little bit in making it more readable. You may 'deobfuscate' a crazy looking one-liner you came up with to just get a job done in the heat of the moment. Here is a one-liner I purposefully made look like crap. It is a function that gets the lines of a script that token kinds are found between:

```
Expand Down Expand Up @@ -181,7 +181,7 @@ Format-ScriptGetKindLines

**Note:** *I've included a vanity function you can tack on the end of any transform to move the beginning curly brace to the end of the prior line called Format-ScriptCondenseEnclosures. I prefer my code with less wasted lines but its just a personal preference so the default for all expansion transforms is to place the start of blocks ({) on their own line.*

###Example 3 - Clean Up Web Copied Code
### Example 3 - Clean Up Web Copied Code
I've done it, you've done it, we have all simply grabbed a script online, ran a cursory glance to ensure that it wasn't malicious, and repurposed it for some immediate need. There is no shame in this but often times the code quality is not only less than stellar but is also garbled by blog publishing software (if not properly embedded by the author).

If I'm wanting to quickly fixup some other person's code or make it more 'useable' for my tastes I'd probably go through the following steps:
Expand All @@ -198,14 +198,14 @@ Doing all of this doesn't fix crappy code but it sure can make it more tolerable

==TBD==

##Functions
## Functions
Here is a short list of some of the code either included or planned to be included in this module.

I've also added the technique(s) used in the function for parsing the code. I've tried to use only AST based logic where possible as it is generally 'safest'. Less 'safe' but often required is direct token manipulation. Least safe yet also often required is straight string/regex manipulation.

==TBD==

##Installing
## Installing
You can download and the current release of this script from [here](https://github.com/zloeber/FormatPowershellCode/raw/master/release/FormatPowershellCode-current.zip). Extract it into a folder called FormatPowershellCode in your modules directory.

Additionally you can install the current release of this module with PowerShellGet (in 5.0)
Expand All @@ -214,7 +214,7 @@ Additionally you can install the current release of this module with PowerShellG

Or you can use [this hack(ish) script](https://raw.githubusercontent.com/zloeber/FormatPowershellCode/master/Install.ps1) to install the module but I don't really maintain or test this script out so use at your own discretion.

##Credits
## Credits
[Haroopad](http://pad.haroopress.com/) - Sweet Markdown Editor

[PowerShell Practice and Style](https://github.com/PoshCode/PowerShellPracticeAndStyle)
Expand Down